前後端對接時，API 設計標準不統一容易產生很多摩擦。整理一下 RESTful 的核心規範，方便和後端對齊。

REST 的核心思想

REST 把 Web 資源抽象成 URI，用 HTTP 方法表示操作：

資源：/users, /products/123, /orders
操作：
  GET     獲取資源（不修改數據）
  POST    創建資源
  PUT     全量更新資源
  PATCH   部分更新資源
  DELETE  刪除資源

URI 設計

✅ 好的設計（名詞複數，層級表示從屬關係）：
GET    /users                   獲取用户列表
GET    /users/123               獲取用户 123
POST   /users                   創建用户
PUT    /users/123               更新用户 123（全量）
PATCH  /users/123               更新用户 123（部分）
DELETE /users/123               刪除用户 123
GET    /users/123/orders        用户 123 的訂單列表
GET    /users/123/orders/456    用户 123 的訂單 456

❌ 不好的設計（動詞、不統一）：
GET  /getUser
POST /createUser
GET  /user/delete?id=123
POST /updateUserInfo

狀態碼使用

2xx 成功：
  200 OK           請求成功（GET、PUT、PATCH、DELETE）
  201 Created      創建成功（POST）
  204 No Content   成功但無返回內容（DELETE）

4xx 客户端錯誤：
  400 Bad Request        請求參數錯誤
  401 Unauthorized       未登錄（需要認證）
  403 Forbidden          已登錄但無權限
  404 Not Found          資源不存在
  409 Conflict           衝突（如用户名已存在）
  422 Unprocessable      參數驗證失敗

5xx 服務端錯誤：
  500 Internal Server Error

響應格式

// 成功響應（列表）
{
  "code": 0,
  "message": "success",
  "data": {
    "list": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

// 成功響應（單個資源）
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "張三",
    "email": "zhangsan@example.com"
  }
}

// 錯誤響應
{
  "code": 40001,
  "message": "用户名已存在",
  "data": null
}

分頁和過濾

GET /users?page=1&pageSize=20              分頁
GET /users?status=active                   過濾
GET /users?sort=createdAt&order=desc       排序
GET /users?fields=id,name,email            字段選擇
GET /users?keyword=張&status=active        組合

前端 API 封裝

// api/users.js
import request from "@/utils/request";

export const usersApi = {
  // 獲取列表
  getList(params) {
    return request.get("/users", { params });
  },
  // 獲取單個
  getById(id) {
    return request.get(`/users/${id}`);
  },
  // 創建
  create(data) {
    return request.post("/users", data);
  },
  // 更新
  update(id, data) {
    return request.patch(`/users/${id}`, data);
  },
  // 刪除
  remove(id) {
    return request.delete(`/users/${id}`);
  },
};

小結

• URI 用名詞複數，層級表示從屬，不要用動詞
• HTTP 方法表示操作：GET/POST/PUT/PATCH/DELETE
• 狀態碼語義化：4xx 客户端錯誤，5xx 服務端錯誤
• 響應統一格式：code、message、data
• 分頁、過濾用查詢參數