别再让后端手写脚本了：我搭了一套可复用的企业 CLI 基座，命令扩展靠 YAML

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// cmd/root.go 核心逻辑
func Execute() {
    root := &cobra.Command{
        Use:   "cli",
        Short: "企业内部统一命令行工具",
    }
    
    // 挂核心命令
    root.AddCommand(authCmd)
    root.AddCommand(versionCmd)
    
    // 加载 YAML 动态命令
    loadYAMLCommands(root)
    
    root.Execute()
}

func loadYAMLCommands(root *cobra.Command) {
    specs, err := runtime.LoadSpecs()  // 从 embed 读取 YAML
    if err != nil {
        return  // YAML 加载失败不影响核心命令
    }
    
    commands := runtime.BuildCommands(specs)  // YAML 转 Cobra 命令
    for _, cmd := range commands {
        root.AddCommand(cmd)
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# specs/groups/order/group.yaml
group: order
short: "订单相关命令"
domains:
  test: https://api.test.example.com
  prod: https://api.example.com
services:
  order-service:
    test: https://api.test.example.com/order
    prod: https://api.example.com/order

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# specs/groups/order/commands/list.yaml
group: order
command: list
short: "查询订单列表"
request:
  method: GET
  service: order-service
  path: /list
flags:
  - name: keyword
    type: string
    short: k
    usage: "关键词搜索"
  - name: biz-ids
    type: int_array
    short: i
    usage: "业务 ID 列表"
  - name: limit
    type: int
    default: 20
    usage: "返回数量上限"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ ./cli order list --help
查询订单列表

Usage:
  cli order list [flags]

Flags:
  -k, --keyword string    关键词搜索
  -i, --biz-ids int[]     业务 ID 列表
      --limit int         返回数量上限 (default 20)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// internal/runtime/executor.go 核心逻辑
func (e *Executor) Execute(cmd *CommandSpec, args map[string]interface{}) (*Response, error) {
    // 1. 构建请求 URL
    baseURL := cmd.ResolveHTTPBaseURL()  // 按环境回退
    url := baseURL + cmd.Request.Path
    
    // 2. 构建请求参数
    var req *http.Request
    if cmd.Request.Method == "GET" {
        query := buildQuery(args)  // 参数转 query string
        req, _ = http.NewRequest("GET", url+"?"+query, nil)
    } else {
        body := buildBody(args)    // 参数转 JSON body
        req, _ = http.NewRequest("POST", url, bytes.NewReader(body))
    }
    
    // 3. 用带 401 refresh 的 client 发送
    client := NewClientWith401(e.store)
    resp, err := client.Do(req)
    
    // 4. 统一错误处理
    if err != nil {
        return nil, fmt.Errorf("请求失败：%w", err)
    }
    
    return parseResponse(resp)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

// internal/httpx/transport.go
func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error) {
    // 从 profile 读取 token 和 device_id
    profile, _ := t.store.GetProfile()
    
    // 注入统一 Header
    req.Header.Set("Authorization", "Bearer "+profile.Token)
    req.Header.Set("X-Device-Id", profile.DeviceID)
    req.Header.Set("X-Request-Id", generateRequestID())
    req.Header.Set("X-Source", "cli")
    req.Header.Set("X-Client-Version", getVersion())
    
    // OAuth 链路不带 X-Device-Id，业务链路带
    if t.isOAuthRequest(req) {
        req.Header.Del("X-Device-Id")
    }
    
    return t.base.RoundTrip(req)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// internal/httpx/client.go
func NewClientWith401(store Store) *http.Client {
    return &http.Client{
        Transport: &RefreshTransport{
            store: store,
            base:  http.DefaultTransport,
        },
    }
}

type RefreshTransport struct {
    store  Store
    base   http.RoundTripper
    once   bool  // 只刷新一次
}

func (t *RefreshTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    resp, err := t.base.RoundTrip(req)
    if err != nil {
        return nil, err
    }
    
    // 401 且还没刷新过，刷新一次再重试
    if resp.StatusCode == 401 && !t.once {
        t.once = true
        err := refreshToken(t.store)  // 调用刷新接口
        if err != nil {
            return resp, nil  // 刷新失败，返回原 401
        }
        
        // 重试一次
        return t.base.RoundTrip(req)
    }
    
    return resp, nil
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

#!/bin/bash
# scripts/build-with-oauth.sh

ENV=${1:-test}  # 默认 test 环境
SUPPORTED_ENVS=("test" "prod" "uat")

# 1. 校验环境参数
if [[ ! " ${SUPPORTED_ENVS[@]} " =~ " ${ENV} " ]]; then
    echo "错误：不支持的环境 $ENV"
    exit 1
fi

# 2. 生成临时 Go 源码注入 OAuth 凭据
cat > cmd/oauth_injected.go <<EOF
//go:build $ENV
// +build $ENV

package cmd

const (
    OAuthClientID = "$OAUTH_CLIENT_ID_${ENV}"
    OAuthClientSecret = "$OAUTH_CLIENT_SECRET_${ENV}"
)
EOF

# 3. 多平台矩阵打包
PLATFORMS=("darwin-arm64" "darwin-amd64" "linux-amd64" "windows-amd64")
for platform in "${PLATFORMS[@]}"; do
    GOOS=$(echo $platform | cut -d'-' -f1)
    GOARCH=$(echo $platform | cut -d'-' -f2)
    
    CGO_ENABLED=0 GOOS=$GOOS GOARCH=$GOARCH go build \
        -tags $ENV \
        -o dist/cli-${ENV}-${platform} \
        .
done

# 4. 清理临时文件
rm -f cmd/oauth_injected.go

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# 1. 新增 YAML 命令后，验证动态注册
go build -o cli .
./cli <group> <command> --help

# 2. 打包 test 环境后验证登录
./scripts/build-with-oauth.sh test
./dist/cli-test-darwin-arm64 auth login

# 3. 手动观察 profile 文件
# 位置：~/.cli/profiles/<profile>.json
# 确认 token/device_id/env/base_url 存在

# 4. 故意触发业务请求 401
# 确认 CLI 只 refresh 一次、retry 一次

# 5. 新增一个 group + command 规格
# 不改核心代码也能扩一个业务命令