前后端接口规范 (RESTful API)

文档修订记录

版本号	修订日期	修订内容	修订人	审核人
V1.0	2023-10-27	初稿创建，明确驼峰命名法	[你的名字]	[审核人名字]
V1.1	2023-11-10	增加分页响应体示例

---

1. 核心原则

1. RESTful设计：接口设计遵循RESTful架构风格，以资源为中心。
2. HTTPS协议：所有API必须通过HTTPS协议提供，保证传输安全。
3. 无状态性：每次请求都必须包含处理该请求所需的所有信息，服务端不存储用户会话状态。
4. 版本控制：API版本应在URL中清晰体现，以便未来平滑升级和兼容。
5. 数据格式：请求体与响应体统一使用 application/json 格式。
6. 命名规范：所有请求参数、响应体、请求体中的字段名，必须使用驼峰命名法（camelCase）。

2. 接口设计规范

2.1 URL 设计

• 格式：https://api.example.com/{api-version}/{resource}[/{identifier}[/sub-resource]]
• 版本：URL中必须包含版本号 v{版本号}，例如：/api/v1/users。
• 资源名：使用名词复数形式表示资源集合，如 /users, /products。
• 资源操作：通过HTTP方法表达操作意图，而不是在URL中使用动词。
  • 正确示例：DELETE /api/v1/users/123
  • 错误示例：GET /api/v1/deleteUser?id=123
• 资源嵌套：嵌套层级不建议超过两级。
  • 示例：GET /api/v1/users/123/orders (获取用户ID为123的所有订单)

2.2 HTTP 方法使用

HTTP 方法	语义	示例
GET	获取资源（一个或多个）	GET /api/v1/users
POST	创建新资源	POST /api/v1/users
PUT	全量更新目标资源（提供资源的完整属性）	PUT /api/v1/users/123
PATCH	部分更新目标资源（仅提供需要修改的属性）	PATCH /api/v1/users/123
DELETE	删除指定资源	DELETE /api/v1/users/123

2.3 查询参数

用于GET请求的过滤、分页、排序等场景。

• 分页参数：
  • pageNum: 当前页码，从1开始。
  • pageSize: 每页记录数。
• 排序参数：
  • sortBy: 排序字段，e.g., createTime。
  • sortOrder: 排序顺序，asc 或 desc。
• 示例： GET /api/v1/products?pageNum=1&pageSize=20&sortBy=createTime&sortOrder=desc&category=books

3. 请求与响应规范

3.1 通用响应体结构

所有HTTP状态码为 2xx 的响应，必须使用以下统一的JSON结构进行包装。

字段命名必须遵循驼峰规则。

{
  "code": 200,
  "data": ...,
  "message": "请求成功",
  "timestamp": 1698393599000
}

字段	类型	必须	说明
code	Number	是	业务状态码，可与HTTP状态码一致，也可自定义。成功通常为200。
data	Object | Array | Null	是	响应返回的核心数据。成功时返回对象或数组，失败时可为null。
message	String	是	对本次请求结果的人性化描述，可用于前端直接展示。
timestamp	Number	是	服务器响应时的Unix时间戳（毫秒级）。

3.2 成功响应示例

• 获取单个用户 (GET /api/v1/users/123):

  {
    "code": 200,
    "data": {
      "userId": 123,
      "userName": "zhangsan",
      "email": "zhangsan@example.com",
      "avatarUrl": "https://...",
      "createTime": "2023-01-01T10:00:00Z"
    },
    "message": "success",
    "timestamp": 1698393599000
  }
  

• 获取用户列表 (GET /api/v1/users):

  {
    "code": 200,
    "data": [
      {
        "userId": 123,
        "userName": "zhangsan",
        "email": "zhangsan@example.com"
      },
      {
        "userId": 124,
        "userName": "lisi",
        "email": "lisi@example.com"
      }
    ],
    "message": "success",
    "timestamp": 1698393599000
  }
  

• 分页响应体（推荐嵌套在data中）:

  {
    "code": 200,
    "data": {
      "list": [
        {"userId": 123, "userName": "zhangsan"},
        {"userId": 124, "userName": "lisi"}
      ],
      "total": 2,
      "pageNum": 1,
      "pageSize": 10,
      "totalPages": 1
    },
    "message": "success",
    "timestamp": 1698393599000
  }
  

• 创建用户成功 (POST /api/v1/users):

  {
    "code": 201, // 注意这里可以使用201更精确
    "data": {
      "userId": 125 // 通常返回创建成功后的主键ID或完整对象
    },
    "message": "用户创建成功",
    "timestamp": 1698393599000
  }
  

3.3 错误响应示例

HTTP状态码为 4xx 或 5xx 时，同样使用统一结构。

• 用户不存在 (404 Not Found):

  {
    "code": 404,
    "data": null,
    "message": "用户不存在",
    "timestamp": 1698393599000
  }
  

• 参数校验失败 (400 Bad Request):

  {
    "code": 400,
    "data": null,
    "message": "邮箱格式不正确",
    "timestamp": 1698393599000
  }
  

• 无权限访问 (403 Forbidden):

  {
    "code": 403,
    "data": null,
    "message": "您没有权限执行此操作",
    "timestamp": 1698393599000
  }
  

3.4 请求体规范

POST, PUT, PATCH 请求的Body也必须使用JSON格式和驼峰命名法。

• 创建用户 (POST /api/v1/users):

  {
    "userName": "wangwu",
    "email": "wangwu@example.com",
    "password": "encryptedPasswordString",
    "phoneNumber": "13800138000"
  }
  

• 更新用户邮箱 (PATCH /api/v1/users/123):

  {
    "email": "new_email@example.com" // 部分更新，只传需要修改的字段
  }
  

4. 安全与认证

• 认证：使用 JWT (JSON Web Token) 作为认证机制。
• 传输：JWT应放在HTTP请求头的 Authorization 字段中，值为 Bearer {token}。

  Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
  

• 接口权限：敏感接口必须在后端校验用户身份和权限。

5. 文档与维护

• API文档：必须使用 Swagger (OpenAPI 3.0) 或 Apifox、YApi 等工具在线维护实时API文档。
• 变更沟通：任何接口的变更（包括字段增删、语义修改）必须提前通知所有前端、客户端、测试相关人员，并同步更新文档。
• 弃用策略：旧版本API应保留一段时间，并在文档中标记为deprecated，给出替代的新版本API地址。

---