必须自定义结构化错误响应体，统一状态码、字段命名与语义，使用ErrorResponse结构体（含code、message、details），封装writeError函数确保Content-Type、WriteHeader顺序及Details安全，并通过中间件recover panic转为标准错误响应。
Go Web 接口返回错误时，http.Error 或裸 WriteHeader + Write 无法满足 RESTful 错误响应的可读性、一致性与客户端解析需求。必须自定义结构化错误响应体，并统一状态码、字段命名和语义。
定义标准错误响应结构体
RESTful 错误响应应包含机器可读的 code（业务错误码）、人类可读的 message、可选的 details（如字段校验失败信息）以及符合 HTTP 语义的状态码。避免用字符串拼接或 map 直接序列化。
推荐定义如下结构：
type ErrorResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Details any `json:"details,omitempty"`
}
注意：Code 是业务错误码（如 1001 表示参数缺失），不是 HTTP 状态码；HTTP 状态码由 http.ResponseWriter.WriteHeader 单独设置。
常见错误：把 http.StatusUnprocessableEntity 直接赋给结构体的 Code 字段，导致前端混淆业务码和协议码。
在 handler 中统一写入错误响应
不要在每个 handler 里重复 json.Marshal + WriteHeader + Write。封装一个 writeError 工具函数，确保 Content-Type、状态码、JSON 序列化行为一致。
关键点：
- 始终显式设置
w.Header().Set("Content-Type", "application/json; charset=utf-8") - 先调用
w.WriteHeader(statusCode)，再写 body；顺序颠倒会导致状态码被忽略 - 对
Details字段做 nil 判断，避免输出"details": null或 panic
示例：
func writeError(w http.ResponseWriter, statusCode int, code int, message string, details any) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(statusCode)
json.NewEncoder(w).Encode(ErrorResponse{
Code: code,
Message: message,
Details: details,
})
}
// 使用
writeError(w, http.StatusBadRequest, 1002, "email format invalid", map[string]string{"email": "must contain @"})
区分 HTTP 状态码与业务错误码的映射逻辑
HTTP 状态码反映请求/响应层面的协议语义（如 400 Bad Request、401 Unauthorized、404 Not Found），而业务错误码用于后端服务间或前端埋点归因。二者不可混用，但需有合理映射关系。
例如：
- 参数校验失败 →
http.StatusBadRequest（400） + 业务码1001 - 资源不存在 →
http.StatusNotFound（404） + 业务码2001 - 权限不足 →
http.StatusForbidden（403） + 业务码3001 - 内部服务异常 →
http.StatusInternalServerError（500） + 业务码5001
避免把所有错误都返回 500，这会让前端无法区分是用户输错还是系统挂了。
中间件中捕获 panic 并转为标准错误响应
Go HTTP server 默认 panic 会返回空白 500 响应，无任何错误上下文。应在顶层中间件中 recover 并转换为 ErrorResponse。
注意：
- recover 后需手动设置
http.StatusInternalServerError - 日志中必须记录 panic stack，否则无法定位问题
- 不要将敏感信息（如数据库连接串、路径）直接暴露在
message中
示例中间件片段：
func recoverMiddleware(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 in %s %s: %+v", r.Method, r.URL.Path, err)
writeError(w, http.StatusInternalServerError, 5001, "internal error", nil)
}
}()
next.ServeHTTP(w, r)
})
}
真正难处理的是异步 goroutine 中的 panic —— 它不会被这个中间件捕获，需要单独加 recover 或改用带上下文的同步调用。
