524 lines
13 KiB
Markdown
524 lines
13 KiB
Markdown
---
|
||
name: api-design
|
||
description: REST API 設計模式，包含資源命名、狀態碼、分頁、篩選、錯誤回應、版本控制以及生產環境 API 的速率限制。
|
||
origin: ECC
|
||
---
|
||
|
||
# API 設計模式 (API Design Patterns)
|
||
|
||
設計一致且對開發者友好的 REST API 的慣例與最佳實踐。
|
||
|
||
## 何時啟用
|
||
|
||
- 設計新的 API 端點 (Endpoints)
|
||
- 評估現有的 API 合約
|
||
- 新增分頁、篩選或排序功能
|
||
- 為 API 實作錯誤處理
|
||
- 規劃 API 版本控制策略
|
||
- 構建面向公眾或合作夥伴的 API
|
||
|
||
## 資源設計 (Resource Design)
|
||
|
||
### URL 結構
|
||
|
||
```
|
||
# 資源應使用名詞、複數、小寫、kebab-case
|
||
GET /api/v1/users
|
||
GET /api/v1/users/:id
|
||
POST /api/v1/users
|
||
PUT /api/v1/users/:id
|
||
PATCH /api/v1/users/:id
|
||
DELETE /api/v1/users/:id
|
||
|
||
# 用於關聯的子資源
|
||
GET /api/v1/users/:id/orders
|
||
POST /api/v1/users/:id/orders
|
||
|
||
# 無法對應到 CRUD 的動作 (謹慎使用動詞)
|
||
POST /api/v1/orders/:id/cancel
|
||
POST /api/v1/auth/login
|
||
POST /api/v1/auth/refresh
|
||
```
|
||
|
||
### 命名規則
|
||
|
||
```
|
||
# 推薦 (GOOD)
|
||
/api/v1/team-members # 多單字資源使用 kebab-case
|
||
/api/v1/orders?status=active # 使用查詢參數進行篩選
|
||
/api/v1/users/123/orders # 使用巢狀資源表示歸屬關係
|
||
|
||
# 不推薦 (BAD)
|
||
/api/v1/getUsers # URL 中包含動詞
|
||
/api/v1/user # 使用單數 (應使用複數)
|
||
/api/v1/team_members # URL 中使用 snake_case
|
||
/api/v1/users/123/getOrders # 巢狀資源中包含動詞
|
||
```
|
||
|
||
## HTTP 方法與狀態碼
|
||
|
||
### 方法語意 (Method Semantics)
|
||
|
||
| 方法 | 冪等性 (Idempotent) | 安全性 (Safe) | 用途 |
|
||
|--------|-----------|------|---------|
|
||
| GET | 是 | 是 | 檢索資源 |
|
||
| POST | 否 | 否 | 建立資源、觸發動作 |
|
||
| PUT | 是 | 否 | 完整替換資源 |
|
||
| PATCH | 否* | 否 | 部分更新資源 |
|
||
| DELETE | 是 | 否 | 移除資源 |
|
||
|
||
*PATCH 若有正確實作也可以具備冪等性。
|
||
|
||
### 狀態碼參考
|
||
|
||
```
|
||
# 成功 (Success)
|
||
200 OK — GET, PUT, PATCH (含回應主體)
|
||
201 Created — POST (應包含 Location 標頭)
|
||
204 No Content — DELETE, PUT (無回應主體)
|
||
|
||
# 客戶端錯誤 (Client Errors)
|
||
400 Bad Request — 驗證失敗、JSON 格式錯誤
|
||
401 Unauthorized — 缺失或無效的身分驗證
|
||
403 Forbidden — 已驗證但無權限
|
||
404 Not Found — 資源不存在
|
||
409 Conflict — 重複輸入、狀態衝突
|
||
422 Unprocessable Entity — 語法正確但語意無效 (JSON 合法，數據有誤)
|
||
429 Too Many Requests — 超過速率限制
|
||
|
||
# 伺服器錯誤 (Server Errors)
|
||
500 Internal Server Error — 非預期失敗 (絕對不要暴露詳細細節)
|
||
502 Bad Gateway — 上游服務失敗
|
||
503 Service Unavailable — 暫時性超載，應包含 Retry-After
|
||
```
|
||
|
||
### 常見錯誤
|
||
|
||
```
|
||
# 錯誤範例 (BAD)：不論什麼情況都回傳 200
|
||
{ "status": 200, "success": false, "error": "Not found" }
|
||
|
||
# 正確案例 (GOOD)：語意化地使用 HTTP 狀態碼
|
||
HTTP/1.1 404 Not Found
|
||
{ "error": { "code": "not_found", "message": "User not found" } }
|
||
|
||
# 錯誤範例 (BAD)：針對驗證錯誤回傳 500
|
||
# 正確案例 (GOOD)：回傳 400 或 422 並提供欄位級別的詳細資訊
|
||
|
||
# 錯誤範例 (BAD)：針對建立的資源回傳 200
|
||
# 正確案例 (GOOD)：回傳 201 並附帶 Location 標頭
|
||
HTTP/1.1 201 Created
|
||
Location: /api/v1/users/abc-123
|
||
```
|
||
|
||
## 回應格式 (Response Format)
|
||
|
||
### 成功回應
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "abc-123",
|
||
"email": "alice@example.com",
|
||
"name": "Alice",
|
||
"created_at": "2025-01-15T10:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 集合回應 (包含分頁)
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{ "id": "abc-123", "name": "Alice" },
|
||
{ "id": "def-456", "name": "Bob" }
|
||
],
|
||
"meta": {
|
||
"total": 142,
|
||
"page": 1,
|
||
"per_page": 20,
|
||
"total_pages": 8
|
||
},
|
||
"links": {
|
||
"self": "/api/v1/users?page=1&per_page=20",
|
||
"next": "/api/v1/users?page=2&per_page=20",
|
||
"last": "/api/v1/users?page=8&per_page=20"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 錯誤回應
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "validation_error",
|
||
"message": "Request validation failed",
|
||
"details": [
|
||
{
|
||
"field": "email",
|
||
"message": "Must be a valid email address",
|
||
"code": "invalid_format"
|
||
},
|
||
{
|
||
"field": "age",
|
||
"message": "Must be between 0 and 150",
|
||
"code": "out_of_range"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 回應外殼 (Envelope) 變體
|
||
|
||
```typescript
|
||
// 選項 A：帶有數據包裝的外殼 (建議用於公眾 API)
|
||
interface ApiResponse<T> {
|
||
data: T;
|
||
meta?: PaginationMeta;
|
||
links?: PaginationLinks;
|
||
}
|
||
|
||
interface ApiError {
|
||
error: {
|
||
code: string;
|
||
message: string;
|
||
details?: FieldError[];
|
||
};
|
||
}
|
||
|
||
// 選項 B：扁平化回應 (較簡單，常見於內部 API)
|
||
// 成功：直接回傳資源
|
||
// 錯誤：回傳錯誤物件
|
||
// 透過 HTTP 狀態碼進行區分
|
||
```
|
||
|
||
## 分頁 (Pagination)
|
||
|
||
### 基於偏移量 (Offset-Based，簡單)
|
||
|
||
```
|
||
GET /api/v1/users?page=2&per_page=20
|
||
|
||
# 實作概念
|
||
SELECT * FROM users
|
||
ORDER BY created_at DESC
|
||
LIMIT 20 OFFSET 20;
|
||
```
|
||
|
||
**點：** 易於實作，支援「跳轉到第 N 頁」。
|
||
**缺點：** 對於大型偏移量 (OFFSET 100000) 效能較慢，且在併發插入時會出現不一致的情況。
|
||
|
||
### 基於游標 (Cursor-Based，具擴展性)
|
||
|
||
```
|
||
GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
|
||
|
||
# 實作概念
|
||
SELECT * FROM users
|
||
WHERE id > :cursor_id
|
||
ORDER BY id ASC
|
||
LIMIT 21; -- 多抓一個以判斷是否有下一頁 (has_next)
|
||
```
|
||
|
||
```json
|
||
{
|
||
"data": [...],
|
||
"meta": {
|
||
"has_next": true,
|
||
"next_cursor": "eyJpZCI6MTQzfQ"
|
||
}
|
||
}
|
||
```
|
||
|
||
**優點：** 不論位置如何效能皆保持一致，且在併發插入時表現穩定。
|
||
**缺點：** 無法跳轉到任意頁碼，且游標內容不具備可讀性。
|
||
|
||
### 該選用哪一種？
|
||
|
||
| 使用情境 | 分頁類型 |
|
||
|----------|----------------|
|
||
| 管理後台、小型資料集 (<10K) | 偏移量 (Offset) |
|
||
| 無限滾動、動態牆、大型資料集 | 游標 (Cursor) |
|
||
| 公眾 API | 預設游標 (可選配偏移量) |
|
||
| 搜尋結果 | 偏移量 (使用者預期看到頁碼) |
|
||
|
||
## 篩選、排序與搜尋
|
||
|
||
### 篩選 (Filtering)
|
||
|
||
```
|
||
# 簡單等值
|
||
GET /api/v1/orders?status=active&customer_id=abc-123
|
||
|
||
# 比較運算子 (使用括號表示)
|
||
GET /api/v1/products?price[gte]=10&price[lte]=100
|
||
GET /api/v1/orders?created_at[after]=2025-01-01
|
||
|
||
# 多重數值 (逗號分隔)
|
||
GET /api/v1/products?category=electronics,clothing
|
||
|
||
# 巢狀欄位 (點表示法)
|
||
GET /api/v1/orders?customer.country=US
|
||
```
|
||
|
||
### 排序 (Sorting)
|
||
|
||
```
|
||
# 單一欄位 (前綴 - 表示降冪)
|
||
GET /api/v1/products?sort=-created_at
|
||
|
||
# 多個欄位 (逗號分隔)
|
||
GET /api/v1/products?sort=-featured,price,-created_at
|
||
```
|
||
|
||
### 全文檢索 (Full-Text Search)
|
||
|
||
```
|
||
# 搜尋查詢參數
|
||
GET /api/v1/products?q=wireless+headphones
|
||
|
||
# 特定欄位搜尋
|
||
GET /api/v1/users?email=alice
|
||
```
|
||
|
||
### 稀疏欄位集 (Sparse Fieldsets)
|
||
|
||
```
|
||
# 僅返回指定欄位 (減少回應體體積)
|
||
GET /api/v1/users?fields=id,name,email
|
||
GET /api/v1/orders?fields=id,total,status&include=customer.name
|
||
```
|
||
|
||
## 身分驗證與授權
|
||
|
||
### 基於 Token 的驗證
|
||
|
||
```
|
||
# Authorization 標頭中的 Bearer token
|
||
GET /api/v1/users
|
||
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
|
||
|
||
# API key (用於伺服器對伺服器通訊)
|
||
GET /api/v1/data
|
||
X-API-Key: sk_live_abc123
|
||
```
|
||
|
||
### 授權模式 (Authorization Patterns)
|
||
|
||
```typescript
|
||
// 資源級別：檢查所有權
|
||
app.get("/api/v1/orders/:id", async (req, res) => {
|
||
const order = await Order.findById(req.params.id);
|
||
if (!order) return res.status(404).json({ error: { code: "not_found" } });
|
||
if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } });
|
||
return res.json({ data: order });
|
||
});
|
||
|
||
// 基於角色：檢查權限
|
||
app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => {
|
||
await User.delete(req.params.id);
|
||
return res.status(204).send();
|
||
});
|
||
```
|
||
|
||
## 速率限制 (Rate Limiting)
|
||
|
||
### 標頭 (Headers)
|
||
|
||
```
|
||
HTTP/1.1 200 OK
|
||
X-RateLimit-Limit: 100
|
||
X-RateLimit-Remaining: 95
|
||
X-RateLimit-Reset: 1640000000
|
||
|
||
# 超過限制時
|
||
HTTP/1.1 429 Too Many Requests
|
||
Retry-After: 60
|
||
{
|
||
"error": {
|
||
"code": "rate_limit_exceeded",
|
||
"message": "Rate limit exceeded. Try again in 60 seconds."
|
||
}
|
||
}
|
||
```
|
||
|
||
### 速率限制分層
|
||
|
||
| 層級 | 限制 | 視窗 | 使用情境 |
|
||
|------|-------|--------|----------|
|
||
| 匿名 | 30/min | 每 IP | 公眾端點 |
|
||
| 已驗證 | 100/min | 每使用者 | 標準 API 存取 |
|
||
| 高級 (Premium) | 1000/min | 每 API key | 付費 API 方案 |
|
||
| 內部 | 10000/min | 每服務 | 服務間通訊 |
|
||
|
||
## 版本控制 (Versioning)
|
||
|
||
### URL 路徑版本控制 (建議方案)
|
||
|
||
```
|
||
/api/v1/users
|
||
/api/v2/users
|
||
```
|
||
|
||
**優點：** 明確、易於路由、可緩存。
|
||
**缺點：** 不同版本間 URL 會更動。
|
||
|
||
### 標頭版本控制 (Header Versioning)
|
||
|
||
```
|
||
GET /api/users
|
||
Accept: application/vnd.myapp.v2+json
|
||
```
|
||
|
||
**優點：** URL 保持乾淨。
|
||
**缺點：** 較難測試、容易遺忘。
|
||
|
||
### 版本控制策略
|
||
|
||
```
|
||
1. 以 /api/v1/ 開始 — 在有需求之前不要進行版本控制。
|
||
2. 最多維持 2 個活動版本 (當前版 + 前一版)。
|
||
3. 棄用 (Deprecation) 時間表：
|
||
- 宣佈棄用 (公眾 API 提前 6 個月通知)。
|
||
- 加入 Sunset 標頭：Sunset: Sat, 01 Jan 2026 00:00:00 GMT。
|
||
- 棄用日期後，回傳 410 Gone。
|
||
4. 非破壞性變更不需要新版本：
|
||
- 在回應中新增欄位。
|
||
- 新增可選的查詢參數。
|
||
- 新增端點。
|
||
5. 破壞性變更需要新版本：
|
||
- 移除或重新命名欄位。
|
||
- 更改欄位型別。
|
||
- 更改 URL 結構。
|
||
- 更改身分驗證方法。
|
||
```
|
||
|
||
## 實作模式
|
||
|
||
### TypeScript (Next.js API Route)
|
||
|
||
```typescript
|
||
import { z } from "zod";
|
||
import { NextRequest, NextResponse } from "next/server";
|
||
|
||
const createUserSchema = z.object({
|
||
email: z.string().email(),
|
||
name: z.string().min(1).max(100),
|
||
});
|
||
|
||
export async function POST(req: NextRequest) {
|
||
const body = await req.json();
|
||
const parsed = createUserSchema.safeParse(body);
|
||
|
||
if (!parsed.success) {
|
||
return NextResponse.json({
|
||
error: {
|
||
code: "validation_error",
|
||
message: "Request validation failed",
|
||
details: parsed.error.issues.map(i => ({
|
||
field: i.path.join("."),
|
||
message: i.message,
|
||
code: i.code,
|
||
})),
|
||
},
|
||
}, { status: 422 });
|
||
}
|
||
|
||
const user = await createUser(parsed.data);
|
||
|
||
return NextResponse.json(
|
||
{ data: user },
|
||
{
|
||
status: 201,
|
||
headers: { Location: `/api/v1/users/${user.id}` },
|
||
},
|
||
);
|
||
}
|
||
```
|
||
|
||
### Python (Django REST Framework)
|
||
|
||
```python
|
||
from rest_framework import serializers, viewsets, status
|
||
from rest_framework.response import Response
|
||
|
||
class CreateUserSerializer(serializers.Serializer):
|
||
email = serializers.EmailField()
|
||
name = serializers.CharField(max_length=100)
|
||
|
||
class UserSerializer(serializers.ModelSerializer):
|
||
class Meta:
|
||
model = User
|
||
fields = ["id", "email", "name", "created_at"]
|
||
|
||
class UserViewSet(viewsets.ModelViewSet):
|
||
serializer_class = UserSerializer
|
||
permission_classes = [IsAuthenticated]
|
||
|
||
def get_serializer_class(self):
|
||
if self.action == "create":
|
||
return CreateUserSerializer
|
||
return UserSerializer
|
||
|
||
def create(self, request):
|
||
serializer = CreateUserSerializer(data=request.data)
|
||
serializer.is_valid(raise_exception=True)
|
||
user = UserService.create(**serializer.validated_data)
|
||
return Response(
|
||
{"data": UserSerializer(user).data},
|
||
status=status.HTTP_201_CREATED,
|
||
headers={"Location": f"/api/v1/users/{user.id}"},
|
||
)
|
||
```
|
||
|
||
### Go (net/http)
|
||
|
||
```go
|
||
func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
|
||
var req CreateUserRequest
|
||
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
|
||
writeError(w, http.StatusBadRequest, "invalid_json", "Invalid request body")
|
||
return
|
||
}
|
||
|
||
if err := req.Validate(); err != nil {
|
||
writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error())
|
||
return
|
||
}
|
||
|
||
user, err := h.service.Create(r.Context(), req)
|
||
if err != nil {
|
||
switch {
|
||
case errors.Is(err, domain.ErrEmailTaken):
|
||
writeError(w, http.StatusConflict, "email_taken", "Email already registered")
|
||
default:
|
||
writeError(w, http.StatusInternalServerError, "internal_error", "Internal error")
|
||
}
|
||
return
|
||
}
|
||
|
||
w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID))
|
||
writeJSON(w, http.StatusCreated, map[string]any{"data": user})
|
||
}
|
||
```
|
||
|
||
## API 設計檢核清單
|
||
|
||
在交付新端點之前：
|
||
|
||
- [ ] 資源 URL 遵循命名規範 (複數、kebab-case、不含動詞)
|
||
- [ ] 使用正確的 HTTP 方法 (GET 用於讀取，POST 用於建立等)
|
||
- [ ] 回傳適當的狀態碼 (不論什麼情況都回傳 200 是錯誤的)
|
||
- [ ] 輸入經過 Schema 驗證 (Zod, Pydantic, Bean Validation)
|
||
- [ ] 錯誤回應遵循標準格式，包含代碼與訊息
|
||
- [ ] 對於清單端點已實作分頁 (游標或偏移量)
|
||
- [ ] 要求身分驗證 (或明確標註為公眾存取)
|
||
- [ ] 已檢查授權 (使用者僅能存取自己的資源)
|
||
- [ ] 已配置速率限制
|
||
- [ ] 回應中不會洩漏內部細節 (堆疊追蹤、SQL 錯誤等)
|
||
- [ ] 與現有端點的命名方式保持一致 (camelCase vs snake_case)
|
||
- [ ] 已撰寫文件 (OpenAPI/Swagger 規範已更新)
|