Go统一处理HTTP错误响应方法分享

本文深入探讨了Go语言中HTTP错误处理的常见陷阱与最佳实践，强调不能简单用`http.Error`一概而论，而应通过自定义带状态码的`AppError`类型实现错误分类、统一拦截和精准响应；同时指出必须显式检查`json.Encoder.Encode`的错误以避免panic，recover后务必先调用`WriteHeader`再写响应体，且生产环境需严格脱敏错误信息、仅返回泛化提示并记录完整日志——核心在于构建可判断、可分类、可控制的健壮错误处理体系。

HTTP handler里直接return error会丢掉状态码

Go 的 http.Handler 接口不接受 error 返回值，你写 return err 编译就报错。常见错误是把业务逻辑里的 err != nil 一判断，就直接 http.Error(w, err.Error(), http.StatusInternalServerError) —— 这样看似简单，但所有错误都变成 500，前端无法区分是参数错（400）、未登录（401）、没权限（403）还是服务炸了（500）。

实操建议：

• 定义统一错误类型，比如 type AppError struct { Code int; Msg string; Err error }，带 HTTP 状态码字段
• handler 中用 if err != nil { handleError(w, err) }，而不是裸调 http.Error
• handleError 函数内部做类型断言：if appErr, ok := err.(*AppError); ok { http.Error(w, appErr.Msg, appErr.Code) }，否则 fallback 到 500

json.Marshal 失败导致 panic 而不是返回 500

很多新手在 handler 末尾写 json.NewEncoder(w).Encode(resp)，结果 resp 里有 time.Time 字段没实现 json.Marshaler，或含 nil map/slice，运行时 panic，HTTP 连接直接断开，日志里只留一行 goroutine crash，前端收不到任何响应。

实操建议：

• 永远用 err := json.NewEncoder(w).Encode(resp) 显式检查 err
• 如果 err != nil，先 w.WriteHeader(http.StatusInternalServerError)，再写错误体，避免 header 已发送后又尝试写 body
• 对输出结构体加 //go:generate go run golang.org/x/tools/cmd/stringer -type=StatusCode 类型约束，或用 encoding/json 的 MarshalJSON 方法预检字段

中间件里 recover 捕获 panic 后忘记设置 status code

用了 defer func() { if r := recover(); r != nil { /* log */ } }() 做兜底，但忘了 w.WriteHeader(http.StatusInternalServerError)，结果默认 200 + 空 body，前端以为成功了。

实操建议：

• recover 后第一件事是 w.WriteHeader(http.StatusInternalServerError)，哪怕后面还要写 JSON 错误体
• 不要在 recover 里直接调 http.Error，它内部会覆盖已写的 header；先设 status，再手动写 body
• 配合 http.Hijacker 或 ResponseWriter 包装器记录是否已写 header，避免重复 WriteHeader 报 warning

error message 泄露敏感信息或内部路径

开发环境直接把 err.Error() 返回给前端，比如 "failed to connect to postgres://xxx@127.0.0.1:5432: dial tcp 127.0.0.1:5432: connect: connection refused"，暴露数据库地址、端口甚至连接串片段。

实操建议：

• 生产环境 error body 只返回泛化提示，如 "service unavailable"，详细日志打到 zap 或 logrus 并带上 traceID
• 用 errors.Is(err, os.ErrNotExist) 或自定义 sentinel error（如 var ErrUserNotFound = errors.New("user not found")）做分类，不同类别映射不同用户提示
• 所有对外输出的 error message 必须经过 sanitizeError 函数过滤，移除 @、://、IP、路径等模式

事情说清了就结束。最常被忽略的是：错误类型必须可判断、可分类、可控制输出，而不是靠字符串匹配或层层 if-else。

到这里，我们也就讲完了《Go统一处理HTTP错误响应方法分享》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！