一、簡介

REST（Representational State Transfer）已成為構建現代Web服務的標準架構風格。設計良好的REST API不僅提高了開發效率，還能提升系統的可維護性和可擴展性。本文將詳細闡述REST API設計的核心規範和最佳實踐。

二、URL設計規範

2.1 資源導向的URL設計

REST API的核心是資源（Resource）。URL應該代表資源，而不是動作。

✓ 正確：

GET /api/v1/users           # 獲取所有用户
GET /api/v1/users/123       # 獲取ID為123的用户
POST /api/v1/users          # 創建新用户
PUT /api/v1/users/123       # 更新用户123
DELETE /api/v1/users/123    # 刪除用户123

✗ 錯誤：

GET /api/getUsers
GET /api/getUserById?id=123
POST /api/createUser
POST /api/updateUser

2.2 URL命名規範

  • 使用小寫字母：URL應全部使用小寫字母
  • 使用複數形式：資源集合使用複數，如/users而非/user
  • 使用連字符分隔：多個單詞用連字符（-）連接，如/user-profiles
  • 避免文件擴展名：不在URL中添加.json或.xml
  • 版本管理：在URL中明確指定API版本，如/api/v1/或/api/v2/

2.3 子資源設計

GET /api/v1/users/123/posts              # 獲取用户123的所有文章
GET /api/v1/users/123/posts/456          # 獲取用户123的ID為456的文章
POST /api/v1/users/123/posts             # 在用户123下創建文章
DELETE /api/v1/users/123/posts/456       # 刪除用户123的文章456

三、HTTP方法規範

3.1 標準HTTP方法使用

方法

用途

冪等性

安全性

GET

獲取資源

是

是

POST

創建新資源

否

否

PUT

完全替換資源

是

否

PATCH

部分更新資源

否

否

DELETE

刪除資源

是

否

HEAD

獲取資源元數據

是

是

OPTIONS

獲取通信選項

是

是

3.2 方法使用示例

# GET：安全、冪等，無副作用
GET /api/v1/users/123

# POST：創建新資源
POST /api/v1/users
Content-Type: application/json
{
  "name": "John Doe",
  "email": "john@example.com"
}

# PUT：完全替換資源
PUT /api/v1/users/123
Content-Type: application/json
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "age": 30
}

# PATCH：部分更新
PATCH /api/v1/users/123
Content-Type: application/json
{
  "email": "newemail@example.com"
}

# DELETE：刪除資源
DELETE /api/v1/users/123

四、請求和響應規範

4.1 請求頭規範

Content-Type: application/json              # 請求數據格式
Accept: application/json                    # 期望響應格式
Authorization: Bearer <token>               # 身份驗證
X-Request-ID: uuid                          # 請求追蹤ID
User-Agent: MyClient/1.0                    # 客户端標識

4.2 查詢參數規範

# 分頁
GET /api/v1/users?page=1&per_page=20

# 排序
GET /api/v1/users?sort=-created_at,name

# 過濾
GET /api/v1/users?status=active&age[gte]=18&age[lte]=60

# 字段選擇
GET /api/v1/users?fields=id,name,email

# 搜索
GET /api/v1/users?search=john

4.3 響應數據格式

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "timestamp": "2025-01-15T10:35:00Z"
}

五、HTTP狀態碼規範

5.1 2xx 成功狀態碼

  • 200 OK：請求成功，返回數據
  • 201 Created：資源創建成功
  • 202 Accepted：請求已接收，但處理尚未完成
  • 204 No Content：請求成功，但無返回內容

5.2 3xx 重定向狀態碼

  • 301 Moved Permanently：資源永久移動
  • 302 Found：資源臨時移動
  • 304 Not Modified：資源未修改

5.3 4xx 客户端錯誤狀態碼

  • 400 Bad Request：請求參數錯誤
  • 401 Unauthorized：未授權
  • 403 Forbidden：禁止訪問
  • 404 Not Found：資源不存在
  • 409 Conflict：請求衝突（如重複數據）
  • 422 Unprocessable Entity：無法處理的實體
  • 429 Too Many Requests：請求過於頻繁

5.4 5xx 服務器錯誤狀態碼

  • 500 Internal Server Error：服務器內部錯誤
  • 502 Bad Gateway：網關錯誤
  • 503 Service Unavailable：服務不可用

六、錯誤處理規範

6.1 統一錯誤響應格式

{
  "code": 400,
  "message": "驗證失敗",
  "errors": [
    {
      "field": "email",
      "message": "郵箱格式不正確"
    },
    {
      "field": "age",
      "message": "年齡必須大於等於18"
    }
  ],
  "timestamp": "2025-01-15T10:35:00Z"
}

6.2 常見錯誤場景

# 認證失敗
HTTP/1.1 401 Unauthorized
{
  "code": 401,
  "message": "憑證過期或無效"
}

# 權限不足
HTTP/1.1 403 Forbidden
{
  "code": 403,
  "message": "您沒有權限執行此操作"
}

# 資源不存在
HTTP/1.1 404 Not Found
{
  "code": 404,
  "message": "請求的資源不存在"
}

七、安全性規範

7.1 身份驗證

  • 使用HTTPS：所有傳輸必須使用HTTPS加密
  • Token認證：優先使用Bearer Token而非Basic Auth
  • 刷新機制：實現Token刷新機制，避免長期有效的Token

7.2 授權

  • 基於角色的訪問控制（RBAC）：根據用户角色控制資源訪問
  • 基於資源的訪問控制（RBAC）：根據資源所有權控制訪問

7.3 其他安全措施

  • 速率限制：防止API濫用，使用X-RateLimit-*頭部
  • 輸入驗證：嚴格驗證所有輸入數據
  • CORS配置：合理配置跨域資源共享
  • 數據加密：敏感數據加密存儲和傳輸

八、API文檔規範

8.1 使用OpenAPI/Swagger

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /api/v1/users:
    get:
      summary: 獲取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: 成功

8.2 文檔內容

  • 清晰的操作描述
  • 請求和響應示例
  • 參數説明和類型
  • 可能的錯誤狀態碼
  • 認證要求説明

九、版本管理

9.1 版本策略

  • URL路徑版本化：/api/v1/、/api/v2/
  • 請求頭版本化：API-Version: 1
  • 查詢參數版本化：?api_version=1

9.2 向後兼容性

  • 儘量保持API的向後兼容性
  • 逐步棄用舊版本API
  • 提前通知用户升級時間表

十、性能優化建議

10.1 緩存策略

Cache-Control: max-age=300, public           # 5分鐘緩存
ETag: "33a64df551425fcc55e4d42a148795d9f900f611"
Last-Modified: Wed, 21 Oct 2025 07:28:00 GMT

10.2 分頁實現

GET /api/v1/users?page=2&per_page=10

Response:
{
  "data": [...],
  "pagination": {
    "page": 2,
    "per_page": 10,
    "total": 100,
    "total_pages": 10
  }
}

10.3 響應壓縮

  • 啓用GZIP壓縮
  • 返回字段選擇功能
  • 分頁機制減少響應體

十一、監控和日誌

11.1 請求日誌

  • 記錄所有API請求
  • 包含用户、時間、參數、響應狀態
  • 記錄異常堆棧跟蹤

11.2 性能監控

  • 監控API響應時間
  • 跟蹤錯誤率
  • 分析流量模式

十二、總結

設計良好的REST API需要遵循以下核心原則：

  1. 資源為中心：URL代表資源，HTTP方法代表操作
  2. 規範一致：命名、響應格式、錯誤處理保持一致
  3. 充分文檔：提供清晰的API文檔和示例
  4. 安全可靠：使用HTTPS、認證、授權、速率限制
  5. 易於維護：合理版本管理、向後兼容性設計
  6. 性能優先：緩存、分頁、壓縮等優化措施

通過遵循這些規範，可以構建高質量、易維護、安全可靠的REST API系統。