如何在Golang中为API接口返回统一错误_Golang接口错误响应规范_技术教程

统一错误结构体必须包含 code 和 message 字段，code 映射 HTTP 状态码，message 为简明提示，details 仅用于调试；错误应实现 StatusCoder 接口以避免字符串匹配；响应与日志内容须分离，禁止透出敏感信息。

统一错误结构体必须包含 status code 和 message 字段

Go 的 HTTP handler 本身不强制错误格式，但前端或调用方依赖可预测的 JSON 错误响应。硬编码 http.Error() 或直接 json.Marshal(map[string]string{"error": "xxx"}) 会导致字段不一致、缺失状态码、无法区分业务错误与系统错误。

推荐定义一个基础错误结构体，例如：

type ErrorResponse struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Details string `json:"details,omitempty"`
}

Code 应映射 HTTP 状态码（如 400、401、404、500），而非自定义错误码；Message 是面向调用方的简明提示；Details 仅用于调试或内部日志，生产环境应为空或脱敏。

不要在 handler 里用 panic 捕获并返回错误

用 recover() + http.Error() 包裹整个 handler 是常见反模式：它掩盖真实错误位置、丢失堆栈、无法区分预期错误（如参数校验失败）和意外 panic（如 nil pointer）。

正确做法是让业务逻辑返回明确的 error 类型，并由中间件或 handler 自上而下处理：

校验失败 → 返回 ErrValidation（实现 status() int 方法）
资源未找到 → 返回 ErrNotFound，其 status() 返回 404
数据库超时 → 返回原生 *pq.Error 或封装为 ErrInternal

最终统一由一个 writeError(w http.ResponseWriter, err error) 函数序列化并写入响应，避免每个 handler 重复判断类型。

HTTP 状态码不能全靠 error 字符串匹配

有人会写 if strings.Contains(err.Error(), "not found") { writeJSON(w, 404, ...) } —— 这极脆弱：翻译、日志前缀、拼写变化都会导致失效。

更可靠的方式是让 error 实现接口：

type StatusCoder interface {
    StatusCode() int
}

然后在 writeError 中判断：

if sc, ok := err.(StatusCoder); ok {
    w.WriteHeader(sc.StatusCode())
} else {
    w.WriteHeader(http.StatusInternalServerError)
}

这样 ErrNotFound、ErrBadRequest 等类型可各自控制状态码，无需字符串解析，也便于单元测试覆盖。

日志记录和响应内容必须分离

同一个错误，响应给前端的 Message 要简洁安全（如 “用户不存在”），而日志里要保留完整上下文（如 “user_id=123 not found in users table, query took 12ms”）。

常见错误是把 err.Error() 直接塞进响应 message，导致暴露路径、SQL 片段、内部服务名等敏感信息。务必检查所有 error 构造点：

使用 fmt.Errorf("failed to get user: %w", dbErr) 而非 fmt.Errorf("failed to get user: %v", dbErr)
自定义 error 类型的 Error() 方法只返回用户友好文本
真正原始错误（如 os.PathError）只进日志，不出现在 HTTP 响应中