统一 API 响应信封:error_code、HTTP 状态码,和前后端怎么对齐

统一 API 响应信封:error_code、HTTP 状态码,和前后端怎么对齐

Hello,我是小兔大白糖。 联调第 N 天:后端说「接口成功了,看 HTTP 200」;前端说「业务失败了,用户不存在」——两边都没错,只是约定没钉死。写成这篇,给要给自家 API 定一套统一响应信封、并和前端对齐判错规则的初中级后端同学。

说明:文中包路径、错误码区间、handler 示例均为教学脱敏写法,不是某家公司的内部规范,也不是行业标准。读完带走的是可行动的心智模型,不是一张必须照抄的码表。

估计阅读时间:14 分钟


目录


为什么现在要关心

没有统一信封时,前后端会在「这次算不算失败」上反复对不上。

常见现场:

你看到的现象常见真相
HTTP 200,前端却当成功解析 data业务失败写在 body 里,客户端没先读 error_code
同一业务「用户不存在」有时 404、有时 200没有双通道约定,handler 随手挑 helper
网关日志全是 200,业务失败率只能拆 body监控只盯 HTTP,业务码没进指标
客户端收到 pq: relation does not exist内部 err.Error() 原样回传,既吓人又泄实现细节

统一信封解决的是:成功与业务失败长什么样、协议层失败怎么表达、前端固定从哪里判错。 它不替代 HTTP 语义,也不自动等于「永远 200」。


心智模型:信封 vs HTTP 状态码

先定双通道,再谈 helper 名字。

把一次 API 调用想成「快递盒 + 路况」:

  • HTTP 状态码 ≈ 路况 / 快递公司能不能把盒子送到门口
    鉴权网关拒了、路径不存在、上游超时被网关写成 502——盒子可能根本没按业务格式打开,或根本没完整送达。
  • 响应信封(error_code / error_msg / data)≈ 盒子里的回执单
    门开了、格式统一;业务说「余额不足」「用户不存在」写在回执上,HTTP 仍可以是 200。
API 双通道:协议层看 HTTP,业务层看信封
API 双通道:协议层看 HTTP,业务层看信封 · 点击查看 SVG 原图

类比局限一句说清:路况类比解释「谁先失败、监控先看哪一层」;解释不了 OAuth、缓存协商、幂等重试该用哪些 HTTP 语义——那些仍要按协议本身设计。

团队必须二选一(教学示例采用 A)

方案做法代价
A. 双通道(本文教学默认)协议 / 网关层问题 → HTTP 4xx/5xx;业务可理解失败 → HTTP 200 + 非 0 error_code客户端必须:先看 HTTP,再看信封
B. 始终用 HTTP 状态码业务失败也映射到 4xx(常见 422 / 409 / 404 等),body 仍可带明细更贴 REST 教科书;网关 / CDN / 通用 HTTP 中间件更好读;要和「业务码表」仔细对齐,避免一码多义

本文后续示例采用方案 A。 若你选 B,请删掉「业务失败也走 BusinessError + 200」这条路径,并让前端以 HTTP 状态为主、body 为辅——不要两套同时当主路径,那是草稿里最容易踩的坑。

一边写「错误时 HTTP 200 + error_code」,一边又提供 BadRequest / Unauthorized 等非 200 helper——这两种都合法,但必须挂在不同通道上,而不是混成「所有错误随便挑一个」。


精确定义:三字段与边界

统一信封是一段固定 JSON 形状;error_code == 0 表示业务成功,非 0 表示业务侧可枚举失败。

教学形状(字段名常见于不少国内互联网 API 约定,不是 RFC 强制标准):

{
  "error_code": 0,
  "error_msg": "",
  "data": {}
}
字段含义硬规则
error_code业务结果码0 = 成功;非 0 = 失败。前端先看它,再读 data
error_msg给人对齐的短说明面向客户端的文案;不要塞堆栈、SQL、内部主机名
data成功时的业务载荷error_code != 0 时通常为 null / 省略 / 空对象——团队定一种并写进约定

边界(必须写进前后端约定):

  1. HTTP ≠ 业务成败的唯一信号(方案 A)
    200 只表示「业务 handler 按信封回了」;成败看 error_code。
  2. 非 200 时 body 形态要声明
    网关 401/502 可能没有三字段信封。客户端应:status 非 2xx → 走协议错误分支;2xx → 再解析信封。
  3. 命名风格
    文中用 snake_case 仅作教学;若团队已定 camelCase,统一即可,别混用。
  4. error_code 与 HTTP 状态码数字无关
    业务码区间里的 400、401 不等于 HTTP 400、401。这是码表最容易误导的地方,下一节会刻意错开示例数字。

Go handler:教学封装怎么用

Handler 只负责:校验 → 调 service → 映射到「协议失败」或「业务信封」,且对外文案脱敏。

教学 import(占位模块名,按仓库改):

import (
    "yourmodule/pkg/errno"
    "yourmodule/pkg/response"
)

下面假设基于常见 Go HTTP 框架的 RequestContext(名称可替换);response / errno 为你们封装的包,不是某个公开标准库。

成功

// 教学示例:成功 → HTTP 200,error_code = 0
response.Success(c, data)
 
// 可选:带面向用户的短消息(仍建议成功时 error_msg 为空或固定文案,团队统一)
response.SuccessWithMessage(c, data, "操作成功")

双通道怎么落到 helper

场景通道教学调用HTTP(示例)
JSON 都解不开、缺必需 path协议 / 入参形态response.BadRequest(c, "用户ID不能为空")400
未带 Token / Token 被网关或中间件判无效协议 / 鉴权response.Unauthorized(c, "未授权访问")401
已登录但无权限常仍算协议/授权层response.Forbidden(c, "权限不足")403
「这个用户 ID 在业务上不存在」业务(方案 A)response.BusinessError(c, errno.UserNotFound, "用户不存在")200 + 非 0 code
未映射的内部故障协议 / 服务端response.ServerError(c, "服务暂时不可用")500;日志打明细,body 不打 err.Error()

若团队选方案 B:上表「用户不存在」可改为 HTTP 404 + 明细 body,并废弃「业务失败固定 200」。二选一写进 README,别让两个 helper 语义打架。

完整 handler(教学 / 脱敏)

func (h *UserHandler) GetUserInfo(ctx context.Context, c *app.RequestContext) {
    userID := c.Param("user_id")
    if userID == "" {
        // 通道 1:请求形态不合法 → HTTP 4xx
        response.BadRequest(c, "用户ID不能为空")
        return
    }
 
    user, err := h.userService.GetUserByID(ctx, userID)
    if err != nil {
        if errors.Is(err, service.ErrUserNotFound) {
            // 通道 2(方案 A):业务可理解失败 → HTTP 200 + 业务码
            response.BusinessError(c, errno.UserNotFound, errno.Message(errno.UserNotFound))
            return
        }
        // 内部错误:日志留细节,响应只给稳定文案
        hlog.Errorf("GetUserByID failed: user_id=%s err=%v", userID, err)
        response.ServerError(c, "服务暂时不可用")
        return
    }
 
    response.Success(c, map[string]any{
        "user": user.ToPublicJSON(),
    })
}

和常见草稿的关键差异:

  • 禁止 response.ServerError(c, "失败: "+err.Error()) 这类把内部错误串回客户端;
  • 业务「不存在」走 BusinessError + 业务码,而不是和「路径不存在」共用一个含糊的 NotFound,除非团队明确选择方案 B 并用 HTTP 404。

参数校验失败时同样脱敏

if err := c.BindAndValidate(&req); err != nil {
    hlog.Warnf("bind failed: %v", err) // 细节进日志
    response.BadRequest(c, "请求参数错误") // 对外固定文案;字段级提示可另做白名单映射
    return
}

错误码分层(教学示例区间)

下面是教学用区间划分,方便讲「系统 / 参数 / 鉴权 / 业务」分层;不是行业标准,也不是 RFC。按项目裁剪,合并或拆分都可以。

刻意注意:

  • 业务失败示例码用 10001 这类大整数,避免和 HTTP 400/401/404 数字撞车造成同义错觉;
  • 表中「建议 HTTP」列只在方案 A下成立:业务行是 200;协议行是 4xx/5xx;
  • 若选方案 B,请重画「建议 HTTP」列,不要照抄本表。

教学区间总览

区间(示例)用途方案 A 下典型 HTTP
0成功200
1xxxx 系统 / 基础设施DB、依赖超时等(对外常折叠成统一文案)多为 5xx;或 200+码(不推荐把未处理异常当业务成功路径)
2xxxx 请求参数校验失败、缺字段400
3xxxx 认证授权未登录、无权限、Token 失效401 / 403
4xxxx 业务可理解失败用户不存在、余额不足、状态不允许200 + 非 0
8xxxx / 9xxxx某业务域细分(设备、账号……)同业务:200 + 非 0

精简示例码(勿当成标准表抄进生产)

error_code(示例)说明通道建议 HTTP(方案 A)
0成功—200
10001服务内部错误(对外文案统一)协议 / 服务端500
20001参数错误协议 / 入参400
20002缺少必需参数协议 / 入参400
30001未授权协议 / 鉴权401
30002禁止访问协议 / 鉴权403
40001通用业务失败业务200
40002用户不存在业务200
40003用户已存在业务200
40004资源状态不允许该操作业务200
90001登录失败(可再细分原因码)业务或鉴权(团队定)200 或 401

errno 包侧建议:

const (
    OK              = 0
    Internal        = 10001
    InvalidArgument = 20001
    Unauthorized    = 30001
    UserNotFound    = 40002
)
 
// Message 返回稳定的对外文案;不要从 err.Error() 生成
func Message(code int) string { /* map 查找 */ }

监控建议(方案 A):HTTP 状态码盯网关与协议层;业务失败率另用 error_code != 0(或按码段)做指标。只盯 5xx 会漏掉大量「200 + 业务失败」。


前端怎么消费:先看 error_code

客户端固定顺序:HTTP 非 2xx → 协议错误;HTTP 2xx → 解析信封 → error_code !== 0 当业务失败 → 最后才用 data。

TypeScript(精简)

interface ApiEnvelope<T> {
  error_code: number;
  error_msg: string;
  data: T;
}
 
async function request<T>(url: string, init?: RequestInit): Promise<T> {
  const res = await fetch(url, init);
 
  // 通道 1:协议 / 网关层
  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`);
  }
 
  const body = (await res.json()) as ApiEnvelope<T>;
 
  // 通道 2:业务信封(方案 A 下成功也是 HTTP 200)
  if (body.error_code !== 0) {
    throw new Error(body.error_msg || `business error ${body.error_code}`);
  }
 
  return body.data;
}

Flutter / Dart(精简)

class ApiEnvelope<T> {
  final int errorCode;
  final String errorMsg;
  final T? data;
 
  ApiEnvelope({required this.errorCode, required this.errorMsg, this.data});
 
  bool get isOK => errorCode == 0;
 
  factory ApiEnvelope.fromJson(
    Map<String, dynamic> json,
    T Function(Object? raw)? parseData,
  ) {
    return ApiEnvelope(
      errorCode: json['error_code'] as int? ?? -1,
      errorMsg: json['error_msg'] as String? ?? '',
      data: parseData != null ? parseData(json['data']) : null,
    );
  }
}
 
// 使用:先判 HTTP,再判 errorCode,最后读 data

前端产品文案:优先用服务端下发的稳定 error_msg,或按 error_code 做本地 i18n 映射;不要假设 HTTP 200 就等于可以渲染 data。


常见坑

  1. 双通道没写进约定,只写进 helper 名字
    BusinessError 走 200、NotFound 走 404,但文档写「错误都看 error_code」——前端会漏判。约定里画清表:哪些错误看 HTTP,哪些看业务码。

  2. 业务码数字贴着 HTTP 状态码
    业务码 401 / 404 极易被新人当成 HTTP。教学上用 4xxxx;生产上至少文档加粗「与 HTTP 无关」。

  3. err.Error() 直接回给客户端
    会泄露表名、SQL、内部地址。对外固定文案 + 对内日志(带 request id)。

  4. 只监控 HTTP,不监控业务码
    方案 A 下大量失败是 200。看板要有 error_code != 0 比率,否则「全绿但用户下不了单」。

  5. 成功时 data 结构漂移、失败时乱塞半截 data
    失败时 data 策略定死(一律 null 或一律 {}),避免前端 optional 地狱。

  6. 网关改写状态码却不改信封
    例如网关把超时统一成 504,body 仍是旧业务 JSON——客户端要按「非 2xx 优先」处理,不要强行当业务码解析。

  7. 把限流 / 熔断也塞进「业务 200」
    限流更常见的是 HTTP 429(可带 Retry-After)。这和业务「余额不足」不是一类问题;混进业务码会让通用中间件失效。相关讨论见 /blog/rate_limit_circuit_breaker/。


小结

  1. 先定方案 A 或 B:双通道(协议 HTTP + 业务 200/信封)或始终 HTTP 状态码——不要两套主路径并存。本文教学示例采用 A。
  2. 信封三字段:error_code / error_msg / data;成功码为 0;前端 先 HTTP,再 error_code,最后 data。
  3. 对外文案脱敏:日志打 err,响应只给稳定消息;禁止把内部 err.Error() 回传。
  4. 错误码表是项目约定:本文区间仅为教学分层;业务码数字不要暗示等于 HTTP 状态码。
  5. 可行动落地顺序:定通道 → 定 JSON 形状 → 定码段与文案表 → handler 只做映射 → 前端封装一次判错 → 监控同时覆盖 HTTP 与业务码。

下一步可以补一份「你们仓库里的 response / errno 真实签名」对照表,以及网关 4xx/5xx 时 body 是否保证信封——这两项因项目而异,公开文写死容易误导。