Go HTTP handler 中 panic 默认导致500且响应不可控，须用recover中间件拦截并统一转为结构化错误响应；应定义带状态码的AppError类型、统一响应包装器Respond，并区分HTTP状态码与业务code。
Go HTTP handler 中 panic 会直接 500，必须拦截
默认情况下，http.ServeMux 或 http.Handler 函数里一旦 panic，Go 的 http.Server 会打印堆栈并返回状态码 500，但响应体不可控、无业务上下文、不记录日志。这不是“错误处理”，是服务裸奔。
正确做法是在中间件中 recover，并转换为结构化错误响应：
func Recovery(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
log.Printf("panic recovered: %v", err)
http.Error(w, "Internal Server Error", http.StatusInternalServerError)
}
}()
next.ServeHTTP(w, r)
})
}
- 必须放在所有业务 handler 外层（比如
http.ListenAndServe(":8080", Recovery(r))） - 仅捕获 panic，不处理
return errors.New(...)这类显式错误 - 不要在 recover 里直接写 JSON 响应——此时可能已部分写入 header，应统一走错误响应构造逻辑
自定义 error 类型 + Status Code 绑定
Go 原生 error 接口不携带 HTTP 状态码，硬编码 http.StatusBadRequest 到每个 handler 里极易遗漏或错配。推荐定义可嵌入状态码的错误类型：
type AppError struct {
Code int
Message string
Err error // 底层原始错误（用于日志/调试）
}
func (e *AppError) Error() string {
if e.Err != nil {
return fmt.Sprintf("%s: %v", e.Message, e.Err)
}
return e.Message
}
func BadRequest(msg string) *AppError {
return &AppError{Code: http.StatusBadRequest, Message: msg}
}
func NotFound(msg string) *AppError {
return &AppError{Code: http.StatusNotFound, Message: msg}
}
- 业务 handler 中直接
return BadRequest("user ID required")，不手动写http.Error -
Err字段保留原始错误（如数据库超时、JSON 解析失败），便于日志追踪，但不暴露给前端 - 避免用字符串拼接做错误类型判断（如
strings.Contains(err.Error(), "not found")），应通过类型断言：if ae, ok := err.(*AppError); ok { ... }
统一响应包装器：把 error 转成标准 JSON 返回
所有 handler 不该各自调用 json.NewEncoder(w).Encode(...)。应在中间件或顶层 wrapper 中统一处理成功与错误响应格式：
立即学习“go语言免费学习笔记（深入）”；
type Response struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}
func Respond(w http.ResponseWriter, status int, data interface{}, err error) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(status)
resp := Response{
Code: status,
Message: http.StatusText(status),
Data: data,
}
if appErr, ok := err.(*AppError); ok {
resp.Code = appErr.Code
resp.Message = appErr.Message
}
if err := json.NewEncoder(w).Encode(resp); err != nil {
log.Printf("failed to encode response: %v", err)
}
}
- 成功响应也走这个函数（
Respond(w, http.StatusOK, user, nil)），保证结构一致 - 注意
w.WriteHeader(status)必须在写 body 前调用，否则会被json.Encoder自动设为 200 - 不要在
Respond里加额外日志——错误日志应在 error 生成时或中间件中记录，避免重复
Handler 内部如何返回错误而不中断流程
Go 没有 try/catch，但大量嵌套 if err != nil { return err } 很丑。可用两种轻量方式保持可读性：
- 使用
errors.Join（Go 1.20+）合并多个校验错误，一次性返回：var errs []error; if x == "" { errs = append(errs, errors.New("x required")) }; if y 0 { return errors.Join(errs) } - 对 DB/HTTP 等外部调用，封装带 context 和重试的工具函数，内部自动转成
*AppError，例如：user, err := GetUser(ctx, id); if err != nil { return InternalError("failed to fetch user").Wrap(err) }（Wrap方法可附加原始错误） - 切忌在 handler 里用
log.Fatal或os.Exit——这会 kill 整个 server
最易被忽略的是：错误响应体里的 code 字段别和 HTTP 状态码强绑定。比如业务需要返回 {"code": 40001, "message": "token expired"}，此时 HTTP 状态码仍应是 401，而 JSON 中的 code 是业务码——两者语义不同，混用会导致前端判断混乱。
