Golang统一错误处理中间件实战

本文深入探讨了Go语言中HTTP服务统一错误处理中间件的设计与实践，重点解析了如何在recover()捕获panic后安全、精准地转化为用户友好的HTTP错误响应：既要通过类型断言和空值判断防止中间件自身崩溃，又要根据错误语义（如JSON解析失败用400、DB中断用503）动态设定状态码，而非一概而论返回500；同时强调每个含复杂逻辑的中间件都应独立封装defer-recover，主动关闭连接以防HTTP/2复用污染，并严格区分error（业务可恢复）与panic（程序不可恢复）的使用边界——真正考验工程能力的，从来不是“能否捕获panic”，而是清醒判断“哪里该错、哪里该崩、哪里该记、哪里该关”。

中间件里 recover() 捕获 panic 后怎么转成 HTTP 错误响应

Go 的 http.Handler 本身不处理 panic，一旦发生就直接崩溃。中间件必须显式调用 recover()，否则请求一崩，整个服务都可能被拖垮。

关键不是“能不能捕获”，而是捕获后怎么把 panic 值安全转成用户能理解的错误响应，同时不泄露敏感信息。

• 必须在 defer 里调用 recover()，且只能在 goroutine 主流程中生效（不能在子 goroutine 里 recover）
• panic 值可能是 string、error、甚至 nil，需做类型断言和空值判断，否则中间件自己 panic
• 不要直接把 runtime/debug.Stack() 返回给客户端——开发环境可记录日志，生产环境必须过滤掉
• HTTP 状态码别硬写 500：如果是 json.Unmarshal 失败导致 panic，更合适返回 400；如果是数据库连接中断，才用 503

示例核心逻辑：

func Recovery(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			if err := recover(); err != nil {
				var errMsg string
				switch e := err.(type) {
				case error:
					errMsg = e.Error()
				case string:
					errMsg = e
				default:
					errMsg = "unknown error"
				}
				http.Error(w, errMsg, http.StatusInternalServerError)
				log.Printf("PANIC: %v, path=%s", err, r.URL.Path)
			}
		}()
		next.ServeHTTP(w, r)
	})
}

为什么 recover() 放在最外层中间件也不一定能兜住所有 panic

不是所有 panic 都发生在 next.ServeHTTP() 调用期间。如果 panic 出现在中间件自身逻辑里（比如解析 header 时索引越界），而你又没在该中间件里加 defer recover()，那它就直接向上冒泡到上一层中间件或 net/http 默认 handler，最终还是 crash。

• 每个中间件若含非 trivial 逻辑（如解密、校验、JSON 解析），都应独立加 defer recover()，而不是依赖最外层统一兜底
• 第三方中间件（如 gorilla/mux 的 Vars()）也可能 panic，尤其传入非法 URL 时，得确认其是否已做防护
• HTTP/2 或长连接场景下，一个 panic 可能影响后续复用的连接，所以恢复后建议主动关闭连接（w.Header().Set("Connection", "close")）

error 类型 vs panic：哪些该用 error 返回，哪些必须 panic

滥用 panic 是统一错误处理失效的根源。Go 的哲学是「错误是值」，只有真正不可恢复、程序状态已损坏的情况才该 panic。

• 业务校验失败（如 ID 不存在、权限不足）→ 返回 error，由 handler 统一转 HTTP 状态码，**不该 panic**
• 配置加载失败（如 env 缺失必填项）、初始化阶段资源获取失败（DB 连不上）→ 应在 main() 里 panic 并退出，**不在 HTTP 中间件里处理**
• 因程序员疏忽导致的 bug（如 map 写入 nil、切片越界）→ 会触发 panic，这是 recover 的目标，但说明代码有缺陷，不能靠中间件掩盖
• 第三方库文档明确说“可能 panic”（如某些正则匹配、unsafe 操作）→ 必须手动包裹并 recover，不能假设它会返回 error

log.Fatal() 和 panic() 在中间件里都是危险操作

中间件里出现 log.Fatal() 或未被捕获的 panic()，会导致整个 Go 进程退出，所有正在处理的请求全部中断——这比单个请求失败严重得多。

• log.Fatal() 底层调用 os.Exit(1)，无法被任何 recover() 拦截
• 有些团队习惯在中间件里写 if err != nil { log.Fatal(err) }，这是典型反模式
• 日志该用 log.Printf() 或结构化 logger（如 zap），错误响应走 http.Error() 或自定义 JSON 错误体
• 如果真需要终止服务（如配置热重载失败），应该发信号或设标志位，让主循环下次检查时优雅退出，而不是当场 kill

真正难的从来不是写 recover，而是分清哪里该错、哪里该崩、哪里该记、哪里该关——边界模糊时，宁可多返回 error，少用 panic。

本篇关于《Golang统一错误处理中间件实战》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于Golang的相关知识，请关注golang学习网公众号！