前后端分离开发API响应规范-HTTP状态码、业务状态码 作者：马育民 • 2026-05-10 19:01 • 阅读：10003 # 介绍 前后端分离 API 响应有两大开发规范，两种规范都是**行业正规标准**，只是设计思想、适用场景、前后端处理逻辑完全不同。 ### HTTP 状态码 和 业务状态码 - **HTTP 状态码**：传输协议层面的状态，由 HTTP 协议定义。 - **业务状态码**：接口业务逻辑层面的状态，开发者自定义。 # 规范一：国内企业主流规范 统一 HTTP 200 + 自定义业务码 ### 设计思想 - **HTTP 状态码只管「网络、请求格式、服务器异常」** - **只要后端正常走完逻辑、能返回 JSON 响应**，不管业务成功还是失败，**HTTP 固定 200** - 业务结果：成功、失败、数据已存在、数据不存在、权限不足等，**全部由响应体内自定义 code 控制** ### 固定响应格式 ```json { "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**： ```json { "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 架构设计的团队 --- # 对比总结 | 维度 | 规范一：全200+自定义业务码 | 规范二：RESTful HTTP语义码 | |------|----------------------------|---------------------------| | 设计核心 | HTTP只管通不通，业务靠内部code | HTTP直接表达业务结果 | | 业务失败HTTP码 | 固定 200 | 用 400/404/409 等 | | 前端接收位置 | 全部进 then | 2xx进then，4xx/5xx进catch | | 统一提示 | 极易封装 | 复杂，需在异常分支处理 | | 开发调试 | 控制台不标红，体验好 | 4xx/5xx 全部标红 | | 兼容性 | 全平台无坑 | 部分移动端偶有兼容问题 | | 主流使用 | 国内业务系统标配 | 开源、外企、开放API标配 | | 推荐项目 | 内部管理系统、前后端分离业务项目 | 对外接口、开源服务 | --- # 选型建议 1. **做国内 Vue/React 后台、业务系统、内部项目** 👉 强制选用：**统一 HTTP 200 + 自定义业务码** 2. **做对外开放平台、给第三方调用、开源项目** 👉 选用：**RESTful 原生 HTTP 状态码规范** # 国内规范中的 业务状态码规范 HTTP 状态码配合规则： 1. 所有业务码，**HTTP 状态码一律 200**。 2. 只有真正协议级错误才用非200： - 400：请求参数格式非法（框架层面校验） - 401：未鉴权拦截 - 404：接口地址不存在 - 500：代码未捕获异常 ## 一、范式1：极简主流版 采用该规范的企业：美团、京东、大部分中小企业、后台管理系统 #### 规则 - **code = 0 → 成功** - **code ≠ 0 → 失败** #### 响应格式 ```json { "code": 0, "msg": "操作成功", "data": {...} } ``` 失败示例： ```json { "code": 1001, "msg": "标签名称已存在", "data": null } ``` #### 特点 1. **最简单、最好记** 2. 前端拦截器只需要一句： ```js if(res.data.code === 0) 成功 else 弹窗提示 ``` 3. 绝大多数**Vue后台、外包、中小企业、美团、京东**都是这套 #### 错误码分段示例 - `0` 成功 - `1xxx` 通用业务错误 - `2xxx` 用户登录权限错误 - `3xxx` 各业务模块自定义错误 --- ## 二、范式2：大厂规范派 采用该规范的企业：阿里、字节 ### 响应格式 ```json { "code": 20000, "msg": "操作成功", "data": {} } ``` ### 业务码区间总体规划 | 码段区间 | 类型 | 说明 | |--------|------|------| | 20000~20999 | 成功区间 | 所有正常操作成功 | | 30000~30999 | 提示类 | 业务友好提示，不算错误 | | 40000~40999 | 通用错误 | 参数、登录、权限、数据通用错误 | | 50000~50999 | 业务自定义错误 | 各业务模块专属错误 | | 60000~60999 | 系统级错误 | 服务器、数据库、第三方服务异常 | --- ### 细分业务码明细 #### 1. 成功码 20000 段 | 业务码 | 含义 | |--------|------| | 20000 | 操作成功 | | 20001 | 查询成功 | | 20002 | 新增成功 | | 20003 | 修改成功 | | 20004 | 删除成功 | #### 2. 通用错误 40000 段 40000 基础通用： | 业务码 | 含义 | |--------|------| | 40000 | 请求失败 | | 40001 | 数据已存在 | | 40002 | 数据不存在 | | 40003 | 数据重复 | | 40004 | 数据已禁用/已失效 | 40100 登录认证： | 业务码 | 含义 | |--------|------| | 40100 | 未登录 | | 40101 | Token 无效 | | 40102 | Token 已过期 | | 40103 | 账号密码错误 | | 40104 | 账号已被封禁 | 40300 权限相关： | 业务码 | 含义 | |--------|------| | 40300 | 无操作权限 | | 40301 | 角色权限不足 | | 40302 | 禁止访问该资源 | 40400 参数校验： | 业务码 | 含义 | |--------|------| | 40400 | 参数校验失败 | | 40401 | 必填参数不能为空 | | 40402 | 参数格式错误 | | 40403 | 参数超出范围 | #### 业务模块错误 50000 段 规则：**每个业务模块占 100 个号码** - 标签模块：50100~50199 - 用户模块：50200~50299 - 文件模块：50300~50399 示例： | 业务码 | 含义 | |--------|------| | 50100 | 标签名称已存在 | | 50101 | 标签不存在 | | 50102 | 标签关联数据无法删除 | #### 系统级错误 60000 段 | 业务码 | 含义 | |--------|------| | 60000 | 服务器内部异常 | | 60001 | 数据库操作失败 | | 60002 | 第三方接口调用失败 | | 60003 | 服务繁忙，请稍后重试 | --- #### 使用规则 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% 普通前后端分离项目 2. **大厂规范派** - `20000` 成功 - `4xxxx` 通用错误 - `5xxxx` 业务错误 - `6xxxx` 系统错误 - 适合大型团队、中台、大厂 --- ## 选型建议 **直接用：0 成功，非0 失败** 理由： - 最简单 - 前端拦截器最好写 - 对接别人接口最常见 - 自己开发不用记一堆数字 原文出处：http://malaoshi.top/show_1GW3HpeZ6QKt.html