RESTful API 接口設計規範提示詞（資源命名、HTTP 方法與狀態碼、分頁、錯誤格式、版本管理）
開始設計一組新接口、或者想統一團隊接口風格時用：給出業務需求，AI 按 REST 慣例設計資源和路徑，統一狀態碼、分頁、過濾、錯誤返回格式和版本策略，並審查已有接口哪裏不一致。
通用大模型 對話模型通用
你是一名 API 設計評審專家。請根據下面的需求設計接口，並輸出一份團隊可以複用的接口規範。 - 業務需求：[業務需求]（例：會員可以收藏商品、查看收藏列表、取消收藏） - 調用方：[如自家 App 和 Web、第三方合作方] - 技術約束：[技術約束]（例：網關只支持 GET 和 POST、必須兼容舊版 App） - 已有的接口（如果要審查）： [粘貼現有接口列表，沒有就寫無] 第一部分：接口設計 1. 識別資源：用名詞複數表示集合，用層級表示從屬關係，層級不超過兩層；說明哪些操作不適合硬套資源模型（如「發送驗證碼」「批量審核」），以及這類操作怎麼命名。 2. 列出每個接口：方法 | 路徑 | 用途 | 請求參數 | 成功狀態碼 | 返回示例。 3. 方法語義：GET 不能有副作用；PUT 整體替換、PATCH 部分更新；哪些接口需要支持冪等（說明冪等鍵的傳遞方式）。 第二部分：統一規範（寫成可以放進團隊文檔的條目） - 命名：路徑用小寫加連字符還是下劃線、字段用駝峰還是下劃線，選一種並保持一致； - 狀態碼：200、201、204、400、401、403、404、409、422、429、500 各自的使用場景； - 錯誤返回格式：統一結構，包含機器可讀的錯誤碼、給人看的提示、出錯字段、請求 ID； - 分頁：說明偏移分頁和游標分頁各自適用的情況，統一參數名和返回結構； - 過濾、排序與字段選擇的參數寫法； - 時間格式（帶時區的 ISO 8601）、金額表示方式（整數分或字符串小數，不用浮點數）； - 版本策略：放在路徑還是請求頭，什麼樣的改動算破壞性變更。 第三部分：如果提供了已有接口，逐條指出與規範不一致的地方並給出修改建議，同時說明修改對現有調用方的影響。 約束條件與 REST 慣例衝突時（比如網關只支持 POST），以約束為準，給出折中方案。
高亮處換成你自己的內容：[業務需求]、[如自家 App 和 Web、第三方合作方]、[技術約束]、[粘貼現有接口列表，沒有就寫無]
ChatGPT Plus 充值
已被複製 0 次
使用說明
怎麼填變量：[調用方] 是第三方合作方時，規範要更嚴格，版本策略和錯誤碼要提前定好，因為對外接口改起來成本極高。[技術約束] 一定要寫，很多公司的網關、防火牆或老客戶端只支持部分 HTTP 方法。
常見坑：
- 所有接口都返回 HTTP 200，再在返回體裏放一個 code 表示成敗。這樣監控和網關無法通過狀態碼識別錯誤。至少要讓 4xx、5xx 反映真實情況。
- 金額用浮點數傳，0.1 + 0.2 的精度問題會出現在對帳裏。用整數分或字符串。
- 偏移分頁在數據量大或數據頻繁新增時，會出現翻頁重複或遺漏，資訊流類列表適合用游標分頁。
追問技巧：設計完成後，追問「根據這份設計生成 OpenAPI 3 描述文件」，可以直接導入接口文檔工具和 Mock 服務。和 414 號提示詞（從代碼生成接口文檔）配合使用效果更好。
示例輸出
示例，僅供參考（節選）
| 方法 | 路徑 | 用途 | 成功狀態碼 |
|---|---|---|---|
| GET | /v1/favorites?cursor=xxx&limit=20 | 我的收藏列表 | 200 |
| PUT | /v1/favorites/{productId} | 收藏商品（重複收藏不報錯，冪等） | 204 |
| DELETE | /v1/favorites/{productId} | 取消收藏 | 204 |
統一錯誤格式：
json
{
"error": {
"code": "PRODUCT_NOT_FOUND",
"message": "商品不存在或已下架",
"field": "productId",
"requestId": "req_7f3a9c2e"
}
}說明：收藏用 PUT 而不是 POST，因為「收藏某個商品」的結果與執行次數無關，天然冪等。
同款作品
用這條提示詞做出來的作品；原作者會因此獲得積分
還沒有同款，來做第一個。
0 條評論
還沒有評論，來搶沙發～