Improve CLI resilience and JSON output

Author: Arlowen

.github/workflows/release.yml

@@ -43,7 +43,7 @@ jobs:
           done
           (
             cd dist
-            sha256sum ./*.tar.gz > checksums.txt
+            sha256sum cloudcanal_*.tar.gz > checksums.txt
           )
 
       - name: Publish GitHub Release

README.md

@@ -32,6 +32,7 @@ curl -fsSL https://raw.githubusercontent.com/Arlowen/cloudcanal-openapi-cli/main
 ```
 
 这个一键安装脚本会从 GitHub Releases 下载预编译二进制，不需要本机安装 Go。
+下载后会自动校验 release 中的 `checksums.txt`，再执行安装。
 默认会把二进制安装到 `~/.local/share/cloudcanal-openapi-cli/bin/cloudcanal`。
 
 一键卸载：
@@ -49,17 +50,37 @@ curl -fsSL https://raw.githubusercontent.com/Arlowen/cloudcanal-openapi-cli/main
 ## 使用方式
 
 详细命令、参数和示例请看上面的使用说明文档。
+如需机器可读输出，可以在命令后追加 `--output json`，例如：
+
+```bash
+cloudcanal jobs list --type SYNC --output json
+```
 
 ## 初始化配置
 
 第一次启动会进入初始化向导，配置文件保存到 `~/.cloudcanal/config.json`。配置格式、字段含义和命令参数说明见详细文档。
 
+高级网络选项也可以直接写进配置文件：
+
+```json
+{
+  "apiBaseUrl": "https://cc.example.com",
+  "accessKey": "your-ak",
+  "secretKey": "your-sk",
+  "language": "en",
+  "httpTimeoutSeconds": 15,
+  "httpReadMaxRetries": 2,
+  "httpReadRetryBackoffMillis": 300
+}
+```
+
 ## 开发
 
 发布：
 
 - 推送 tag，例如 `v0.1.0`
 - GitHub Actions 会自动构建并发布 `darwin/linux + amd64/arm64` 的 release 资产
+- Release 会同时生成 `checksums.txt`，供一键安装脚本做完整性校验
 
 只编译：
 

cmd/cloudcanal/main.go

@@ -10,7 +10,6 @@ import (
 	"cloudcanal-openapi-cli/internal/console"
 	"cloudcanal-openapi-cli/internal/i18n"
 	"cloudcanal-openapi-cli/internal/repl"
-	"cloudcanal-openapi-cli/internal/util"
 )
 
 func main() {
@@ -35,14 +34,14 @@ func main() {
 	shell := repl.NewShell(io, runtime)
 	if len(os.Args) > 1 {
 		if err := shell.ExecuteArgs(os.Args[1:]); err != nil {
-			io.Println(i18n.T("common.fatalErrorPrefix", util.SummarizeError(err)))
+			shell.PrintFatalError(err)
 			os.Exit(1)
 		}
 		return
 	}
 
 	if err := shell.Run(); err != nil {
-		io.Println(i18n.T("common.fatalErrorPrefix", util.SummarizeError(err)))
+		shell.PrintFatalError(err)
 		os.Exit(1)
 	}
 }

docs/cloudcanal-cli-usage.md

@@ -15,6 +15,7 @@ cloudcanal
 ```bash
 cloudcanal jobs list
 cloudcanal datasources list --type MYSQL
+cloudcanal jobs list --type SYNC --output json
 ```
 
 如果还没有安装到系统命令，也可以直接执行本地二进制：
@@ -32,6 +33,7 @@ curl -fsSL https://raw.githubusercontent.com/Arlowen/cloudcanal-openapi-cli/main
 说明：
 
 - 当前一键安装会从 GitHub Releases 下载预编译二进制
+- 下载后会自动校验 release 里的 `checksums.txt`
 - 不需要本机安装 `Go`
 - 默认会把二进制安装到 `~/.local/share/cloudcanal-openapi-cli/bin/cloudcanal`
 - 之后会自动完成命令、PATH 和补全安装
@@ -57,7 +59,10 @@ curl -fsSL https://raw.githubusercontent.com/Arlowen/cloudcanal-openapi-cli/main
   "apiBaseUrl": "https://cc.example.com",
   "accessKey": "your-ak",
   "secretKey": "your-sk",
-  "language": "en"
+  "language": "en",
+  "httpTimeoutSeconds": 15,
+  "httpReadMaxRetries": 2,
+  "httpReadRetryBackoffMillis": 300
 }
 ```
 
@@ -67,6 +72,9 @@ curl -fsSL https://raw.githubusercontent.com/Arlowen/cloudcanal-openapi-cli/main
 - `accessKey` 是访问密钥 ID
 - `secretKey` 是访问密钥 Secret，不会在 `config show` 中明文展示
 - `language` 是 CLI 文案语言，支持 `en` 和 `zh`
+- `httpTimeoutSeconds` 是单次 HTTP 请求超时秒数，默认 `10`
+- `httpReadMaxRetries` 是只读请求的最大重试次数，默认 `0`
+- `httpReadRetryBackoffMillis` 是只读请求的首次退避毫秒数，默认 `250`
 
 ## 基本命令
 
@@ -127,12 +135,14 @@ cloudcanal completion bash
 - `--desc <desc>`: 按任务描述过滤
 - `--source-id <id>`: 按源数据源 ID 过滤
 - `--target-id <id>`: 按目标数据源 ID 过滤
+- `--output <text|json>`: 输出文本表格或 JSON
 
 示例：
 
 ```bash
 cloudcanal jobs list --type SYNC --name demo
 cloudcanal jobs list --desc "nightly sync"
+cloudcanal jobs list --type SYNC --output json
 ```
 
 `jobs show <jobId>`
@@ -256,6 +266,7 @@ cloudcanal job-config specs --type SYNC --initial-sync=true
 ## 使用建议
 
 - 带空格的参数值请使用引号包裹，例如 `--desc "nightly sync"`
+- 可以在查询类命令后追加 `--output json` 获取机器可读结果
 - 交互模式下如果终端支持行编辑，可以直接使用 `TAB` 补全命令、子命令和常见参数
 - 可以先执行 `cloudcanal help` 查看帮助主题，再执行 `cloudcanal help jobs` 这类子帮助查看参数含义
 - 如果想切换中文或英文文案，可执行 `cloudcanal lang set zh` 或 `cloudcanal lang set en`

internal/app/runtime.go

@@ -118,9 +118,7 @@ func (r *Runtime) validateConfig(cfg config.AppConfig) error {
 	if err != nil {
 		return err
 	}
-	service := datajob.NewService(client)
-	_, err = service.ListJobs(datajob.ListOptions{})
-	return err
+	return client.ProbeAuthentication()
 }
 
 func (r *Runtime) activate(cfg config.AppConfig) error {

internal/cluster/service.go

@@ -49,12 +49,12 @@ type listResponse struct {
 
 func (s *Service) List(options ListOptions) ([]Cluster, error) {
 	var out listResponse
-	if err := s.client.PostJSON(listPath, listRequest{
+	if err := s.client.PostJSONWithOptions(listPath, listRequest{
 		CloudOrIDCName: options.CloudOrIDCName,
 		ClusterDesc:    options.ClusterDesc,
 		ClusterName:    options.ClusterName,
 		Region:         options.Region,
-	}, &out); err != nil {
+	}, &out, openapi.RequestOptions{Retryable: true}); err != nil {
 		return nil, err
 	}
 	if err := openapi.EnsureSuccess(out.Response, "failed to list clusters"); err != nil {

internal/config/config.go

@@ -8,13 +8,22 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"time"
+)
+
+const (
+	defaultHTTPTimeoutSeconds         = 10
+	defaultHTTPReadRetryBackoffMillis = 250
 )
 
 type AppConfig struct {
-	APIBaseURL string `json:"apiBaseUrl"`
-	AccessKey  string `json:"accessKey"`
-	SecretKey  string `json:"secretKey"`
-	Language   string `json:"language,omitempty"`
+	APIBaseURL                 string `json:"apiBaseUrl"`
+	AccessKey                  string `json:"accessKey"`
+	SecretKey                  string `json:"secretKey"`
+	Language                   string `json:"language,omitempty"`
+	HTTPTimeoutSeconds         int    `json:"httpTimeoutSeconds,omitempty"`
+	HTTPReadMaxRetries         int    `json:"httpReadMaxRetries,omitempty"`
+	HTTPReadRetryBackoffMillis int    `json:"httpReadRetryBackoffMillis,omitempty"`
 }
 
 func (c AppConfig) Validate() error {
@@ -31,6 +40,15 @@ func (c AppConfig) Validate() error {
 	if normalized := i18n.NormalizeLanguage(c.Language); normalized == "" && strings.TrimSpace(c.Language) != "" {
 		return errors.New(i18n.T("config.languageUnsupported"))
 	}
+	if c.HTTPTimeoutSeconds < 0 {
+		return errors.New(i18n.TFor(language, "config.httpTimeoutSecondsInvalid"))
+	}
+	if c.HTTPReadMaxRetries < 0 {
+		return errors.New(i18n.TFor(language, "config.httpReadMaxRetriesInvalid"))
+	}
+	if c.HTTPReadRetryBackoffMillis < 0 {
+		return errors.New(i18n.TFor(language, "config.httpReadRetryBackoffMillisInvalid"))
+	}
 
 	parsed, err := url.Parse(strings.TrimSpace(c.APIBaseURL))
 	if err != nil {
@@ -63,6 +81,35 @@ func (c AppConfig) WithDefaults() AppConfig {
 	return c
 }
 
+func (c AppConfig) HTTPTimeout() time.Duration {
+	return time.Duration(c.HTTPTimeoutSecondsValue()) * time.Second
+}
+
+func (c AppConfig) HTTPTimeoutSecondsValue() int {
+	if c.HTTPTimeoutSeconds <= 0 {
+		return defaultHTTPTimeoutSeconds
+	}
+	return c.HTTPTimeoutSeconds
+}
+
+func (c AppConfig) HTTPReadMaxRetriesValue() int {
+	if c.HTTPReadMaxRetries <= 0 {
+		return 0
+	}
+	return c.HTTPReadMaxRetries
+}
+
+func (c AppConfig) HTTPReadRetryBackoff() time.Duration {
+	return time.Duration(c.HTTPReadRetryBackoffMillisValue()) * time.Millisecond
+}
+
+func (c AppConfig) HTTPReadRetryBackoffMillisValue() int {
+	if c.HTTPReadRetryBackoffMillis <= 0 {
+		return defaultHTTPReadRetryBackoffMillis
+	}
+	return c.HTTPReadRetryBackoffMillis
+}
+
 type Service struct {
 	path string
 }

internal/consolejob/service.go

@@ -57,7 +57,7 @@ type queryResponse struct {
 
 func (s *Service) Get(consoleJobID int64) (Job, error) {
 	var out queryResponse
-	if err := s.client.PostJSON(queryPath, queryRequest{ConsoleJobID: consoleJobID}, &out); err != nil {
+	if err := s.client.PostJSONWithOptions(queryPath, queryRequest{ConsoleJobID: consoleJobID}, &out, openapi.RequestOptions{Retryable: true}); err != nil {
 		return Job{}, err
 	}
 	if err := openapi.EnsureSuccess(out.Response, "failed to query console job"); err != nil {

internal/datajob/service.go

@@ -128,7 +128,7 @@ type queryJobSchemaResponse struct {
 
 func (s *Service) ListJobs(options ListOptions) ([]Job, error) {
 	var out listJobsResponse
-	if err := s.client.PostJSON(listPath, newListJobsRequest(options), &out); err != nil {
+	if err := s.client.PostJSONWithOptions(listPath, newListJobsRequest(options), &out, openapi.RequestOptions{Retryable: true}); err != nil {
 		return nil, err
 	}
 	if err := openapi.EnsureSuccess(out.Response, "failed to list jobs"); err != nil {
@@ -142,7 +142,7 @@ func (s *Service) ListJobs(options ListOptions) ([]Job, error) {
 
 func (s *Service) GetJob(jobID int64) (Job, error) {
 	var out queryJobResponse
-	if err := s.client.PostJSON(queryPath, jobActionRequest{JobID: jobID}, &out); err != nil {
+	if err := s.client.PostJSONWithOptions(queryPath, jobActionRequest{JobID: jobID}, &out, openapi.RequestOptions{Retryable: true}); err != nil {
 		return Job{}, err
 	}
 	if err := openapi.EnsureSuccess(out.Response, "failed to query job"); err != nil {
@@ -153,7 +153,7 @@ func (s *Service) GetJob(jobID int64) (Job, error) {
 
 func (s *Service) GetJobSchema(jobID int64) (JobSchema, error) {
 	var out queryJobSchemaResponse
-	if err := s.client.PostJSON(schemaPath, jobActionRequest{JobID: jobID}, &out); err != nil {
+	if err := s.client.PostJSONWithOptions(schemaPath, jobActionRequest{JobID: jobID}, &out, openapi.RequestOptions{Retryable: true}); err != nil {
 		return JobSchema{}, err
 	}
 	if err := openapi.EnsureSuccess(out.Response, "failed to query job schema"); err != nil {

internal/datasource/service.go

@@ -58,7 +58,7 @@ type listResponse struct {
 
 func (s *Service) List(options ListOptions) ([]DataSource, error) {
 	var out listResponse
-	if err := s.client.PostJSON(listPath, newListRequest(options), &out); err != nil {
+	if err := s.client.PostJSONWithOptions(listPath, newListRequest(options), &out, openapi.RequestOptions{Retryable: true}); err != nil {
 		return nil, err
 	}
 	if err := openapi.EnsureSuccess(out.Response, "failed to list data sources"); err != nil {