Go API 错误响应怎么设计：统一错误码、字段语义与兼容迁移

接口出错时，客户端最怕的不是收到 400 或 500，而是同一个语义的返回，今天输出 message，下周又换成 error；同一个“库存不足”场景，不同接口还各自定义一套独立的错误编号。Go 服务一旦被多个前端、定时任务和第三方业务方调用，错误响应就应该当成一份长期维护的接口契约来落地。

推荐把错误响应固定为“业务码 + 人类可读消息 + 请求标识 + 可选字段错误”，HTTP 状态码负责表达协议层结果，业务码负责表达应用层具体原因；新增字段全程保持向后兼容，旧客户端就能平稳完成升级。

先把 HTTP 状态和业务错误分开

HTTP 状态码解决的是“这次请求在协议层发生了什么”。例如请求体 JSON 无法正常解析可以返回 400，缺少登录身份凭证可以返回 401，服务内部下游依赖异常可以返回 502。这类状态码适合网关、监控系统和通用客户端做初步判断，但没法承载所有的业务细节。

业务码则回答“调用方接下来具体该做什么动作”。库存不足、优惠券已核销、账户被冻结，这类场景都可能返回 409，但对应的重试策略完全不同。如果把这几个原因都统一写成 409，客户端仍然需要一个稳定的 code 来做分支逻辑处理。

{
  "code": "inventory_not_enough",
  "message": "商品库存不足",
  "request_id": "req_01J8K4M2",
  "details": { "sku": "SKU-1008", "available": 2 }
}

这里的 message 字段内容可以直接展示给终端用户，但程序逻辑绝对不要解析这个字段。文案内容会随着多语言配置、运营表达调整或数据脱敏策略变化，code 才是可以写进客户端判断逻辑的稳定字段。

统一错误结构，字段语义要能坚持三年

统一错误结构不等于把所有错误字段都塞进一个无限膨胀的巨型对象。先定义少部分必填字段，再给特殊业务场景预留可选扩展区域，接口后续维护起来会轻松很多。

• code：稳定、可枚举、面向调用方的业务原因标识，命名建议统一用小写下划线风格。
• message：当前语言环境下的可读说明，完全不作为机器判断的依据。
• request_id：贯穿请求链路日志、网关日志和下游调用链路的追踪标识。
• fields：参数校验失败时返回的字段级问题详情列表。

Go 项目里可以用一个轻量结构体约束错误响应的输出形状：

type APIError struct {
    Code      string       `json:"code"`
    Message   string       `json:"message"`
    RequestID string       `json:"request_id"`
    Fields    []FieldIssue `json:"fields,omitempty"`
}

type FieldIssue struct {
    Field string `json:"field"`
    Rule  string `json:"rule"`
    Hint  string `json:"hint"`
}

omitempty 可以让普通业务错误不携带空数组，但遇到字段校验错误场景时，又能返回非常清晰的机器可读结构化信息：

{
  "code": "invalid_argument",
  "message": "请求参数不合法",
  "request_id": "req_01J8K4N7",
  "fields": [
    {"field": "email", "rule": "format", "hint": "请输入有效邮箱"},
    {"field": "amount", "rule": "min", "hint": "金额必须大于 0"}
  ]
}

错误码命名和 HTTP 映射怎么定

错误码最好直接描述业务事实，不要透出内部实现细节。redis_timeout 直接暴露了当前服务的存储依赖，后续换成数据库集群或者缓存服务时，就会产生额外的兼容负担；dependency_unavailable 更适合放在对外的接口契约里，具体的底层依赖异常细节只需要记录到内部日志即可。

你可以先维护一份精简的映射表，代码和接口文档共用同一份定义，避免两边信息不一致：

不要让所有异常都统一返回 200 再靠 code 判断状态。这种写法会让监控系统把业务失败误判为请求成功，也会让网关、缓存组件和通用 SDK 的默认行为失去参考价值。

在 Go Handler 里集中写出错误

错误输出逻辑应该收敛到统一入口，避免每个业务 Handler 自己单独设置响应头、编码 JSON、补全请求标识。

func writeError(w http.ResponseWriter, r *http.Request, status int, e APIError) {
    if e.RequestID == "" {
        e.RequestID = requestIDFromContext(r.Context())
    }
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(e)
}

func createOrder(w http.ResponseWriter, r *http.Request) {
    if err := validateOrder(r); err != nil {
        writeError(w, r, http.StatusBadRequest, APIError{
            Code: "invalid_argument", Message: "请求参数不合法",
            Fields: []FieldIssue{{Field: "items", Rule: "required", Hint: "至少填写一项"}},
        })
        return
    }
    // 业务处理成功后再写 201，避免响应状态已经发送却继续改写错误。
}

这个统一入口有两个很容易被漏掉的检查点：先设置 HTTP 状态码再编码响应正文，并且所有分支在写出错误响应后立即 return。否则 Handler 后续逻辑可能继续写入成功响应内容，日志里看起来完全正常，客户端却收到拼接后的非法 JSON。

兼容迁移：先加字段，再切客户端

老接口如果只有 error 字段，不要一次性直接改成新结构并删掉旧字段。第一阶段让服务同时返回旧字段和新字段，客户端优先读取 code；第二阶段统计旧字段的实际读取量；确认没有遗留活跃调用方后，再安排删除旧逻辑。

1. 服务端新增 code 和 request_id，完整保留旧的 error 返回逻辑。
2. 客户端优先读取 code，读不到的情况下自动回退到 error 做兼容。
3. 在网关或服务日志里统计走旧格式返回的调用来源和调用量。
4. 发布正式迁移文档和预留足够的迁移窗口，最后才移除旧兼容字段。

回归测试至少覆盖 HTTP 状态码正确性、必填字段完整性、错误码稳定性和未知字段容忍度几个点。绝大多数 JSON 客户端会自动忽略返回里的新增字段，但如果业务用了自定义严格反序列化 SDK，就要单独做适配确认。

func TestCreateOrderErrorContract(t *testing.T) {
    req := httptest.NewRequest(http.MethodPost, "/orders", strings.NewReader(`{"items":[]}`))
    rec := httptest.NewRecorder()
    createOrder(rec, req)

    if rec.Code != http.StatusBadRequest { t.Fatalf("status = %d", rec.Code) }
    var got APIError
    if err := json.NewDecoder(rec.Body).Decode(&got); err != nil { t.Fatal(err) }
    if got.Code != "invalid_argument" || got.RequestID == "" { t.Fatalf("bad contract: %+v", got) }
}

常见问题：错误响应落地时容易踩哪些坑

业务失败都用 500，可以吗？

不建议这么做。500 状态码应该保留给服务端未主动捕获的异常；参数错误、资源冲突和下游依赖故障分别使用更准确的状态码，监控系统和调用方才能拿到可靠的判断信号。

message 可以直接给前端展示吗？

可以作为默认提示文案直接透出，但涉及内部错误堆栈、敏感字段或下游细节信息时要替换成脱敏后的安全文案。真正的业务分支判断逻辑仍然要读取 code 字段。

request_id 应该由谁生成？

入口网关已经生成可信链路标识时可以直接透传下去；没有前置网关标识的场景下由 Go 服务自行生成，同时写入请求上下文和结构化日志。不要把用户传入的参数直接当成链路追踪标识使用。

新增字段会破坏旧客户端吗？

对大多数宽松模式的 JSON 客户端不会有影响，但启用严格解码、签名校验或者设置了返回字段白名单的场景可能会出问题。正式发布前要基于项目实际使用的 SDK 做一轮真实兼容测试。

把错误契约变成可检查的团队规则

一套好用的错误响应规范，不在于字段越多设计得越专业，而在于调用方能稳定判断状态、日志能完整串起一次全链路请求、服务端后续能平滑迭代演进。先固定三四个核心字段，再把字段校验、错误码映射和兼容回归逻辑写进自动化测试；下次做接口改造升级的时候，错误处理就不会变成到处补临时补丁的大坑。