26 lines
1.3 KiB
Markdown
26 lines
1.3 KiB
Markdown
|
# API 合約設計 (API Contract Design) 知識合約指南
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
`api-contract-design` 是知識合約，不是 workflow 技能。用來定義 API 合約的設計原則，包含請求/回應結構、狀態碼、分頁機制、認證邊界與冪等性行為。供 `design-architecture` 在定義 API 時參考。
|
|||
|
|
|
|||
|
|
## 核心原則
|
|||
|
|
- API 是生產者與消費者之間的合約，穩定性與清晰度至關重要
|
|||
|
|
- 每個端點必須服務至少一個 PRD 功能需求
|
|||
|
|
- 合約必須明確、完整且無歧義
|
|||
|
|
- 破壞性變更必須避免；必須規劃版本管理
|
|||
|
|
|
|||
|
|
## 設計重點
|
|||
|
|
- REST API：端點定義、請求結構、回應結構、狀態碼、分頁、過濾
|
|||
|
|
- 非 REST API：GraphQL schema、gRPC service 定義、WebSocket 訊息格式
|
|||
|
|
- 錯誤回應格式：一致的錯誤碼、機器可讀與人類可讀的訊息
|
|||
|
|
- 版本策略：URL path versioning 與 header versioning 的適用場景
|
|||
|
|
|
|||
|
|
## 知識合約職責
|
|||
|
|
- 提供 API 設計的理論指引
|
|||
|
|
- 不直接產生 API 規格（由 `generate_openapi_spec` 負責格式）
|
|||
|
|
- 與 `generate_openapi_spec` 搭配使用：前者提供原則，後者提供格式
|
|||
|
|
|
|||
|
|
## 不應做的事
|
|||
|
|
- 不產生 API 規格檔案
|
|||
|
|
- 不替特定端點命名或定義結構（那是 `design-architecture` 的職責）
|
|||
|
|
- 不做最終技術選型
|