用途:为在 Go 中开发命令行应用提供统一规范,当前使用 Cobra 组织命令结构,使用 Huh 实现交互式界面。
主要能力与约定:命令组织上,每个命令一个文件放在 cmd/ 下,文件名与命令名一致(camelCase);所有命令在各自的 init() 中通过 rootCmd.AddCommand() 注册。新增命令时创建对应文件,定义含 Use 与 Short 字段的 cobra.Command 变量,在 init() 中注册、定义标志并绑定 Viper,需抑制 init lint://nolint:gochecknoinits // Cobra requires an init function to set up the command structure.
标志约定:全局标志用 rootCmd.PersistentFlags(),局部标志用 cmd.Flags();统一使用 StringVar/BoolVar/CountVarP 指针绑定;每个标志通过 viper.BindPFlag("name", cmd.Flags().Lookup("name")) 绑定 Viper;标志名用 kebab-case,如 --git-clone-protocol;提供有意义的默认值与描述。
初始化与错误处理:全局依赖在 root.go 中通过 cobra.OnInitialize() 初始化,顺序重要,后续初始化器可能依赖前面的。命令使用 Run 而非 RunE,错误用 logger.Error() + os.Exit(1) 内联处理,成功用 logger.Success();Run 保持精简,业务逻辑委托给 lib/。
信号与清理:信号处理器在 root.go 的 setupCleanup() 注册;根命令的 PersistentPostRun 处理成功完成后的清理;错误/信号路径使用单独的 cleanupAndExit();所有退出路径都要清理资源(日志器、临时文件)。
非交互与输出模式:--non-interactive 禁用所有交互提示(Huh 表单)与进度指示,改用自动默认值或显式标志值,便于 CI/CD 与脚本使用。输出模式包括:默认进度模式(层级 spinner,隐藏命令输出)、--plain 纯文本模式(简单日志,隐藏命令输出)、-v/-vv 透传模式(显示全部命令输出)、--non-interactive 透传模式(显示全部命令输出);解析逻辑见 root.go 的 GetDisplayMode()。
关键规则:命令之间不应互相导入,通过 cmd/ 中的包级变量共享状态;错误输出用 fmt.Fprint(os.Stderr, ...),结构化消息用 logger;任何新增交互功能都必须遵守 --non-interactive。
限制:资料未提供具体安装命令、依赖版本、平台支持范围及完整代码示例,相关细节暂未提供。