1.3 KiB

Raw Blame History

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 的職責）
不做最終技術選型