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 中统一处理成功与错误响应格式：
Json Schema Toolkit
下载
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
立即学习“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 是业务码——两者语义不同，混用会导致前端判断混乱。
