2025-08-29 14:50:43 +08:00

6.8 KiB

Raw Permalink Blame History

前后端接口规范 (RESTful API)

文档修订记录

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

1. 核心原则

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

6.8 KiB Raw Permalink Blame History Unescape Escape