API 設計原則
掌握 REST 與 GraphQL API 設計原則,打造直觀、可擴展且易於維護的 API,為開發者帶來愉悅的體驗,並經得起時間考驗。
何時使用此技能
- 設計全新的 REST 或 GraphQL API
- 重構現有 API 以提升可用性
- 為團隊建立 API 設計標準
- 在實作前審查 API 規格
- 在不同 API 範式間遷移(例如從 REST 遷移至 GraphQL)
- 建立開發者友善的 API 文件
- 針對特定使用情境(如行動裝置、第三方整合)最佳化 API
核心概念
1. RESTful 設計原則
資源導向架構
- 資源應為名詞(例如 users、orders、products),而非動詞
- 使用 HTTP 方法來表示動作(GET、POST、PUT、PATCH、DELETE)
- URL 應反映資源的階層關係
- 採用一致的命名慣例
HTTP 方法語意:
GET:取得資源(冪等、安全)POST:建立新資源PUT:完整取代資源(冪等)PATCH:部分更新資源DELETE:刪除資源(冪等)
2. GraphQL 設計原則
架構優先開發
- 類型 (Types) 定義了你的領域模型
- 查詢 (Queries) 用於讀取資料
- 突變 (Mutations) 用於修改資料
- 訂閱 (Subscriptions) 用於即時更新
查詢結構:
- 客戶端精確請求所需的資料
- 單一端點,多種操作
- 強型別架構
- 內建自省 (Introspection) 機制
3. API 版本管理策略
URL 版本管理:
/api/v1/users
/api/v2/users
標頭版本管理:
Accept: application/vnd.api+json; version=1
查詢參數版本管理:
/api/users?version=1
REST API 設計模式
模式 1:資源集合設計
# 良好:資源導向端點
GET /api/users # 列出使用者(含分頁)
POST /api/users # 建立使用者
GET /api/users/{id} # 取得特定使用者
PUT /api/users/{id} # 取代使用者
PATCH /api/users/{id} # 更新使用者欄位
DELETE /api/users/{id} # 刪除使用者
# 巢狀資源
GET /api/users/{id}/orders # 取得使用者的訂單
POST /api/users/{id}/orders # 為使用者建立訂單
# 不良:以動作為導向的端點(應避免)
POST /api/createUser
POST /api/getUserById
POST /api/deleteUser
模式 2:分頁與篩選
from typing import List, Optional
from pydantic import BaseModel, Field
class PaginationParams(BaseModel):
page: int = Field(1, ge=1, description="頁碼")
page_size: int = Field(20, ge=1, le=100, description="每頁項目數")
class FilterParams(BaseModel):
status: Optional[str] = None
created_after: Optional[str] = None
search: Optional[str] = None
class PaginatedResponse(BaseModel):
items: List[dict]
total: int
page: int
page_size: int
pages: int
@property
def has_next(self) -> bool:
return self.page < self.pages
@property
def has_prev(self) -> bool:
return self.page > 1
# FastAPI 端點範例
from fastapi import FastAPI, Query, Depends
app = FastAPI()
@app.get("/api/users", response_model=PaginatedResponse)
async def list_users(
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=100),
status: Optional[str] = Query(None),
search: Optional[str] = Query(None)
):
# 套用篩選
query = build_query(status=status, search=search)
# 計算總數
total = await count_users(query)
# 取得頁面資料
offset = (page - 1) * page_size
users = await fetch_users(query, limit=page_size, offset=offset)
return PaginatedResponse(
items=users,
total=total,
page=page,
page_size=page_size,
pages=(total + page_size - 1) // page_size
)
模式 3:錯誤處理與狀態碼
from fastapi import HTTPException, status
from pydantic import BaseModel
class ErrorResponse(BaseModel):
error: str
message: str
details: Optional[dict] = None
timestamp: str
path: str
class ValidationErrorDetail(BaseModel):
field: str
message: str
value: Any
# 一致的錯誤回應
STATUS_CODES = {
"success": 200,
"created": 201,
"no_content": 204,
"bad_request": 400,
"unauthorized": 401,
"forbidden": 403,
"not_found": 404,
"conflict": 409,
"unprocessable": 422,
"internal_error": 500
}
def raise_not_found(resource: str, id: str):
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail={
"error": "NotFound",
"message": f"找不到 {resource}",
"details": {"id": id}
}
)
def raise_validation_error(errors: List[ValidationErrorDetail]):
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail={
"error": "ValidationError",
"message": "請求驗證失敗",
"details": {"errors": [e.dict() for e in errors]}
}
)
# 使用範例
@app.get("/api/users/{user_id}")
async def get_user(user_id: str):
user = await fetch_user(user_id)
if not user:
raise_not_found("使用者", user_id)
return user
模式 4:HATEOAS(超媒體作為應用程式狀態引擎)
class UserResponse(BaseModel):
id: str
name: str
email: str
_links: dict
@classmethod
def from_user(cls, user: User, base_url: str):
return cls(
id=user.id,
name=user.name,
email=user.email,
_links={
"self": {"href": f"{base_url}/api/users/{user.id}"},
"orders": {"href": f"{base_url}/api/users/{user.id}/orders"},
"update": {
"href": f"{base_url}/api/users/{user.id}",
"method": "PATCH"
},
"delete": {
"href": f"{base_url}/api/users/{user.id}",
"method": "DELETE"
}
}
)
GraphQL 設計模式
模式 1:架構設計
# schema.graphql
# 清晰的類型定義
type User {
id: ID!
email: String!
name: String!
createdAt: DateTime!
# 關聯
orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!
profile: UserProfile
}
type Order {
id: ID!
status: OrderStatus!
total: Money!
items: [OrderItem!]!
createdAt: DateTime!
# 反向關聯
user: User!
}
# 分頁模式 (Relay 風格)
type OrderConnection {
edges: [OrderEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type OrderEdge {
node: Order!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
# 列舉類型確保型別安全
enum OrderStatus {
PENDING
CONFIRMED
SHIPPED
DELIVERED
CANCELLED
}
# 自訂標量
scalar DateTime
scalar Money
# 查詢根節點
type Query {
user(id: ID!): User
users(first: Int = 20, after: String, search: String): UserConnection!
order(id: ID!): Order
}
# 突變根節點
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
updateUser(input: UpdateUserInput!): UpdateUserPayload!
deleteUser(id: ID!): DeleteUserPayload!
createOrder(input: CreateOrderInput!): CreateOrderPayload!
}
# 用於突變的輸入類型
input CreateUserInput {
email: String!
name: String!
password: String!
}
# 用於突變的回應類型
type CreateUserPayload {
user: User
errors: [Error!]
}
type Error {
field: String
message: String!
}
模式 2:解析器設計
from typing import Optional, List
from ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass
query = QueryType()
mutation = MutationType()
user_type = ObjectType("User")
@query.field("user")
async def resolve_user(obj, info, id: str) -> Optional[dict]:
"""根據 ID 解析單一使用者。"""
return await fetch_user_by_id(id)
@query.field("users")
async def resolve_users(
obj,
info,
first: int = 20,
after: Optional[str] = None,
search: Optional[str] = None
) -> dict:
"""解析分頁的使用者列表。"""
# 解碼游標
offset = decode_cursor(after) if after else 0
# 取得使用者
users = await fetch_users(
limit=first + 1, # 多取得一個以判斷是否有下一頁
offset=offset,
search=search
)
# 分頁
has_next = len(users) > first
if has_next:
users = users[:first]
edges = [
{
"node": user,
"cursor": encode_cursor(offset + i)
}
for i, user in enumerate(users)
]
return {
"edges": edges,
"pageInfo": {
"hasNextPage": has_next,
"hasPreviousPage": offset > 0,
"startCursor": edges[0]["cursor"] if edges else None,
"endCursor": edges[-1]["cursor"] if edges else None
},
"totalCount": await count_users(search=search)
}
@user_type.field("orders")
async def resolve_user_orders(user: dict, info, first: int = 20) -> dict:
"""解析使用者的訂單 (使用 DataLoader 預防 N+1 問題)。"""
# 使用 DataLoader 批次處理請求
loader = info.context["loaders"]["orders_by_user"]
orders = await loader.load(user["id"])
return paginate_orders(orders, first)
@mutation.field("createUser")
async def resolve_create_user(obj, info, input: dict) -> dict:
"""建立新使用者。"""
try:
# 驗證輸入
validate_user_input(input)
# 建立使用者
user = await create_user(
email=input["email"],
name=input["name"],
password=hash_password(input["password"])
)
return {
"user": user,
"errors": []
}
except ValidationError as e:
return {
"user": None,
"errors": [{"field": e.field, "message": e.message}]
}
模式 3:DataLoader(預防 N+1 問題)
from aiodataloader import DataLoader
from typing import List, Optional
class UserLoader(DataLoader):
"""根據 ID 批次載入使用者。"""
async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
"""在單一查詢中載入多個使用者。"""
users = await fetch_users_by_ids(user_ids)
# 將結果對應回輸入順序
user_map = {user["id"]: user for user in users}
return [user_map.get(user_id) for user_id in user_ids]
class OrdersByUserLoader(DataLoader):
"""根據使用者 ID 批次載入訂單。"""
async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
"""在單一查詢中載入多個使用者的訂單。"""
orders = await fetch_orders_by_user_ids(user_ids)
# 按 user_id 分組訂單
orders_by_user = {}
for order in orders:
user_id = order["user_id"]
if user_id not in orders_by_user:
orders_by_user[user_id] = []
orders_by_user[user_id].append(order)
# 按輸入順序回傳
return [orders_by_user.get(user_id, []) for user_id in user_ids]
# 上下文設定
def create_context():
return {
"loaders": {
"user": UserLoader(),
"orders_by_user": OrdersByUserLoader()
}
}
最佳實踐
REST API
- 一致的命名:對集合使用複數名詞(例如
/users,而非/user) - 無狀態:每個請求應包含所有必要資訊
- 正確使用 HTTP 狀態碼:2xx 成功、4xx 用戶端錯誤、5xx 伺服器錯誤
- 為 API 加上版本:從第一天起就為破壞性變更做好準備
- 分頁:大型集合務必使用分頁
- 速率限制:使用速率限制保護你的 API
- 文件:使用 OpenAPI/Swagger 提供互動式文件
GraphQL API
- 架構優先:在撰寫解析器之前先設計架構
- 避免 N+1:使用 DataLoader 實現高效的資料獲取
- 輸入驗證:在架構與解析器兩個層級進行驗證
- 錯誤處理:在突變回應中回傳結構化的錯誤資訊
- 分頁:使用基於游標的分頁(Relay 規範)
- 棄用:使用
@deprecated指令進行逐步遷移 - 監控:追蹤查詢的複雜度與執行時間
常見陷阱
- 過度擷取/不足擷取 (REST):GraphQL 解決了此問題,但仍需 DataLoader
- 破壞性變更:為 API 加上版本或使用棄用策略
- 不一致的錯誤格式:標準化錯誤回應
- 缺少速率限制:沒有限制的 API 容易遭受濫用
- 貧乏的文件:未妥善記錄的 API 會讓開發者困擾
- 忽略 HTTP 語意:對冪等操作使用 POST 會破壞預期行為
- 高度耦合:API 結構不應直接鏡像資料庫結構
資源
- references/rest-best-practices.md:全面的 REST API 設計指南
- references/graphql-schema-design.md:GraphQL 架構模式與反模式
- references/api-versioning-strategies.md:版本管理策略與遷移路徑
- assets/rest-api-template.py:FastAPI REST API 模板
- assets/graphql-schema-template.graphql:完整的 GraphQL 架構範例
- assets/api-design-checklist.md:實作前審查清單
- scripts/openapi-generator.py:從程式碼產生 OpenAPI 規格