Golang CLI错误处理技巧

本文深入剖析了Go语言CLI程序错误处理的四大核心原则：错误输出必须严格使用os.Stderr以确保管道和重定向场景下的可靠性；flag解析失败需主动干预、避免逻辑继续执行导致panic；自定义错误应遵循Go 1.13+错误包装规范，通过Is/As实现稳健的错误识别与分发；exit code必须显式、语义化控制，杜绝依赖panic或隐式退出。这些实践直击CLI在自动化脚本中沦为“黑盒”的根本原因——不是写不出错误处理，而是缺乏端到端的一致性，真正让每一个错误路径都可观察、可预测、可集成。

错误输出应该用 os.Stderr 而不是 fmt.Println

默认的 fmt.Println 和 log.Print 都写入 os.Stdout，而 CLI 程序的错误信息必须输出到 os.Stderr，否则在管道或重定向时会被丢弃或混淆。比如：

echo "input" | your-cli --invalid

中，如果错误走 stdout，上游无法区分成功输出和报错信息。

• 始终用 fmt.Fprintln(os.Stderr, "error: ...") 输出错误
• 避免直接调用 log.Fatal，它会强制退出且不返回 exit code；改用 log.New(os.Stderr, "", 0).Fatal + 显式 os.Exit(1)
• 若使用第三方日志库（如 zap），确保其 writer 设置为 os.Stderr

flag.Parse() 失败后不能继续执行主逻辑

Go 标准库的 flag 包在解析失败（如未知 flag、类型错误）时会自动调用 os.Exit(2)，但前提是没禁用默认行为。如果你调用了 flag.Usage = func(){...} 或 flag.SetOutput(...) 却忘了手动处理错误退出，程序可能继续运行并 panic。

• 不要覆盖 flag.Usage 后忘记在自定义函数里调用 os.Exit(2)
• 若需捕获解析错误，改用 flag.CommandLine.Parse(os.Args[1:]) 并检查返回 error，而不是依赖默认退出
• 常见误写：

  flag.Usage = func() { fmt.Fprintln(os.Stderr, "usage...") }
  // ❌ 缺少 os.Exit(2)，flag.Parse() 错误后仍往下走

自定义错误类型应实现 Error() 并支持 Is() 和 As()

CLI 程序常需对特定错误做差异化处理（如网络超时重试、权限不足提示 chmod）。仅靠字符串匹配或类型断言不可靠，应让错误满足 Go 1.13+ 的标准错误包装规范。

• 定义错误时嵌入 errors.Unwrap 或用 fmt.Errorf("wrap: %w", err)
• 导出可识别的错误变量，例如：

  var ErrPermissionDenied = errors.New("permission denied")

• 判断时用 errors.Is(err, ErrPermissionDenied)，而非 err == ErrPermissionDenied（后者不适用于包装后的错误）
• 若需提取底层错误详情（如 HTTP 状态码），实现 As() 方法或用 errors.As(err, &target)

exit code 必须显式控制，不要依赖 panic 或未捕获 error

Go 程序 panic 时默认 exit code 是 2，但很多 CLI 工具约定：0=成功，1=通用错误，2=用法错误，其他值用于业务含义（如 3=网络失败，4=配置缺失）。靠 panic 推导 exit code 不可靠，也掩盖真实错误路径。

• 主函数返回 int，并在各分支明确 return 对应 code（如 return 1）
• 顶层 defer 中避免 recover() 吞掉 panic；若必须 recover，应重新转为结构化 error 并返回非零 exit code
• 测试 exit code 时用 exec.Command + cmd.Run() 检查 cmd.ProcessState.ExitCode()，而非只看 stdout

错误处理的复杂点不在写法，而在一致性：所有错误路径是否都写了 stderr、是否都返回了语义清晰的 exit code、是否允许上层脚本稳定判断失败原因。漏掉任意一环，都会让 CLI 在自动化场景中变成“黑盒”。

好了，本文到此结束，带大家了解了《Golang CLI错误处理技巧》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！