# **前后端接口规范 (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地址。

---