前后端分离开发API响应规范-HTTP状态码、业务状态码-马育民老师

# 介绍

前后端分离 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://www.malaoshi.top/show_1GW3HpeZ6QKt.html