为什么制定规范

统一公司HTTP对外API接口输出标准，消除多技术栈、多业务服务之间 接口返回格式差异，降低前后端联调成本，方便错误处理、日志排查与自动化测试，有以下好处：

1. 降低前端对接成本：一套解析逻辑即可对接全部后端接口，无需为不同服务做差异化适配，减少联调bug。
2. 统一异常与错误处理：标准化业务错误码、提示信息，便于前端统一弹窗提示、错误埋点统计。
3. 便于问题排查定位：统一requestId链路追踪，结合日志可以快速定位接口故障。
4. 提升接口可读性与一致性：对分页、空值、时间、ID、敏感字段做统一约束，减少理解歧义。
5. 便于网关、测试、监控系统接入：标准化报文有利于自动化测试、接口监控统一解析处理。

一、统一响应体格式

成功响应

成功时 HTTP 状态码是 200，业务 code 也是 200：

{
  "code": 200,
  "msg": "操作成功",
  "data": {},
  "requestId": "uuid-xxxxxx"
}

失败响应

业务异常，HTTP状态码依旧 200，业务 code 标识错误

{
  "code": 40001,
  "msg": "用户名密码错误",
  "data": null,
  "requestId": "uuid-xxxxxx"
}

字段说明

约定

1. 无论成功失败，结构体字段不能缺失；data失败必须为 null，不要省略key
2. HTTP状态码尽量统一用 200，业务错误全部走 code；鉴权失败可返回 401，权限不足 403
3. requestId 从请求头 X‑Request‑Id获取，没有则生成UUID

二、业务错误码设计规范

码段划分

示例

200     成功
40001   账号密码错误
40002   参数校验失败
40100   token失效/未登录
40300   无操作权限
40400   资源不存在
50001   服务器内部异常
50002   第三方接口调用失败

禁止：直接把原始异常堆栈丢给前端；堆栈只输出到服务端日志。

三、分页接口返回规范

data 里面套分页结构体

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 123,
    "pageNum": 1,
    "pageSize": 10,
    "pages": 13,
    "list": [
      {"id":1,"name":"xxx"}
    ]
  },
  "requestId": "uuid-xxxxxx"
}

字段解释

• pageNum：当前页码，从1开始
• pageSize：每页条数
• total：总条数
• pages：总页数
• list：实际业务数组

查询参数：pageNum:int=1, pageSize:int=10，后端做上限保护，pageSize最大100，防止大查询拖垮数据库。

四、企业开发其它强制规范

1. 时间字段。全部返回 datetime 字符串，格式：yyyy‑MM‑dd HHss，禁止返回对象，禁止返回时间戳混用。
2. 布尔值：返回true/false，不要用0/1数字代替布尔。
3. 空数组：查询无数据返回[]，不要返回null。
4. ID：数据库bigint，返回给前端建议转字符串，避免JS丢失精度。
5. 安全：接口不要返回密码、salt等敏感字段；pydantic model过滤敏感字段。
6. 请求头：透传X‑Request‑Id，日志打印该ID，方便定位问题。
7. openapi文档：所有接口写summary、description，pydantic字段写description，自动生成文档给前端看。
8. 不要返回多余字段：数据库字段不要全部直接透传到response，使用输出model做裁剪。

五、不推荐的写法

• ❌ 成功返回{"code":200,"data":{}}，失败返回{"code":400,"msg":"xxx"}，data字段缺失，前端解析报错。
• ❌ 异常直接raise HTTPException，返回FastAPI原生格式，前后端两套返回体。
• ❌ 把堆栈信息暴露给前端。
• ❌ http状态码乱用，业务错误返回4xx/5xx http码，前端axios统一拦截混乱。
• ❌ 分页接口list为null，没有返回空数组。

原文出处：/show_1GW3twY6jORG.html