API规范文档

豆芽包
5 阅读9分钟

告别接口混乱！一份能直接落地的API规范文档

大家好，我是豆芽包。

做后端开发、前后端联调、微服务对接的同学肯定都懂：没有统一的API规范，就是团队协作的灾难。

前端对着一堆乱七八糟的接口地址、参数、返回值抓狂，后端改个字段全团队同步不及时，测试用例写不明白，线上排查问题更是头大。其实一份规范、清晰、可落地的API文档，不仅能解决协作痛点，还能提升接口复用率、降低维护成本、减少线上BUG。

今天这篇文章，不讲空泛的理论，全是实战干货：从基础命名、请求规范、参数设计、返回格式、错误处理等核心维度，梳理一套完整的API接口规范，搭配通俗易懂的例子

一、为什么必须制定API规范？

先聊聊核心价值，避免大家觉得“规范是束缚”：

  • 降低协作成本：前后端、测试、运维不用反复沟通接口细节，文档即契约
  • 提升可维护性：统一风格后，新人接手、老代码迭代一目了然
  • 减少兼容问题：参数、返回值、状态码标准化，避免前端适配多种格式
  • 方便自动化测试：规范的接口更容易做单元测试、接口自动化
  • 适配生态工具：符合RESTful、OpenAPI规范，能无缝对接Swagger、Postman、APIFox等工具

二、核心API规范细则

2.1 接口地址（URL）规范

URL是接口的门面，必须清晰、语义化、无歧义，遵循以下规则：

  • 统一用小写字母，禁止驼峰、大写、中文、特殊字符（除了分隔符）
  • 资源用复数形式，比如用户是users，订单是orders，避免单数user、order
  • 用短横线-分隔单词，禁止下划线_、空格
  • 层级清晰，按「域名/版本/资源/子资源」结构设计
  • 禁止在URL里携带动作动词（增删改查用HTTP方法体现）

❌ 反例

http://xxx.com/getUserInfo
http://xxx.com/api/userdetail/1
http://xxx.com/Api/V1/User/Delete

✅ 正例

https://api.xxx.com/v1/users
https://api.xxx.com/v1/users/123/orders
https://api.xxx.com/v1/goods-category

补充说明

公共接口建议加版本号（v1/v2），方便后续迭代兼容老接口；内部微服务可省略域名，直接用/service/版本/资源。

2.2 HTTP请求方法规范

用HTTP方法语义化表达操作意图，不要所有接口都用POST：

HTTP方法语义适用场景示例
GET查询/获取资源列表查询、详情查询，无副作用GET /v1/users 查询用户列表；GET /v1/users/123 查询单个用户
POST新增资源创建单条/批量数据POST /v1/users 新增用户
PUT全量更新资源替换整个资源数据PUT /v1/users/123 更新用户全部信息
PATCH局部更新资源只修改单个/部分字段PATCH /v1/users/123 只修改用户手机号
DELETE删除资源删除单条/批量数据DELETE /v1/users/123 删除用户

💡 实战小贴士：国内很多团队为了规避缓存、跨域、参数长度问题，会把查询也用POST，这种情况建议在文档里明确标注，保持团队统一即可。

2.3 请求参数规范

参数分为路径参数、查询参数、请求体参数，必须统一格式、必填校验、注释清晰。

通用规则

  • 参数名用小驼峰（camelCase） ，比如userName、pageSize，禁止下划线、大写
  • 必填参数必须标注，非必填参数设默认值
  • 参数类型严格定义：string、number、boolean、array、object
  • 敏感参数（密码、手机号）建议加密传输

参数位置区分

  • 路径参数：URL里的动态值，用{}包裹，比如/users/{userId}
  • 查询参数：URL?后拼接，适用于GET请求的筛选、分页，比如/users?pageNum=1&pageSize=10
  • 请求体参数：POST/PUT/PATCH的body，统一用JSON格式，禁止form-data（文件上传除外）

参数示例（用户列表查询）

// 查询参数
{
  "pageNum": 1,        // 页码，必填，默认1
  "pageSize": 10,      // 每页条数，必填，默认10
  "userName": "张三",  // 用户名，非必填，模糊查询
  "status": 1          // 用户状态，非必填，1-正常 0-禁用
}

2.4 请求头（Header）规范

Header用于传递鉴权、版本、格式等公共信息，避免冗余参数塞到body里：

Header字段必填说明
Content-Type是固定为application/json;charset=utf-8，文件上传除外
Authorization是令牌信息，格式：Bearer {token}
Api-Version否接口版本，比如v1
Request-Id否请求唯一标识，用于链路追踪

2.5 响应数据规范

这是前后端协作最核心的部分，所有接口必须返回统一格式，前端不用适配多种结构。

统一响应体结构

{
  "code": 200,             // 业务状态码，非HTTP状态码
  "msg": "请求成功",        // 提示信息，成功/失败描述
  "data": {},              // 响应数据，无数据时返回null/空对象/空数组
  "requestId": "xxx123456" // 请求ID，方便排查问题
}

字段说明

  • code：业务状态码，200=成功，非200=失败，禁止用HTTP 404/500表示业务失败
  • msg：人性化提示，前端可直接展示给用户，禁止返回英文/乱码
  • data：核心数据，列表用数组，单条用对象，无数据返回[]或{}
  • requestId：全链路唯一ID，运维、测试排查问题神器

分页列表响应示例

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "total": 100,     // 总条数
    "pageNum": 1,     // 当前页码
    "pageSize": 10,   // 每页条数
    "pages": 10,      // 总页数
    "list": [
      {
        "userId": 123,
        "userName": "张三",
        "phone": "138****1234",
        "status": 1,
        "createTime": "2026-03-11 12:00:00"
      }
    ]
  },
  "requestId": "req_20260311120000_123456"
}

2.6 错误处理规范

失败响应严格遵循统一格式，状态码语义化、提示信息清晰，不抛原生异常给前端。

通用业务状态码定义

code含义场景
200请求成功正常响应
400参数错误必填参数为空、参数格式非法
401未登录/令牌失效token过期、未携带token
403无权限接口权限不足、资源无访问权
404资源不存在查询的用户/订单不存在
500服务器异常系统内部错误，需屏蔽敏感信息

失败响应示例

{
  "code": 400,
  "msg": "用户名不能为空",
  "data": null,
  "requestId": "req_20260311120100_654321"
}

2.7 其他补充规范

  • 时间格式：统一返回yyyy-MM-dd HH:mm:ss字符串，禁止时间戳
  • 脱敏处理：手机号、身份证、邮箱等敏感数据必须脱敏展示
  • 接口注释：每个接口必须写清楚功能、作者、创建时间、更新日志
  • 版本迭代：老接口不删，新增v2版本接口，平滑过渡
  • 接口限流：公共接口标注限流规则，避免恶意请求

三、完整API接口文档示例（开发实战版）

以下是用户管理模块的完整接口文档，直接复制到Swagger/APIFox/Markdown里就能用，涵盖增删改查全场景。

文档基础信息

  • 文档标题：用户管理模块API接口文档
  • 接口域名：api.xxx.com
  • 接口版本：v1
  • 作者：后端开发组
  • 更新时间：2026-03-11

接口1：查询用户列表

  • 接口地址：GET /v1/users
  • 接口功能：分页查询用户列表，支持模糊搜索、状态筛选
  • 请求头：Content-Type: application/json;charset=utf-8、Authorization: Bearer {token}

请求参数（查询参数）

参数名类型必填默认值说明
pageNumnumber是1当前页码
pageSizenumber是10每页条数，最大50
userNamestring否-用户名，模糊查询
statusnumber否-用户状态：1-正常 0-禁用

响应示例

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "total": 120,
    "pageNum": 1,
    "pageSize": 10,
    "pages": 12,
    "list": [
      {
        "userId": 1001,
        "userName": "张三",
        "phone": "138****1234",
        "email": "zhangsan@xxx.com",
        "status": 1,
        "createTime": "2026-03-01 09:30:00",
        "updateTime": "2026-03-10 15:20:00"
      }
    ]
  },
  "requestId": "req_20260311143000_789012"
}

接口2：新增用户

  • 接口地址：POST /v1/users
  • 接口功能：新增单个用户信息
  • 请求头：同上

请求参数（请求体）

参数名类型必填说明
userNamestring是用户名，长度2-20
phonestring是手机号，格式校验
passwordstring是密码，加密传输
emailstring否邮箱地址

响应示例

{
  "code": 200,
  "msg": "新增成功",
  "data": {
    "userId": 1002
  },
  "requestId": "req_20260311143500_345678"
}

接口3：查询单个用户详情

  • 接口地址：GET /v1/users/{userId}
  • 接口功能：根据用户ID查询详情
  • 路径参数：userId（用户ID，必填）

响应示例

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "userId": 1001,
    "userName": "张三",
    "phone": "138****1234",
    "email": "zhangsan@xxx.com",
    "status": 1,
    "createTime": "2026-03-01 09:30:00",
    "updateTime": "2026-03-10 15:20:00"
  },
  "requestId": "req_20260311144000_901234"
}

接口4：删除用户

  • 接口地址：DELETE /v1/users/{userId}
  • 接口功能：根据用户ID删除用户（逻辑删除）
  • 路径参数：userId（用户ID，必填）

响应示例

{
  "code": 200,
  "msg": "删除成功",
  "data": null,
  "requestId": "req_20260311144500_567890"
}

四、写在最后

API规范不是一成不变的，核心是团队统一、落地可行。不用盲目追求纯RESTful，适合自己业务的才是最好的。

建议大家把这套规范整理成团队文档，搭配Swagger、APIFox等工具自动生成接口文档，既能减少手写成本，又能保证规范落地。后续接口迭代，只要遵循这套规则，就能彻底告别“接口扯皮”的尴尬。

avatar
文章
阅读
粉丝