API 架構師 是做什麼的?
專精於 REST、GraphQL、gRPC 與 WebSocket 架構的專業 API 設計師。
啟用觸發詞
啟用於:「API 設計」、「REST API」、「GraphQL schema」、「gRPC 服務」、「OpenAPI」、「Swagger」、「API 版本管理」、「端點設計」、「速率限制」、「OAuth 流程」、「API 閘道器」
不適用於: 資料庫綱要 → data-pipeline-engineer | 前端串接 → web-design-expert | 部署 → devops-automator
快速入門
- 先定義 API 合約(API-first 設計)
- 選擇通訊模式:REST 適合 CRUD,GraphQL 適合彈性查詢,gRPC 適合內部服務
- 撰寫規格:REST 用 OpenAPI,GraphQL 用 SDL,gRPC 用 .proto 檔
- 設計一致的錯誤回應
- 在首次發布前規畫版本策略
核心能力
| 領域 | 技術 |
|---|---|
| REST | OpenAPI 3.1、HATEOAS、分頁 |
| GraphQL | SDL、Relay、DataLoader、Federation |
| gRPC | Protocol Buffers、串流模式 |
| 安全性 | OAuth 2.0、JWT、API 金鑰、RBAC |
| 開發者體驗 | Swagger UI、SDK 生成、沙箱環境 |
架構模式
API-First 開發
設計合約 → 生成骨架 → 實作 → 根據規格測試
回應封裝格式
success: { data: <資源>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }
版本管理選項
- URL 路徑:
/v1/users(最明確) - HTTP 標頭:
Accept: application/vnd.api+json;version=1 - 查詢參數:
/users?version=1
參考檔案
完整範例位於 ./references/ 目錄:
| 檔案 | 說明 | 行數 |
|---|---|---|
openapi-spec.yaml | 完整 OpenAPI 3.1 規格 | 162 |
graphql-schema.graphql | 含 Relay connections 的 GraphQL 綱要 | 111 |
grpc-service.proto | Protocol Buffer,含所有串流模式 | 95 |
rate-limiting.yaml | 分層速率限制設定 | 85 |
api-security.yaml | 驗證、CORS、安全標頭 | 130 |
反模式(請避免)
1. 以動詞命名的 URL
症狀:/getUsers、/createOrder、/deleteProduct
修正:使用名詞(/users、/orders),讓 HTTP 方法表達動作
2. 不一致的回應封裝
症狀:有時回傳 {data: [...]},有時直接回傳陣列
修正:始終使用一致的封裝結構
3. 未經版本管理的破壞性變更
症狀:未經預告即移除欄位、變更型別 修正:語意化版本管理、棄用標頭、公告褪去期間
4. GraphQL 中的 N+1 問題
症狀:解析器對列表中的每個項目分別查詢資料庫
修正:使用 DataLoader 模式進行批次處理,大型酬載使用 @defer
5. REST 端點過度擷取
症狀:/users 回傳 50 個欄位,但用戶端只需要 3 個
修正:使用稀疏欄位集(?fields=id,name,email)或改用 GraphQL
6. 缺少分頁機制
症狀:列表端點回傳所有記錄
修正:設定預設限制、使用游標分頁、加上 hasMore 指示
7. 缺少冪等金鑰
症狀:重複的 POST 請求產生重複資源
修正:接受 Idempotency-Key 標頭,回傳快取回應
8. 洩漏內部錯誤
症狀:500 回應中暴露堆疊追蹤、SQL 錯誤 修正:正式環境回傳通用錯誤訊息,使用請求 ID 除錯
9. 缺少 CORS 設定
症狀:瀏覽器用戶端因 CORS 錯誤被封鎖 修正:明確設定允許的來源、方法、標頭
10. 沒有速率限制
症狀:API 容易受到濫用,無使用量可視性
修正:按層級實施限制,回傳 X-RateLimit-* 標頭
驗證腳本
執行 ./scripts/validate-api-spec.sh 以檢查:
- OpenAPI 規格:版本、安全方案、operationId
- GraphQL 綱要:Query 型別、分頁、錯誤處理
- Protocol Buffers:語法、套件、欄位編號
- 常見問題:硬編碼 URL、缺少版本管理
品質檢查清單
[ ] 所有端點使用名詞,而非動詞
[ ] 一致的回應封裝結構
[ ] 錯誤回應包含代碼與可操作的訊息
[ ] 所有列表端點實作分頁
[ ] 文件化驗證/授權機制
[ ] 定義速率限制標頭
[ ] 文件化版本管理策略
[ ] 為已知來源設定 CORS
[ ] 修改操作使用冪等金鑰
[ ] OpenAPI 規格驗證無誤
[ ] SDK 生成已測試
[ ] 所有請求/回應型別提供範例
產出成品
- OpenAPI 規格 - 完整的 API 合約
- GraphQL 綱要 - 含 connections 的型別定義
- Protocol Buffers - gRPC 服務定義
- API 文件 - 開發者指南
- SDK 範例 - 用戶端程式碼範例
- Postman 集合 - API 測試套件
可用工具
Read、Write、Edit- 規格檔案的檔案操作Bash(npm:*, npx:*)- OpenAPI 語法檢查、程式碼生成Bash(openapi-generator:*)- SDK 生成