commit a3914ab2237b781850d521fe5fd339c209976749
Author: ivo <ivo_d@icloud.com>
Date:   Fri Aug 29 14:50:43 2025 +0800

    init

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..08599dc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,221 @@
+# **前后端接口规范 (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地址。
+
+---
\ No newline at end of file