API 介面設計：先定契約再寫碼
要新增一組接口，想先把設計定清楚再動手。
提示詞長度
191
tokens
建議模型
V4 Pro
單次成本（離峰）
$0.00021
Flash
跑一萬次
$2.09
Flash 離峰
提示詞全文
設計一組 API 介面。
需求：{{這個 API 要解決什麼}}
使用方：{{前端 / 第三方 / 內部服務}}
資料量級：{{每天多少請求}}
輸出：
1. 資源模型（有哪些實體、彼此關係）
2. 端點清單表格：方法 | 路徑 | 用途 | 權限
3. 每個端點的請求/響應範例（JSON）
4. 錯誤碼設計（哪些情況回什麼碼，含業務錯誤）
5. 分頁、過濾、排序的統一約定
6. 三個「這個設計未來會痛的地方」
要求：
- 遵循 REST 慣例，不要自創風格
- 錯誤響應要包含可供程式判斷的 code，不要只給 message
- 說明冪等性：哪些操作重複調用安全、哪些不安全
為什麼這樣寫
- 「未來會痛的地方」是這個 prompt 最有價值的一節。API 設計的坑通常在半年後才顯現。
- 要求錯誤碼可被程式判斷，避免前端只能靠字符串匹配錯誤類型。
- 要求說明冪等性，能提前發現重試會導致重複下單這類問題。
成本
按上面這段提示詞估算（輸入 191 tokens、輸出 300 tokens）。輸出長度依任務而定，實際會有差異。
| 模型 | 單次（高峰） | 單次（離峰） | 1 萬次（高峰） | 1 萬次（離峰） |
|---|---|---|---|---|
| DeepSeek Flash | $0.00042 | $0.00021 | $4.17 | $2.09 |
| DeepSeek V4 Pro | $0.00144 | $0.00072 | $14.40 | $7.20 |
模型建議：API 設計是架構決策，錯了的修正成本遠高於 API 費用，值得用 V4 Pro。
變體
- 對外開放時，追加「設計 API Key 與速率限制方案，說明超限時回什麼」。
- 內部服務時，追加「說明哪些欄位可以樂觀返回、哪些必須強一致」。
常見失敗
- 不給量級，分頁與快取策略會設計得過重或不足。
- 不要求冪等性說明，支付類接口容易埋雷。