1. 資源與資源建模：把業(yè)務(wù)名詞變成 URL ???

資源可以是“訂單”“發(fā)票”，甚至“一次換地址的意圖”。先拿「開發(fā)任務(wù)管理系統(tǒng)KPI」給需求量化：

• 核心資源數(shù) ≤ 20 個(gè)
• 95% 消費(fèi)者請求能在 1 次往返完成

再按下面步驟建模：

1. 抓名詞：用事件風(fēng)暴把領(lǐng)域名詞貼滿墻 ??
2. 定單例 or 集合：/profile 單例、/users 集合、/users/{id}/orders 子集合
3. 分配 HTTP 謂詞：GET 查、POST 建、PUT 全量替換、PATCH 局部更新、POST 自定義動(dòng)作

2. 細(xì)粒度 vs 粗粒度：找到“剛剛好”的甜蜜點(diǎn) ??

實(shí)戰(zhàn)技巧

• 用「代碼生成」快速拋出兩套原型，讓前端團(tuán)隊(duì)盲測調(diào)用次數(shù) ??
• 把最熱門聚合接口喂給「代碼優(yōu)化」，一鍵把 N+1 查詢變成單次 JOIN ??

3. 把業(yè)務(wù)流程藏起來：別讓消費(fèi)者背鍋 ??

業(yè)務(wù)邏輯泄漏典型癥狀：

• 客戶端先 POST /orders，再 POST /payments，再 PATCH /inventory——一旦順序錯(cuò)就數(shù)據(jù)不一致 ?

解藥：用“意圖”資源收編流程

POST /addressChangeRequests
{
  "customerId": "C-123",
  "newAddress": { "street": "長安街 1 號(hào)" }
}

服務(wù)器端異步處理、發(fā)事件、更新讀模型，消費(fèi)者只 polling /addressChangeRequests/{id} 即可 ?

設(shè)計(jì)完后，把 JSON 樣例拖進(jìn)「代碼文檔生成器」，3 秒生成帶示例的 OpenAPI 片段，前端同事直呼舒服 ??

4. 名詞 or 動(dòng)詞？讓領(lǐng)域告訴你 ???

把“注冊流程”建模為 /customerEnrollments 資源，能天然支持 KYC 狀態(tài)輪詢：

GET /customerEnrollments/E-456
→ { "status": "pendingKyc", "kycUrl": "https://kyc.example.com" }

上線前，讓「代碼審查助手」再掃一遍：

• 是否泄露了內(nèi)部狀態(tài)字段？
• 是否返回了 201 卻沒帶 Location？
• 是否把敏感日志打印到控制臺(tái)？

5. 具體化抽象概念：Transaction 模式 ??

現(xiàn)金存款涉及驗(yàn)證、記賬、短信通知等多步，直接 PATCH /accounts/{id}/balance 顯然不合理。
建模為資源：

POST /transactions
{
  "type": "cashDeposit",
  "accountId": "A-789",
  "amount": 1000.00
}

返回 201 Created + Location: /transactions/T-987，后續(xù)步驟全部封裝在服務(wù)端，消費(fèi)者只需輪詢即可 ??

6. 速查清單：設(shè)計(jì)完對(duì)照打鉤 ?

1. 資源名是名詞復(fù)數(shù) ≠ 動(dòng)詞 ?
2. 一次請求≤2 次往返（弱網(wǎng)場景）??
3. 業(yè)務(wù)狀態(tài)機(jī)藏在服務(wù)端，客戶端只關(guān)心“意圖”資源 ??
4. 用「代碼優(yōu)化」把慢查詢降到 200 ms 內(nèi) ?
5. 用「代碼文檔生成器」保持 Swagger 實(shí)時(shí)更新 ??

7. 結(jié)語 ??

好的 REST API 像“順滑的樂高”——顆粒度剛剛好、拼裝不割手、說明書隨時(shí)更新。先把「開發(fā)任務(wù)管理系統(tǒng)KPI」定好，再用 4 款代碼級(jí)提示詞一路護(hù)航，你就能交付既“好用”又“好養(yǎng)”的 API！??

原文鏈接: https://mayvenstudios.com/blog/designing-effective-rest-apis-guide-software-developers