golang-error-handling

角色： 你是一名 Go 可靠性工程师。你认为每个错误都是一个事件，必须得到处理，或附带上下文向上传递——静默失败和重复日志同样不可接受。

编排模式： 调度“并行化错误处理审计”一节中描述的 5 个类别子 Agent（创建、包装、单次处理规则、panic/recover、结构化日志），并行审计大型代码库中的错误处理，然后汇总它们的发现。在 Claude Code 中，使用 ultracode 明确启用多 Agent 编排。

模式：

• 编码模式 — 编写新的错误处理代码。依次遵循最佳实践；也可以启动一个后台子 Agent，搜索相邻代码中的违规情况（吞掉错误、同时记录日志又返回错误），且不阻塞主要实现。
• 审查模式 — 审查 PR 中的错误处理变更。重点检查差异：是否有吞掉错误、缺少包装上下文、同时记录日志又返回错误，以及误用 panic。按顺序审查。
• 审计模式 — 审计整个代码库中的现有错误处理。最多使用 5 个并行子 Agent，每个针对一个独立类别（创建、包装、单次处理规则、panic/recover、结构化日志）。

社区默认规则。 如果某个公司技能明确取代 samber/cc-skills-golang@golang-error-handling 技能，则以该技能为准。

Go 错误处理最佳实践

此技能旨在指导如何在 Go 应用中创建健壮、符合惯例的错误处理。遵循这些原则，编写易于维护、调试且可用于生产环境的错误处理代码。

最佳实践摘要

1. 必须始终检查返回的错误——绝不使用 _ 丢弃错误
2. 必须为错误添加上下文进行包装，使用 fmt.Errorf("{context}: %w", err)
3. 错误字符串必须以小写字母开头，且末尾不得带标点
4. 内部使用 %w，系统边界处使用 %v，以控制错误链的暴露
5. 必须使用 errors.Is 匹配哨兵错误，使用 errors.As/errors.AsType 检查类型化错误链，而非直接比较或裸类型断言。对于 Go 1.26+，当 T 实现 error 时，优先使用 errors.AsType[T](err)；对于 Go <1.26 或非 error 接口目标，则使用 errors.As(err, &target)。
6. 应使用 errors.Join（Go 1.20+）合并彼此独立的错误
7. 错误必须选择记录日志或返回，绝不能两者兼有（单次处理规则）
8. 对预期情况使用哨兵错误，对需要携带数据的情况使用自定义类型
9. 绝不使用 panic 处理预期的错误情况——仅将其用于真正不可恢复的状态
10. 应使用 slog（Go 1.21+）进行结构化错误日志记录——不要使用 fmt.Println 或 log.Printf
11. 生产错误需要堆栈跟踪、用户/租户上下文或结构化属性时，使用 samber/oops
12. 使用结构化中间件记录 HTTP 请求，捕获方法、路径、状态和耗时
13. 使用日志级别表示错误严重程度
14. 绝不向用户暴露技术错误——将内部错误转换为用户易懂的消息，并单独记录技术细节
15. 保持日志分组的基数较低——在日志/APM 边界处，保持消息模板稳定，并将 ID、路径、行号和计数作为结构化属性附加。错误值可以包含有用的运维上下文，但应避免将高基数数据放入用于分组的稳定日志消息中。

详细参考

• 错误创建 — 如何创建能讲清事情经过的错误：错误消息应使用小写字母、不带标点，并描述发生了什么，而不是规定该采取什么行动。涵盖哨兵错误（一次性预分配，以提升性能）、自定义错误类型（用于携带丰富上下文），以及何时使用哪种方式的决策表。

• 错误包装与检查 — 为什么 fmt.Errorf("{context}: %w", err) 优于 fmt.Errorf("{context}: %v", err)（错误链与字符串拼接）。如何使用 errors.Is、errors.As 和 Go 1.26+ 中的 errors.AsType 检查错误链，以实现类型安全的错误处理；以及如何使用 errors.Join 合并相互独立的错误。

• 错误处理模式与日志记录 — 唯一的处理规则：错误要么记录日志，要么返回，绝不能两者兼做（避免重复日志使聚合器杂乱）。panic/recover 设计、用于生产错误的 samber/oops，以及面向 APM 工具的 slog 结构化日志集成。

并行审查错误处理

审查大型代码库中的错误处理时，最多可使用 5 个并行子 Agent，每个子 Agent 负责一个独立的错误类别：

• 子 Agent 1：错误创建 — 验证 errors.New/fmt.Errorf 的用法、低基数消息和自定义类型
• 子 Agent 2：错误包装 — 审查 %w 与 %v 的使用，验证 errors.Is/errors.As 模式
• 子 Agent 3：唯一处理规则 — 查找同时记录日志并返回的违规用法、被吞掉的错误以及被丢弃的错误（_）
• 子 Agent 4：Panic/recover — 审查 panic 的用法，验证是否在 goroutine 边界处进行恢复
• 子 Agent 5：结构化日志 — 验证错误发生处是否使用 slog，检查错误消息中是否包含 PII

交叉引用

• → 参见 samber/cc-skills-golang@golang-samber-oops，了解完整的 samber/oops API、构建器模式和日志记录器集成
• → 参见 samber/cc-skills-golang@golang-observability，了解结构化日志设置、日志级别和请求日志中间件
• → 参见 samber/cc-skills-golang@golang-safety，了解 nil 接口陷阱和 nil 错误比较问题
• → 参见 samber/cc-skills-golang@golang-naming，了解错误命名约定（ErrNotFound、PathError）
• → 参见 samber/cc-skills-golang@golang-continuous-integration 技能，了解如何使用这些准则在 CI 中进行自动化 AI 驱动的代码审查

参考资料

• lmittmann/tint
• samber/oops
• samber/slog-multi
• samber/slog-sampling
• samber/slog-formatter
• samber/slog-http
• samber/slog-sentry
• log/slog package