Golang全局错误处理技巧分享

在 Go 语言开发中，仅依赖标准 `error` 接口无法支撑健壮的全局错误处理——因其缺乏状态码、堆栈、业务上下文等关键元信息，导致日志模糊、HTTP 响应混乱、监控告警失真；真正有效的方案是定义可扩展的自定义错误类型（含 Code/Message/Detail/Stack），配合 Recovery + ErrorHandler 双中间件统一捕获 panic 和显式 error，对数据库、gRPC 等外部错误做针对性封装转换，并在日志、Prometheus 和 Sentry 等观测链路中显式透传错误结构化字段，同时牢记：中间件负责响应，业务层仍需主动打点记录原始错误上下文，才能实现可追踪、可分类、可告警的全链路错误治理。

为什么 error 类型不能直接做全局错误分类？

Go 的 error 是接口，底层通常只是字符串封装（如 errors.New），没有状态码、层级、堆栈或上下文。直接用它做全局统一处理，会导致日志看不出是数据库超时还是参数校验失败，HTTP 返回也难区分 400 还是 500。

真正可行的做法是：自定义错误类型，嵌入标准 error，再加字段。常见组合包括：

• Code（int 或 string，用于映射 HTTP 状态码或业务码）
• Message（面向用户/前端的简明提示）
• Detail（面向开发者的调试信息，含参数、SQL 片段等）
• Stack（可选，用 debug.Stack() 或第三方库如 github.com/pkg/errors 捕获）

如何让中间件捕获所有 handler 中的 panic 和 error？

HTTP handler 内部 panic 会终止请求；显式返回 error 则需手动检查。两者都该由统一中间件兜底，避免每个 handler 写重复逻辑。

推荐结构：func Recovery(next http.Handler) http.Handler + func ErrorHandler(next http.Handler) http.Handler 两层协作：

• Recovery 捕获 panic，转成带 Code=500 的自定义错误，并记录完整堆栈
• ErrorHandler 接收 context.Context 中注入的 error（比如通过 ctx.Value("err") 或更稳妥的 middleware.ErrorKey），根据 Code 决定 HTTP 状态码和响应体
• 务必在 Recovery 中调用 recover() 后清空 panic 状态，否则后续中间件可能失效

怎样把数据库错误、RPC 错误自动转成统一错误类型？

不同依赖库抛出的错误格式差异大：sql.ErrNoRows 是预定义变量，pgx.PgError 有 Code 字段，grpc.Status 需调用 .Err() 才得 Go error —— 不能靠 errors.Is 或 errors.As 一招通吃。

实操建议：

• 对每个外部依赖，写一个薄封装函数，例如 WrapDBError(err error) *AppError，内部判断 errors.Is(err, sql.ErrNoRows) → Code=404，strings.Contains(err.Error(), "timeout") → Code=503
• 避免在 DAO 层直接返回原始 error，一律过一遍包装函数
• 对 gRPC 客户端，用 status.Convert(err) 提取 Code() 和 Message()，再映射到你的 AppError.Code

日志、监控、告警怎么和错误类型联动？

只定义错误类型没用，关键在消费端是否识别。比如 Sentry 上报时若只传 err.Error()，就丢失了 Code 和 Detail；Prometheus 计数器若按 err.Error() 分组，会导致相同错误因参数不同被拆成几十个指标。

必须做到：

• 日志库（如 zerolog）写日志时，显式添加 .Int("code", err.Code)、.Str("detail", err.Detail)
• Prometheus counter 标签用 code 而非完整错误文本：errorsTotal.WithLabelValues(strconv.Itoa(err.Code))
• Sentry 的 sentry.CaptureException() 前，用 sentry.WithScope() 注入 Code 和 Detail 作为 extra context

最容易被忽略的是：HTTP handler 中返回错误后，仍要主动调用日志记录 —— 中间件里的 ErrorHandler 只负责响应，不负责打点；否则错误进了监控但没留痕，排查时找不到原始上下文。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Golang全局错误处理技巧分享》文章吧，也可关注golang学习网公众号了解相关技术文章。