
Hello,我是小兔大白糖。 联调第 N 天:后端说「接口成功了,看 HTTP 200」;前端说「业务失败了,用户不存在」——两边都没错,只是约定没钉死。写成这篇,给要给自家 API 定一套统一响应信封、并和前端对齐判错规则的初中级后端同学。
说明:文中包路径、错误码区间、handler 示例均为教学脱敏写法,不是某家公司的内部规范,也不是行业标准。读完带走的是可行动的心智模型,不是一张必须照抄的码表。
估计阅读时间:14 分钟
目录
- 为什么现在要关心
- 心智模型:信封 vs HTTP 状态码
- 精确定义:三字段与边界
- Go handler:教学封装怎么用
- 错误码分层(教学示例区间)
- 前端怎么消费:先看 error_code
- 常见坑
- 小结
为什么现在要关心
没有统一信封时,前后端会在「这次算不算失败」上反复对不上。
常见现场:
| 你看到的现象 | 常见真相 |
|---|---|
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。
类比局限一句说清:路况类比解释「谁先失败、监控先看哪一层」;解释不了 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 / 省略 / 空对象——团队定一种并写进约定 |
边界(必须写进前后端约定):
- HTTP ≠ 业务成败的唯一信号(方案 A)
200只表示「业务 handler 按信封回了」;成败看error_code。 - 非 200 时 body 形态要声明
网关 401/502 可能没有三字段信封。客户端应:status非 2xx → 走协议错误分支;2xx → 再解析信封。 - 命名风格
文中用snake_case仅作教学;若团队已定camelCase,统一即可,别混用。 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。
常见坑
-
双通道没写进约定,只写进 helper 名字
BusinessError走 200、NotFound走 404,但文档写「错误都看 error_code」——前端会漏判。约定里画清表:哪些错误看 HTTP,哪些看业务码。 -
业务码数字贴着 HTTP 状态码
业务码401/404极易被新人当成 HTTP。教学上用4xxxx;生产上至少文档加粗「与 HTTP 无关」。 -
err.Error()直接回给客户端
会泄露表名、SQL、内部地址。对外固定文案 + 对内日志(带 request id)。 -
只监控 HTTP,不监控业务码
方案 A 下大量失败是 200。看板要有error_code != 0比率,否则「全绿但用户下不了单」。 -
成功时
data结构漂移、失败时乱塞半截data
失败时data策略定死(一律null或一律{}),避免前端 optional 地狱。 -
网关改写状态码却不改信封
例如网关把超时统一成 504,body 仍是旧业务 JSON——客户端要按「非 2xx 优先」处理,不要强行当业务码解析。 -
把限流 / 熔断也塞进「业务 200」
限流更常见的是 HTTP 429(可带Retry-After)。这和业务「余额不足」不是一类问题;混进业务码会让通用中间件失效。相关讨论见 /blog/rate_limit_circuit_breaker/。
小结
- 先定方案 A 或 B:双通道(协议 HTTP + 业务 200/信封)或始终 HTTP 状态码——不要两套主路径并存。本文教学示例采用 A。
- 信封三字段:
error_code/error_msg/data;成功码为0;前端 先 HTTP,再error_code,最后data。 - 对外文案脱敏:日志打
err,响应只给稳定消息;禁止把内部err.Error()回传。 - 错误码表是项目约定:本文区间仅为教学分层;业务码数字不要暗示等于 HTTP 状态码。
- 可行动落地顺序:定通道 → 定 JSON 形状 → 定码段与文案表 → handler 只做映射 → 前端封装一次判错 → 监控同时覆盖 HTTP 与业务码。
下一步可以补一份「你们仓库里的 response / errno 真实签名」对照表,以及网关 4xx/5xx 时 body 是否保证信封——这两项因项目而异,公开文写死容易误导。