CLI程序应避免用panic代替Error返回，所有I/O、解析、校验失败须走error路径；main函数应结构化为run()返回error，统一输出到stderr并设退出码；需定义自定义错误类型支持精准识别与差异化处理；参数校验须集中于flag.Parse后，退出码1表示运行时错误、2表示用户输入错误。
CLI程序中不要用panic代替错误返回
go的panic在CLI工具里容易导致不可控退出，丢失错误上下文，且无法被调用方拦截处理。用户执行mytool --config bad.yaml时，如果内部直接panic("yaml: unmarshal error")，终端只看到堆栈，没法区分是配置错误、权限不足还是网络超时。
- 所有I/O、解析、校验失败都应走
error返回路径，主函数统一处理 - 仅在真正“程序无法继续”时用
panic（如初始化全局logger失败），且必须配recover兜底并转为用户友好的退出码 - 避免在
init()或包级变量初始化中触发panic——这会让测试和导入失败
main函数里如何结构化错误退出
CLI工具的main()函数应该返回int退出码，并把错误信息输出到stderr。标准做法是定义一个run()函数返回error，main()只做最小包装：
func main() { if err := run(); err != nil { fmt.Fprintln(os.Stderr, "ERROR:", err) os.Exit(1) } } func run() error { cfg, err := loadConfig(flag.Arg(0)) if err != nil { return fmt.Errorf("failed to load config: %w", err) } return doWork(cfg) }关键点：
- 用
%w包装错误，保留原始错误链，方便后续判断类型（比如检查是否是*os.PathError） - 不直接在
main()里写业务逻辑，否则无法测试 - 所有用户可见错误消息必须用
fmt.Fprintln(os.Stderr, ...)，不能用log.Fatal（它会强制退出且不返回控制权）
自定义错误类型用于差异化处理
当需要根据错误类型做不同响应（比如重试、提示帮助、静默忽略），定义带方法的错误类型比字符串匹配更可靠：
type ConfigError struct { Path string Err error } func (e *ConfigError) Error() string { return fmt.Sprintf("invalid config file %q: %v", e.Path, e.Err) } func (e *ConfigError) Is(target error) bool { _, ok := target.(*ConfigError) return ok }这样可以在run()中精准识别并处理：
-
errors.Is(err, &ConfigError{})→ 输出--help提示 -
errors.As(err, &net.OpError{})→ 加上超时重试逻辑 - 普通
os.IsNotExist(err)→ 提示“配置文件不存在，请运行mytool init”
命令行参数解析失败时的错误粒度
用flag包时，flag.Parse()本身不返回错误，但参数校验要主动做。常见坑是把校验逻辑散落在各处，导致错误信息零散、退出码混乱。
- 所有参数校验统一放在
flag.Parse()之后、业务逻辑之前 - 对必需字段缺失、值范围越界、互斥参数同时出现等场景，用
fmt.Errorf构造带上下文的错误（如"--timeout must be > 0, got %d"） - 避免用
flag.Usage()自动打印帮助——它不输出到stderr，且格式固定；改用自定义帮助函数配合os.Exit(2)（约定：2表示用法错误）
错误退出码的语义要明确：1是运行时错误，2是用户输入错误，127是命令未找到（POSIX兼容）。