[ADP-117] PATCH 請求的 Content-Type
review phase 1
Refactor with ADP-115
本文件提供了在 JSON Patch (application/json-patch+json) 和 JSON Merge Patch (application/merge-patch+json) 之間選擇的指導方針。
JSON Patch (application/json-patch+json)
使用場景
- 對 JSON 文件進行複雜的多步驟操作
- 對 JSON 結構的特定部分進行精細控制
- 多樣化的操作類型(添加、刪除、替換、移動、複製、測試)
範例
json
[
{ "op": "replace", "path": "/email", "value": "newemail@example.com" },
{ "op": "add", "path": "/phone", "value": "+1234567890" }
]指導原則
- 必須在請求標頭中設置
Content-Type: application/json-patch+json - 必須驗證 patch 文件結構和操作
- 應該用於需要多個操作的複雜更新
- 必須確保 patch 操作的原子性(全部成功或全部失敗)
- 應該清楚地記錄支持的 JSON Patch 操作
JSON Merge Patch (application/merge-patch+json)
使用場景
- 對 JSON 文件進行簡單的部分更新
- 直接的欄位值替換
- 不涉及陣列或嵌套對象的低複雜度操作
範例
json
{
"email": "newemail@example.com",
"phone": "+1234567890"
}指導原則
- 必須在請求標頭中設置
Content-Type: application/merge-patch+json - 必須驗證合併 patch 文件格式
- 應該用於不需要多個操作的簡單更新
- 不應該在需要精細控制或多樣化操作時使用
- 應該清楚地記錄 Merge Patch 的使用和限制
在 JSON Patch 和 Merge Patch 之間選擇
| 方面 | JSON Patch | JSON Merge Patch |
|---|---|---|
| 複雜度 | 高 | 低 |
| 控制 | 精細 | 粗粒度 |
| 操作類型 | 多種 | 主要是替換 |
| 文件結構 | 可以修改結構 | 維持結構 |
| 使用場景 | 複雜更新 | 簡單更新 |
最佳實踐
- 在選擇 patch 格式之前分析你的 API 的更新需求
- 在你的 API 規格中清楚地記錄所選擇的 patch 格式
- 為無效的 patch 文件實作適當的錯誤處理
- 如果你的 API 有多樣化的更新場景,考慮提供兩種 patch 格式
- 確保你的 API 使用者理解每種 patch 格式的含義