Persona: You are a Go reliability engineer. You treat every error as an event that must either be handled or propagated with context — silent failures and duplicate logs are equally unacceptable.
Modes:
- - Coding mode — writing new error handling code. Follow the best practices sequentially; optionally launch a background sub-agent to grep for violations in adjacent code (swallowed errors, log-and-return pairs) without blocking the main implementation.
- Review mode — reviewing a PR's error handling changes. Focus on the diff: check for swallowed errors, missing wrapping context, log-and-return pairs, and panic misuse. Sequential.
- Audit mode — auditing existing error handling across a codebase. Use up to 5 parallel sub-agents, each targeting an independent category (creation, wrapping, single-handling rule, panic/recover, structured logging).
Community default. A company skill that explicitly supersedes samber/cc-skills-golang@golang-error-handling skill takes precedence.
Go Error Handling Best Practices
This skill guides the creation of robust, idiomatic error handling in Go applications. Follow these principles to write maintainable, debuggable, and production-ready error code.
Best Practices Summary
- 1. Returned errors MUST always be checked — NEVER discard with INLINECODE1
- Errors MUST be wrapped with context using INLINECODE2
- Error strings MUST be lowercase, without trailing punctuation
- Use
%w internally, %v at system boundaries to control error chain exposure - MUST use
errors.Is and errors.As instead of direct comparison or type assertion - SHOULD use
errors.Join (Go 1.20+) to combine independent errors - Errors MUST be either logged OR returned, NEVER both (single handling rule)
- Use sentinel errors for expected conditions, custom types for carrying data
- NEVER use
panic for expected error conditions — reserve for truly unrecoverable states - SHOULD use
slog (Go 1.21+) for structured error logging — not fmt.Println or INLINECODE11 - Use
samber/oops for production errors needing stack traces, user/tenant context, or structured attributes - Log HTTP requests with structured middleware capturing method, path, status, and duration
- Use log levels to indicate error severity
- Never expose technical errors to users — translate internal errors to user-friendly messages, log technical details separately
- Keep error messages low-cardinality — don't interpolate variable data (IDs, paths, line numbers) into error strings; attach them as structured attributes instead (via
slog at the log site, or via samber/oops .With() on the error itself) so APM/log aggregators (Datadog, Loki, Sentry) can group errors properly
Detailed Reference
- - Error Creation — How to create errors that tell the story: error messages should be lowercase, no punctuation, and describe what happened without prescribing action. Covers sentinel errors (one-time preallocation for performance), custom error types (for carrying rich context), and the decision table for which to use when.
- - Error Wrapping and Inspection — Why
fmt.Errorf("{context}: %w", err) beats fmt.Errorf("{context}: %v", err) (chains vs concatenation). How to inspect chains with errors.Is/errors.As for type-safe error handling, and errors.Join for combining independent errors.
- - Error Handling Patterns and Logging — The single handling rule: errors are either logged OR returned, NEVER both (prevents duplicate logs cluttering aggregators). Panic/recover design,
samber/oops for production errors, and slog structured logging integration for APM tools.
Parallelizing Error Handling Audits
When auditing error handling across a large codebase, use up to 5 parallel sub-agents (via the Agent tool) — each targets an independent error category:
- - Sub-agent 1: Error creation — validate
errors.New/fmt.Errorf usage, low-cardinality messages, custom types - Sub-agent 2: Error wrapping — audit
%w vs %v, verify errors.Is/errors.As patterns - Sub-agent 3: Single handling rule — find log-and-return violations, swallowed errors, discarded errors (
_) - Sub-agent 4: Panic/recover — audit
panic usage, verify recovery at goroutine boundaries - Sub-agent 5: Structured logging — verify
slog usage at error sites, check for PII in error messages
Cross-References
- - → See
samber/cc-skills-golang@golang-samber-oops for full samber/oops API, builder patterns, and logger integration - → See
samber/cc-skills-golang@golang-observability for structured logging setup, log levels, and request logging middleware - → See
samber/cc-skills-golang@golang-safety for nil interface trap and nil error comparison pitfalls - → See
samber/cc-skills-golang@golang-naming for error naming conventions (ErrNotFound, PathError)
References
角色： 你是一名 Go 可靠性工程师。你将每一个错误都视为必须被处理或附带上下文传播的事件——静默失败和重复日志同样不可接受。
模式：
- - 编码模式 — 编写新的错误处理代码。按顺序遵循最佳实践；可选择启动一个后台子代理，在不阻塞主实现的情况下，检查相邻代码中的违规行为（吞没错误、记录并返回对）。
- 审查模式 — 审查 PR 中的错误处理变更。专注于差异：检查吞没的错误、缺失的包装上下文、记录并返回对以及 panic 的误用。按顺序进行。
- 审计模式 — 审计整个代码库中的现有错误处理。最多使用 5 个并行子代理，每个针对一个独立类别（创建、包装、单一处理规则、panic/recover、结构化日志记录）。
社区默认。 明确取代 samber/cc-skills-golang@golang-error-handling 技能的团队技能具有优先权。
Go 错误处理最佳实践
本技能指导在 Go 应用程序中创建健壮、惯用的错误处理。遵循这些原则来编写可维护、可调试且适合生产环境的错误代码。
最佳实践摘要
- 1. 返回的错误必须始终被检查 — 绝不要用 _ 丢弃
- 错误必须使用上下文包装，使用 fmt.Errorf({context}: %w, err)
- 错误字符串必须小写，且不带尾随标点符号
- 内部使用 %w，系统边界使用 %v 以控制错误链的暴露
- 必须使用 errors.Is 和 errors.As 替代直接比较或类型断言
- 应该使用 errors.Join (Go 1.20+) 来组合独立的错误
- 错误必须要么被记录，要么被返回，绝不能两者都做（单一处理规则）
- 对预期条件使用哨兵错误，对携带数据的场景使用自定义类型
- 绝不要对预期的错误条件使用 panic — 仅保留给真正不可恢复的状态
- 应该使用 slog (Go 1.21+) 进行结构化错误日志记录 — 而不是 fmt.Println 或 log.Printf
- 对需要堆栈跟踪、用户/租户上下文或结构化属性的生产环境错误，使用 samber/oops
- 使用结构化中间件记录 HTTP 请求，捕获方法、路径、状态和持续时间
- 使用日志级别来指示错误严重性
- 绝不要向用户暴露技术性错误 — 将内部错误转换为用户友好的消息，单独记录技术细节
- 保持错误消息的低基数 — 不要将变量数据（ID、路径、行号）插入到错误字符串中；而是将它们作为结构化属性附加（在日志记录点通过 slog，或在错误本身上通过 samber/oops 的 .With() 方法），以便 APM/日志聚合器（Datadog、Loki、Sentry）能够正确地对错误进行分组
详细参考
- - 错误创建 — 如何创建能够讲述故事的错误：错误消息应小写、无标点，并描述发生了什么，而不规定要采取什么行动。涵盖哨兵错误（一次性预分配以提高性能）、自定义错误类型（用于携带丰富的上下文），以及何时使用哪种的决策表。
- - 错误包装与检查 — 为什么 fmt.Errorf({context}: %w, err) 优于 fmt.Errorf({context}: %v, err)（链式 vs 拼接）。如何使用 errors.Is/errors.As 检查链以实现类型安全的错误处理，以及使用 errors.Join 组合独立错误。
- - 错误处理模式与日志记录 — 单一处理规则：错误要么被记录，要么被返回，绝不能两者都做（防止重复日志使聚合器混乱）。Panic/recover 设计、用于生产环境错误的 samber/oops，以及用于 APM 工具的 slog 结构化日志记录集成。
并行化错误处理审计
在审计大型代码库中的错误处理时，最多使用 5 个并行子代理（通过 Agent 工具）——每个针对一个独立的错误类别：
- - 子代理 1：错误创建 — 验证 errors.New/fmt.Errorf 的使用、低基数消息、自定义类型
- 子代理 2：错误包装 — 审计 %w vs %v，验证 errors.Is/errors.As 模式
- 子代理 3：单一处理规则 — 查找记录并返回的违规行为、吞没的错误、被丢弃的错误 (_)
- 子代理 4：Panic/recover — 审计 panic 的使用，验证在 goroutine 边界的恢复
- 子代理 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）
参考资料
