221 lines
6.8 KiB
Markdown
221 lines
6.8 KiB
Markdown
# **前后端接口规范 (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结构进行包装。
|
||
|
||
**字段命名必须遵循驼峰规则。**
|
||
|
||
```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):**
|
||
```json
|
||
{
|
||
"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):**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": [
|
||
{
|
||
"userId": 123,
|
||
"userName": "zhangsan",
|
||
"email": "zhangsan@example.com"
|
||
},
|
||
{
|
||
"userId": 124,
|
||
"userName": "lisi",
|
||
"email": "lisi@example.com"
|
||
}
|
||
],
|
||
"message": "success",
|
||
"timestamp": 1698393599000
|
||
}
|
||
```
|
||
|
||
* **分页响应体（推荐嵌套在`data`中）:**
|
||
```json
|
||
{
|
||
"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):**
|
||
```json
|
||
{
|
||
"code": 201, // 注意这里可以使用201更精确
|
||
"data": {
|
||
"userId": 125 // 通常返回创建成功后的主键ID或完整对象
|
||
},
|
||
"message": "用户创建成功",
|
||
"timestamp": 1698393599000
|
||
}
|
||
```
|
||
|
||
### **3.3 错误响应示例**
|
||
|
||
HTTP状态码为 `4xx` 或 `5xx` 时，同样使用统一结构。
|
||
|
||
* **用户不存在 (404 Not Found):**
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"data": null,
|
||
"message": "用户不存在",
|
||
"timestamp": 1698393599000
|
||
}
|
||
```
|
||
|
||
* **参数校验失败 (400 Bad Request):**
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"data": null,
|
||
"message": "邮箱格式不正确",
|
||
"timestamp": 1698393599000
|
||
}
|
||
```
|
||
|
||
* **无权限访问 (403 Forbidden):**
|
||
```json
|
||
{
|
||
"code": 403,
|
||
"data": null,
|
||
"message": "您没有权限执行此操作",
|
||
"timestamp": 1698393599000
|
||
}
|
||
```
|
||
|
||
### **3.4 请求体规范**
|
||
|
||
`POST`, `PUT`, `PATCH` 请求的Body也**必须使用JSON格式和驼峰命名法**。
|
||
|
||
* **创建用户 (POST /api/v1/users):**
|
||
```json
|
||
{
|
||
"userName": "wangwu",
|
||
"email": "wangwu@example.com",
|
||
"password": "encryptedPasswordString",
|
||
"phoneNumber": "13800138000"
|
||
}
|
||
```
|
||
|
||
* **更新用户邮箱 (PATCH /api/v1/users/123):**
|
||
```json
|
||
{
|
||
"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地址。
|
||
|
||
--- |