应使用 recover 中间件捕获 panic 并返回 JSON 错误响应，同时定义 ErrorStatuser 接口统一映射业务错误为状态码与 JSON，避免 http.Error() 和字符串匹配，用 errors.Is() 识别 context 超时等底层错误。
Go HTTP handler 中 panic 怎么捕获并转成 JSON 错误响应
默认情况下，http.ServeHTTP 遇到 panic 会打印堆栈并返回 500 空响应，前端收不到结构化错误信息。必须在中间件里用 recover() 拦截，且要确保只在顶层 handler goroutine 中生效（Go 的 panic 不跨 goroutine 传播）。
- 不要在 goroutine 里直接调用
panic()后指望中间件捕获——它根本收不到 - 恢复后需手动设置
Content-Type: application/json，否则浏览器可能当文本渲染 - 建议只 recover 非预期 panic，业务错误应主动返回
error，而非依赖 panic
func recoverMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusInternalServerError)
json.NewEncoder(w).Encode(map[string]string{
"error": "internal server error",
})
}
}()
next.ServeHTTP(w, r)
})
}
自定义错误类型如何统一映射为 HTTP 状态码和 JSON 响应
用接口解耦错误分类比用字符串判断更可靠。定义 ErrorStatuser 接口，让业务错误实现它，中间件即可提取状态码与消息。
-
errors.Is()和errors.As()能穿透包装错误，推荐用于判断底层错误类型 - 避免在错误消息里拼接用户输入，防止 JSON 注入或 XSS（即使服务端渲染 JSON，也要防字段污染）
- 数据库超时、连接拒绝等底层错误应映射为
503 Service Unavailable，而非笼统的 500
type ErrorStatuser interface {
error
StatusCode() int
}
func errorResponse(w http.ResponseWriter, err error) {
status := http.StatusInternalServerError
if es, ok := err.(ErrorStatuser); ok {
status = es.StatusCode()
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
json.NewEncoder(w).Encode(map[string]string{"error": err.Error()})
}
为什么不能直接用 http.Error() 返回 JSON 错误
http.Error() 默认写的是纯文本（text/plain; charset=utf-8），且无法控制响应体结构。前端若期望 {"error": "xxx"} 却收到 Internal Server Error 字符串，解析必然失败。
- 它不支持设置自定义 JSON 字段（如
code、request_id） - 状态码硬编码在函数参数里，没法根据错误动态决定（比如同一个错误在调试环境返回 500，在生产返回 503）
- 日志埋点、监控指标也难挂钩——你得额外再 wrap 一层才能记录完整错误上下文
中间件里统一错误处理时，context 超时错误怎么识别和响应
Go 的 context.DeadlineExceeded 是一个已导出变量，但它是 error 类型，不是具体类型，所以不能用类型断言，得用 errors.Is() 判断。
立即学习“go语言免费学习笔记（深入）”；
- 别写
err == context.DeadlineExceeded—— 它是包装后的错误，相等判断必失败 - 超时响应建议用
408 Request Timeout或504 Gateway Timeout，取决于超时发生在本层还是下游服务 - 如果 handler 已写部分响应头（如
Set-Cookie），再写错误体可能触发http: multiple response.WriteHeader calls
if errors.Is(err, context.DeadlineExceeded) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusRequestTimeout)
json.NewEncoder(w).Encode(map[string]string{"error": "request timeout"})
return
}
真正难的不是封装响应格式，而是错误来源的归因粒度：是客户端参数错（400）、资源不存在（404）、权限不足（403）、还是服务不可用（503）？每种都要有明确的错误构造路径，而不是全塞进一个 AppError 里靠字符串匹配区分。 
