使用 Cobra 的 SetHelpFunc 可动态生成帮助文本：通过反射读取 struct tag（如 help、default），结合 cmd.CommandPath() 构造真实示例，并手动按 rune 控制中文换行，再用测试保障一致性。
用 cobra 的 SetUsageFunc 自定义帮助文本生成逻辑
Go 命令行工具默认的帮助输出是静态的，但如果你的命令结构（比如嵌套子命令、动态 flag）由 struct 字段或配置驱动，硬写 Short/Long 字段会很快失控。这时候得让帮助文本“活”起来——cobra.Command 提供了 SetUsageFunc 和 SetHelpFunc，允许你接管整个帮助渲染流程。
关键不是重写所有格式，而是把结构体字段注释、tag 或运行时元信息注入到模板里。比如你有个 type ServeCmd struct { Addr string `json:"addr" help:"HTTP 监听地址，默认 :8080"` }，就可以在 SetHelpFunc 里反射读取 help tag 并拼进说明。
- 别直接修改
cmd.Long：它只在首次调用 help 时被读取一次，后续修改无效 -
SetHelpFunc接收*Command，可安全调用cmd.Flags().VisitAll()遍历所有 flag 获取 tag - 如果用了
pflag（cobra默认），注意Flag.Value.Type()返回的是底层类型名（如"string"），不是 struct 字段名
从 struct tag 自动生成 flag 描述，避开 bindPFlags 的盲区
cobra 官方推荐用 cmd.Flags().StringVarP(&v, "name", "n", "def", "desc") 手动注册 flag，但一旦你的配置 struct 变更频繁，描述就容易和字段脱节。有人尝试用 bindPFlags 自动绑定，但它完全忽略 struct tag 里的描述信息，只靠变量名生成 help 文本，结果就是 --config-path 的帮助变成 config path (default "")，毫无业务语义。
真正可行的做法是：自己写一个 flagsFromStruct 函数，用 reflect 遍历 struct 字段，检查 help 或 usage tag，再调用对应类型的 StringVarP/BoolVarP 等注册 flag。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 字段必须导出（首字母大写），否则
reflect读不到 tag - 对 slice 类型（如
[]string），要用StringArrayVarP，不能用StringVarP，否则 panic - 如果字段有
defaulttag（如default:"true"），记得在注册 flag 时传入该默认值，否则bindPFlags的默认值逻辑不会生效
帮助文本中嵌入动态示例，避免硬编码过期
很多 CLI 工具的帮助末尾会加 Examples，但内容往往是静态字符串，比如 mytool serve --addr :3000。当你的子命令名或 flag 名从配置生成时，这个示例很容易和实际不一致。
解决方法是在 SetHelpFunc 里构造真实命令路径：用 cmd.CommandPath() 拿到当前命令完整调用链（如 mytool serve），再根据当前命令的 flag 列表动态拼接常用组合。比如检测到存在 addr flag 且有 default tag，就自动生成 $ mytool serve --addr {{.Default}} 这样的行。
-
cmd.CommandPath()返回的是带空格的字符串，不是切片，别试图strings.Split后取最后一个词——用cmd.Name()更可靠 - 示例中的默认值要从
flag.DefValue读，而不是从 struct 字段初始值读，因为用户可能通过环境变量或配置文件改写了默认行为 - 如果命令支持 shell 补全（
genbashcompletion），确保动态生成的示例不包含补全不识别的语法（如未转义的$）
中文帮助对齐与换行问题，golang.org/x/text 不是必需的
用中文写 help 描述时，cobra 默认的换行器（基于空格切分）会在中文字符中间断行，导致排版错乱。网上常见方案是引入 golang.org/x/text 做 Unicode 段落处理，但其实多数场景没必要——cobra 的 help 渲染最终走的是 fmt.Fprintf，只要你在 SetHelpFunc 里手动控制每行宽度即可。
简单做法：把 help 字符串按字符切片（[]rune），每 40 个 rune 插入 \n（英文场景可用 80，中文建议 40–50），再用 strings.Join 拼回去。注意跳过已有换行符，避免重复断行。
- 别用
strings.RuneCountInString做实时计数：它比直接转[]rune慢，且 help 文本长度固定，预处理一次就行 - 如果帮助文本含 ANSI 转义序列（如颜色），要先剥离再计算宽度，否则
\x1b[32m这类会被算作 5 个字符，破坏对齐 - 终端宽度检测（
term.Width）在 CI 或管道中不可靠，不要依赖，固定宽度更稳妥
cmd.Help() == expectedHelp，并在 CI 中跑，一改就报。 
