介绍

前后端分离 API 响应有两大开发规范，两种规范都是行业正规标准，只是设计思想、适用场景、前后端处理逻辑完全不同。

HTTP 状态码 和 业务状态码

• HTTP 状态码：传输协议层面的状态，由 HTTP 协议定义。
• 业务状态码：接口业务逻辑层面的状态，开发者自定义。

规范一：国内企业主流规范

统一 HTTP 200 + 自定义业务码

设计思想

• HTTP 状态码只管「网络、请求格式、服务器异常」
• 只要后端正常走完逻辑、能返回 JSON 响应，不管业务成功还是失败，HTTP 固定 200
• 业务结果：成功、失败、数据已存在、数据不存在、权限不足等，全部由响应体内自定义 code 控制

固定响应格式

{
  "code": 20000,   // 自定义业务状态码
  "msg": "操作提示文案",
  "data": null     // 业务数据
}

HTTP 状态码使用规则

仅以下情况不用 200：

• 400：请求参数格式错误、缺字段、类型不匹配
• 401：未登录、Token 过期
• 403：已登录但无操作权限
• 404：接口路由地址不存在
• 500：后端代码报错、数据库异常、服务崩溃

业务场景一律 HTTP=200：
数据已存在、数据不存在、新增失败、用户名重复、表单校验失败、余额不足等。

后端处理

所有业务判断正常返回 JSON，不抛 HTTP 异常码。

前端处理（Axios）

• 所有业务响应全部进入 then
• 拦截器只判断：res.data.code
  • 成功：走正常业务逻辑
  • 失败：直接弹窗 msg 提示
• 只有网络超时、500、404 才进入 catch

优点

1. 前端拦截器极简，统一提示、统一封装非常容易
2. 所有业务结果都在正常回调，不用混在异常里处理
3. 浏览器/调试工具不会标红，开发体验好
4. 小程序、App、移动端兼容性无坑
5. 团队协作成本低，新人上手快

缺点

1. 不完全符合标准 REST 语义化设计
2. 对外公开开放 API 时，第三方调用方不够直观

适用场景

• 国内 90% 以上 Vue/React 前后端分离管理系统
• 内部业务系统、后台项目、CRUD 系统
• 团队协作、中小型项目、教学实训项目
• 你当前正在开发的标签管理这类业务系统

规范二：标准 RESTful 规范

HTTP 状态码承载业务语义

设计思想

• 不用自定义业务码
• 直接用原生 HTTP 状态码表达业务结果
• HTTP 状态码同时承担「协议传输 + 业务逻辑」两层含义

常用 HTTP 码与业务对应

• 200：查询成功、普通操作成功
• 201：新增数据成功
• 204：删除成功（无返回体）
• 400：参数错误、业务校验失败
• 401：未登录、认证失败
• 403：权限不足
• 404：资源/数据不存在
• 409：数据冲突、已存在（同名重复）
• 500：服务器内部异常

响应格式

可返回简洁数据，也可带提示信息，无强制统一业务 code：

{
  "message": "数据已存在"
}

后端处理

不同业务场景手动返回对应 HTTP 状态码。

前端处理（Axios）

• 2xx 进入 then
• 4xx/5xx 全部进入 catch
• 需要在 catch 里再细分：网络错误、404、409、500，分别做提示和处理

优点

1. 严格遵循 REST 设计理念，语义直观
2. 接口自解释，看状态码就知道业务结果
3. 适合对外公开 API、第三方对接、开源项目

缺点

1. 前端拦截器复杂度大幅提升，要在异常里处理业务提示
2. 4xx/5xx 浏览器控制台标红，开发调试观感差
3. 部分小程序、老旧客户端对非200状态码有兼容问题
4. 统一全局弹窗、统一异常封装麻烦

适用场景

• 外企、海外项目、开源后端项目
• 对外提供开放平台 API、第三方调用接口
• 严格遵循 REST 架构设计的团队

对比总结

选型建议

1. 做国内 Vue/React 后台、业务系统、内部项目
   👉 强制选用：统一 HTTP 200 + 自定义业务码

2. 做对外开放平台、给第三方调用、开源项目
   👉 选用：RESTful 原生 HTTP 状态码规范

国内规范中的 业务状态码规范

HTTP 状态码配合规则：

1. 所有业务码，HTTP 状态码一律 200。
2. 只有真正协议级错误才用非200：
   • 400：请求参数格式非法（框架层面校验）
   • 401：未鉴权拦截
   • 404：接口地址不存在
   • 500：代码未捕获异常

一、范式1：极简主流版

采用该规范的企业：美团、京东、大部分中小企业、后台管理系统

规则

• code = 0 → 成功
• code ≠ 0 → 失败

响应格式

{
  "code": 0,
  "msg": "操作成功",
  "data": {...}
}

失败示例：

{
  "code": 1001,
  "msg": "标签名称已存在",
  "data": null
}

特点

1. 最简单、最好记
2. 前端拦截器只需要一句：

   if(res.data.code === 0) 成功 else 弹窗提示
   

3. 绝大多数Vue后台、外包、中小企业、美团、京东都是这套

错误码分段示例

• 0 成功
• 1xxx 通用业务错误
• 2xxx 用户登录权限错误
• 3xxx 各业务模块自定义错误

二、范式2：大厂规范派

采用该规范的企业：阿里、字节

响应格式

{
  "code": 20000,
  "msg": "操作成功",
  "data": {}
}

业务码区间总体规划

细分业务码明细

1. 成功码 20000 段

2. 通用错误 40000 段

40000 基础通用：

40100 登录认证：

40300 权限相关：

40400 参数校验：

业务模块错误 50000 段

规则：每个业务模块占 100 个号码

• 标签模块：50100~50199
• 用户模块：50200~50299
• 文件模块：50300~50399

示例：

系统级错误 60000 段

使用规则

1. 正常业务成功 统一返回 20000。
2. 数据已存在、不存在、重复 用 40001 / 40002 / 40003。
3. 登录、Token、权限 走 401xx、403xx 区间。
4. 表单参数校验 走 404xx 区间。
5. 自己业务特有错误 用 50xxx 自定义，不占用通用码。
6. 后端崩溃、数据库报错 用 60xxx。

一句话总结

• 成功全用 20000
• 通用错误 40xxx
• 业务专属 50xxx
• 系统异常 60xxx
• 所有接口 HTTP 固定 200

特点

• 偏大型大厂、规范更严谨
• 不用 0 做成功码，用 20000
• 分段更细，适合超大型团队多模块开发

为什么会有这两种？

1）0代表成功

追求简单、开发快、前后端好约定
适合：中小型项目、管理后台、外包、创业项目、普通公司

2）20000代表成功

追求规范、分区清晰、大型团队多业务模块隔离
适合：阿里、字节、大型中台、超复杂多模块系统

总结

国内业务状态码就两大派系：

1. 极简派（最常用）

• 0 成功
• 非0 失败
• 适合 90% 普通前后端分离项目

1. 大厂规范派

• 20000 成功
• 4xxxx 通用错误
• 5xxxx 业务错误
• 6xxxx 系统错误
• 适合大型团队、中台、大厂

选型建议

直接用：0 成功，非0 失败

理由：

• 最简单
• 前端拦截器最好写
• 对接别人接口最常见
• 自己开发不用记一堆数字

原文出处：/show_1GW3HpeZ6QKt.html