用 Go 构建多命令 CLI 时，用 Cobra 组织命令…

在 Go 中开发生产级多命令 CLI，需要 POSIX 子命令、flags/env/config 优先级配置、shell 补全和命令测试时使用。

适用场景

解决思路

1. 采用 Cobra 的 `APPNAME VERB NOUN --FLAG` 命令结构，创建 `cmd/root.go` 中的 `rootCmd`，设置 `Use`、`Short`、`Long`，并在 `Execute()` 中调用 `rootCmd.Execute()`，出错时写入 `os.Stderr` 并 `os.Exit(1)`。
2. 在 `init()` 中调用 `cobra.OnInitialize(initConfig)`，确保命令执行前先加载配置。
3. 为 root 命令定义 persistent flags：`--config`（默认 `$HOME/.myapp.yaml`）和 `--verbose`，并用 `viper.BindPFlag` 分别绑定 `config` 和 `verbose`。
4. 在 `initConfig()` 中，如果 `cfgFile` 非空则 `viper.SetConfigFile(cfgFile)`；否则用 `os.UserHomeDir()` 取得 home，`viper.AddConfigPath(home)`、`viper.AddConfigPath('.')`、`viper.SetConfigType('yaml')`、`viper.SetConfigName('.myapp')`。
5. 在 `initConfig()` 中设置 `viper.SetEnvPrefix('MYAPP')`、`viper.AutomaticEnv()`，并调用 `viper.ReadInConfig()`；若读取成功且 `verbose` 为真，打印 `viper.ConfigFileUsed()`。
6. 创建子命令时使用 `Use: 'deploy [environment]'`、`Short`、`Long`，用 `Args: cobra.ExactArgs(1)` 限制参数数量，用 `ValidArgs: []string{'dev','staging','production'}` 提供有效值。
7. 在子命令的 `PreRunE` 中做校验，例如环境为 `production` 且 `force` 不为真时返回错误；在 `RunE` 中读取 `env`、`region`、`force` 并调用实际逻辑；在 `PostRunE` 中做清理或通知。
8. 在子命令 `init()` 中调用 `rootCmd.AddCommand(deployCmd)`；定义 local flags：`deployCmd.Flags().StringP('region','r','us-east-1','AWS region')` 和 `deployCmd.Flags().BoolP('force','f',false,'Force deployment without confirmation')`；再用 `viper.BindPFlag` 绑定 `region` 和 `force`。
9. 区分 persistent flags 与 local flags：`rootCmd.PersistentFlags()` 对命令及所有子命令可用，用于 `--config`、`--verbose`；`xxxCmd.Flags()` 只对当前命令可用，用于 `--region`、`--force`。
10. 使用 `MarkFlagRequired('region')` 标记必填 flag；使用 `MarkFlagsRequiredTogether('username','password')` 标记必须同时出现；使用 `MarkFlagsMutuallyExclusive('json','yaml')` 标记互斥 flag。
11. 用 Cobra hooks 控制执行顺序：`PersistentPreRunE` 做全局 setup，`PreRunE` 做校验和准备，`RunE` 做主逻辑，`PostRunE` 做清理，`PersistentPostRunE` 做全局收尾；优先使用带 `E` 的版本（`RunE`、`PreRunE`、`PostRunE`）。
12. 让 Viper 按优先级合并配置：显式 `viper.Set` > 命令行 flags（`viper.BindPFlag`） > 环境变量（`MYAPP_KEY=value`） > 配置文件（`~/.myapp.yaml`、`./config.yaml`） > Key/Value Store（etcd、Consul，可选） > 默认值（`viper.SetDefault`）。
13. 在 `initConfig()` 中先设置默认值：`viper.SetDefault('port',8080)`、`viper.SetDefault('database.host','localhost')`、`viper.SetDefault('database.port',5432)`。
14. 设置配置文件搜索：`viper.SetConfigName('config')`、`viper.SetConfigType('yaml')`、`viper.AddConfigPath('/etc/myapp/')`、`viper.AddConfigPath('$HOME/.myapp')`、`viper.AddConfigPath('.')`。
15. 设置环境变量映射：`viper.SetEnvPrefix('MYAPP')` 和 `viper.AutomaticEnv()`，使 `port` → `MYAPP_PORT`、`database.host` → `MYAPP_DATABASE_HOST`、`database.port` → `MYAPP_DATABASE_PORT`、`aws.s3.region` → `MYAPP_AWS_S3_REGION`。
16. 对非标准环境变量名使用手动绑定：`viper.BindEnv('database.host','DB_HOST')`、`viper.BindEnv('database.password','DB_PASSWORD')`。
17. 读取配置文件时用 `viper.ReadInConfig()`；若返回 `viper.ConfigFileNotFoundError` 则允许继续使用默认值和环境变量；若是其他读取错误则返回错误。
18. 支持多种配置格式：YAML、JSON、TOML、HCL、INI、envfile、Java properties；例如 `config.yaml` 中写 `port`、`log_level`、`database.host`、`database.port`、`aws.region`、`aws.s3.bucket`。
19. 访问配置值使用类型化方法：`viper.GetInt('port')`、`viper.GetString('database.host')`、`viper.GetString('aws.s3.bucket')`；用 `viper.IsSet('database.ssl_mode')` 判断是否设置。
20. 用 `viper.Unmarshal(&config)` 把配置解到 struct，字段使用 `mapstructure` tag 映射，例如 port 字段和 log_level 字段。
21. Cobra + Viper 集成时，先定义 flags，再逐个 `viper.BindPFlag('log_level', rootCmd.Flags().Lookup('log-level'))`；也可用 `viper.BindPFlags(rootCmd.Flags())` 批量绑定；推荐混合：全局 persistent flags 全局绑定，local flags 在各命令 `init()` 中绑定。
22. 在 `PersistentPreRunE` 中加载并校验配置：检查 `viper.IsSet('api_key')`，按 `viper.GetString('log_level')` 设置日志，按 `viper.GetString('api_key')` 初始化 API client，出错返回带上下文的错误。
23. 添加 `completion` 子命令，支持 `bash|zsh|fish|powershell`；用 `ValidArgs` 指定 shell 列表，`Args: cobra.ExactValidArgs(1)`，`DisableFlagsInUseLine: true`。
24. 在 completion 子命令中按参数调用：`cmd.Root().GenBashCompletion(os.Stdout)`、`GenZshCompletion(os.Stdout)`、`GenFishCompletion(os.Stdout, true)`、`GenPowerShellCompletionWithDesc(os.Stdout)`。
25. 为 shell completion 提供安装说明：bash 用 `source <(myapp completion bash)` 并追加到 `~/.bashrc`；zsh 用 `source <(myapp completion zsh)` 并追加到 `~/.zshrc`；fish 用 `myapp completion fish | source` 或写入 `~/.config/fish/completions/myapp.fish`；PowerShell 用 `myapp completion powershell | Out-String | Invoke-Expression` 或加入 profile。
26. 为命令参数提供动态补全：设置 `ValidArgsFunction` 返回候选列表（如 `dev`、`staging`、`production`）和 `cobra.ShellCompDirectiveNoFileComp`。
27. 为 flag 提供动态补全：用 `deployCmd.RegisterFlagCompletionFunc('region', ...)` 返回 `us-east-1`、`us-west-2`、`eu-west-1` 和 `ShellCompDirectiveNoFileComp`。
28. 编写用户可操作的错误信息：不要只写 `connection failed`，而要说明无法连接到的 host:port，并列出检查项，如数据库是否运行、凭证 `MYAPP_DB_PASSWORD`、网络/防火墙规则。
29. 对缺失配置给出修复建议，例如未设置 `api_key` 时提示 `export MYAPP_API_KEY=your-key` 或写入 `~/.myapp.yaml`。
30. 为耗时操作添加进度指示，可使用 `github.com/briandowns/spinner`，设置 `s.Suffix`，`s.Start()`，用 `defer s.Stop()`，失败时先停止再返回错误，成功后打印 `✓ Deployment successful`。
31. 实现多格式输出：用 `encoding/json` 输出 JSON（`enc.SetIndent('', ' ')`），用 `github.com/olekukonko/tablewriter` 输出表格，设置表头 `ID`、`Name`、`Status`，未知格式返回错误。
32. 分离用户输出和日志：用户输出写 `stdout`，日志和错误写 `stderr`；例如 `out = os.Stdout`、`logger = log.New(os.Stderr, '[myapp] ', log.LstdFlags)`；仅在 `verbose` 时输出调试日志。
33. 测试 CLI 命令时写 `executeCommand(root *cobra.Command, args ...string)` 辅助函数：用 `bytes.Buffer`，`root.SetOut(buf)`、`root.SetErr(buf)`、`root.SetArgs(args)`，调用 `root.Execute()` 并返回输出和错误。
34. 用表驱动测试覆盖命令：测试 `deploy dev` 成功、`deploy production` 无 `--force` 失败、`deploy production --force` 成功，并断言输出包含预期文本。
35. 测试 Viper 配置前调用 `viper.Reset()` 清理状态，用 `viper.Set('region','eu-west-1')`、`viper.Set('api_key','test-key-123')` 注入测试配置，再执行命令并断言输出包含配置值。
36. 测试输出格式时捕获 stdout：保存 `oldStdout := os.Stdout`，用 `os.Pipe()` 替换 `os.Stdout`，执行命令后关闭 writer，读取 pipe 到 buffer，断言输出包含 `ID`、`Name` 等。
37. 避免在 `Run`/`PreRun`/`PostRun` 中吞掉错误；使用 `RunE`/`PreRunE`/`PostRunE` 返回 error，让 Cobra 统一处理错误展示和退出码。
38. 避免手动混合配置来源；把 flags 绑定到 Viper，设置 `SetEnvPrefix`、`AutomaticEnv`、`SetDefault`，然后统一用 `viper.GetInt('port')` 读取，让 Viper 处理优先级。
39. 避免忘记 `viper.BindPFlag`；定义 flag 后必须绑定，否则 `viper.GetString('region')` 不会读取命令行 flag。
40. 为 CLI 命令编写测试，不要因为只是 CLI 而跳过测试。
41. 生产结构参考：`myapp/cmd/root.go`、`cmd/deploy.go`、`cmd/status.go`、`cmd/completion.go`、`main.go`、`config.yaml`、`go.mod`；`main.go` 只调用 `cmd.Execute()`。
42. 构建和安装：开发用 `go run main.go deploy staging --region us-west-2`；生产用 `go build -o myapp`；全局安装用 `go install`；启用 bash 补全用 `myapp completion bash > /etc/bash_completion.d/myapp`。
43. 用成功标准自检：命令遵循 POSIX 约定；配置优先级为 flags > env > config > defaults；所有 flags 都绑定到 Viper；为主流 shell 生成补全；错误信息可操作；CLI 命令有完整测试；help 文本自动生成且准确；用 `PersistentPreRunE` 做全局 setup/校验；区分 stdout 用户输出与 stderr 日志；配置文件可选，CLI 可仅靠 flags/env 运行。
44. 需要实时重载配置时，使用 Viper 的 watch config file changes 能力监控配置文件变化并更新运行时配置。

适用边界 · 注意事项

• 简单单命令脚本、只有 1-2 个 flag 的内部工具或一次性原型脚本，不需要 Cobra/Viper，直接用标准 `flag` 包即可。
• 配置全部硬编码，或只从命令行读取且不需要多来源优先级时，不需要 Viper。
• CLI 很少使用、选项很少、纯内部工具或临时脚本，不需要添加 shell completion。