Go REST API 如何统一错误响应：错误码、字段语义与兼容边界

订单服务刚接入移动端时，最麻烦的不是返回500错误，而是同一类参数错误在三个接口里返回三种完全不同的格式：一个返回 message，一个返回 msg，还有一个直接把字段错误信息塞到普通提示字符串里。客户端只能靠匹配文本内容来决定要不要给用户弹提示、要不要触发重试逻辑，服务端哪怕只改了一句提示文案，都有可能影响正常业务流程。

先把错误响应当成正式的接口契约

成功响应的格式通常很早就会做统一，失败响应却经常被开发当成临时返回的字符串随便写。真正稳定的方案是先提前约定一个所有客户端都能长期依赖的统一错误信封格式，再把每一类失败场景明确映射到对应的HTTP状态码和自定义业务错误码上。

推荐的最小完整结构如下。成功和失败响应不要混用一堆可选字段，不然客户端很容易把空值、缺字段和真正的业务有效值搞混，出现意料之外的解析问题。

{
  "error": {
    "code": "order_param_invalid",
    "message": "订单参数不正确",
    "request_id": "req_7f2a",
    "details": {
      "field": "quantity",
      "reason": "must_be_positive"
    }
  }
}

为什么要把错误码和HTTP状态分成两层

HTTP状态码适合用来表达协议层的执行结果，自定义业务错误码适合表达明确给调用方的下一步操作指引。比如 400 可以承载所有字段格式错误类的场景，409 可以承载库存版本冲突类的场景，但客户端还需要知道具体是 order_param_invalid 还是 stock_version_conflict 才能给出对应的交互反馈。

可以先划出四条非常清晰的边界规则：

• 400：请求格式或者传入字段值不符合要求，客户端修正参数之后再重新发起请求。
• 401/403：身份凭证无效或者当前账号没有对应操作权限，不能盲目自动重复发起请求。
• 409：当前资源状态和写入操作的前置条件冲突，通常需要客户端重新读取最新资源状态再引导用户二次确认。
• 429/503：服务端暂时无法承载当前请求压力，只有在请求本身具备幂等属性的前提下，才考虑按照退避策略重试。

别着急把所有失败请求的状态都改成500。500只能笼统说明服务端没有正常完成请求，完全不能替代“哪个字段传错了”或者“这次请求能不能安全重发”这类关键信息。

Go 中集中处理错误信封和字段级详情

各个业务处理器不需要自己手动拼接JSON响应，只要返回一个携带业务错误码的自定义错误对象就行。统一的响应写出逻辑会自动设置 Content-Type、对应的HTTP状态码和追踪相关字段，后续要调整日志字段或者新增特殊响应头的时候，只需要改这一处公共逻辑就可以。

package api

import (
    "encoding/json"
    "net/http"
)

type APIError struct {
    Status    int            `json:"-"`
    Code      string         `json:"code"`
    Message   string         `json:"message"`
    RequestID string         `json:"request_id,omitempty"`
    Details   map[string]any `json:"details,omitempty"`
}

func writeAPIError(w http.ResponseWriter, err *APIError) {
    if err.Status == 0 {
        err.Status = http.StatusInternalServerError
    }
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(err.Status)
    _ = json.NewEncoder(w).Encode(map[string]any{"error": err})
}

func invalidField(field, reason, requestID string) *APIError {
    return &APIError{
        Status: http.StatusBadRequest, Code: "order_param_invalid",
        Message: "订单参数不正确", RequestID: requestID,
        Details: map[string]any{"field": field, "reason": reason},
    }
}

Status 字段只用于服务端内部的错误映射逻辑，对应的JSON标签直接把它排除在序列化结果之外。这样客户端拿到的永远是约定好的稳定错误信封格式，不会因为服务端内部新增了某个状态字段就打乱对外的协议结构。

客户端到底该不该重试，由错误码说清楚

错误码的命名要直接体现当前场景下客户端可以处理的业务事实，不要只是机械复述HTTP状态的含义。service_unavailable 只能笼统说明请求暂时失败；order_param_invalid 要明确告诉客户端继续重试完全没有意义。对于所有写操作，还要把幂等键规则和对应的重试策略一起写进接口文档里。

如果一个错误码既表示参数错误，又表示上游服务调用超时，客户端迟早会做出完全错误的处理动作。宁可多新增一个独立错误码，也不要让同一个错误码承载两个完全相反的重试结论。

兼容旧客户端时，哪些改动最容易踩坑

在错误响应里新增字段通常是安全操作，直接删除字段或者修改原有字段的类型就很容易出问题。比如旧客户端原本把 details 当成字符串类型读取，新版本突然改成对象类型，服务端明明觉得信息展示更完整了，旧客户端却可能直接出现JSON解析崩溃。

• 保留旧的 message 字段不删除，新增 request_id 扩展字段完全不替换原有字段。
• 错误码只做新增操作，绝对不复用已经上线过的旧错误码。
• details外层先固定为对象类型，后续要扩展信息的话只在对象内部逐步增加可选键。
• 抽选一批真实的旧客户端版本做JSON格式回归校验，至少要覆盖参数错误、权限校验失败和服务暂不可用三类核心场景。

正式发布之前可以用一张很小的契约校验清单，挡住绝大多数兼容性回归问题：

curl -i -X POST http://127.0.0.1:8080/orders \
  -H 'Content-Type: application/json' \
  -d '{"quantity":0}'

检查响应状态、error.code、error.details.field 和 request_id 几个核心字段是不是都正常存在。不要只看浏览器里展示的那句中文提示就直接放行。

相关问题

错误码能不能直接使用 HTTP 状态码？

不建议这么做。HTTP状态码用来表达协议层的分类结果，业务错误码用来明确调用方的下一步动作，两者组合起来才能完整覆盖资源冲突、字段错误和服务暂时不可用等各类细分场景。

message 改了会影响客户端吗？

如果之前的客户端代码有依赖message文本内容做分支判断，修改之后肯定会受影响。规范的客户端逻辑应该完全依赖稳定的code字段和details扩展信息，message字段只用来做页面展示或者留作日志排查。

所有 503 都应该自动重试吗？

不是。要先确认当前请求本身是不是幂等、有没有配置退避策略和重试次数上限；创建订单这类涉及数据写入的操作还要额外配置幂等键，否则盲目重试很容易生成重复业务数据。

把错误协议当成长期接口维护

统一错误响应的核心目标不是让JSON返回内容看起来更整齐，而是让所有调用方都能稳定判断下一步该做什么：是修正参数、刷新资源、重新登录，还是等一会儿再重试。Go服务侧把错误映射逻辑全部集中起来，再配合错误码不复用、字段只增不删、旧客户端回归校验几个规则，这套错误协议完全可以随着业务迭代扩展，不会慢慢失控。