前言
JSON-RPC是一種簡單、輕量且無狀態的遠程過程調用（RPC）協議，它允許不同系統通過標準化的數據格式進行通信。自2010年由JSON-RPC工作組發布以來，已成為眾多應用中實現遠程交互的基礎協議之一。本規范主要表達了JSON-RPC 2.0版本的核心內容和處理規則，以保證各實現之間的兼容性和基礎一致性。
本文由翻譯者整理并編輯，旨在幫助中文讀者理解和掌握JSON-RPC 2.0的技術細節與使用規范。
一、概述
JSON-RPC是建立在JSON（JavaScript Object Notation）之上的一種協議（符合RFC 4627），它定義了一套數據結構和交互規則，支持多種傳輸協議（如HTTP、WebSocket、TCP socket等）。其特點如下：
- 無狀態（Stateless）：每個請求都獨立，無依賴歷史狀態。
- 輕量級（Lightweight）：沒有繁瑣的通信機制，只有必要的數據結構。
- 跨平臺：可以運行在任意支持JSON的環境中。
- 多角色支持：既可以是客戶端，也可以是服務端，也可以在同一應用內部既充當請求者又承擔服務角色。
二、約定與用語
本規范中涉及的關鍵詞在RFC 2119中定義，表示其強制性或推薦性。例如：
- MUST：必須
- SHALL：強制要求
- SHOULD：建議
- MAY：可選
JSON類型
- Primitive（基本類型）：String、Number、Boolean、Null
- Structured（結構化類型）：Object（對象）、Array（數組）
在文檔中，標記為“Object”、“Array”、“String”、“Number”、“Boolean”、“Null”的類型名，首字母必須大寫。
名稱區分大小寫
所有成員名（字段名）必須區分大小寫。
角色定義
- 客戶端（Client）：請求發起方，發起請求，并處理響應。
- 服務端（Server）：請求應答方，接受請求并發出響應。
三、版本兼容性
JSON-RPC 2.0定義了請求和響應的結構，若要與舊版本（1.0）兼容：
- 2.0請求對象必須包含
"jsonrpc": "2.0"字段。 - 1.0版本不包含該字段。
- 實現應嘗試處理1.0格式請求，但優先處理2.0格式。
四、請求對象（Request Object）
客戶端發起遠程調用時，使用請求對象進行描述。請求對象具有以下成員：
| 成員名 | 類型 | 說明 | 是否必須 |
|---|---|---|---|
jsonrpc | String | 協議版本，必須為字符串"2.0" | 必須 |
method | String | 方法名，代表要調用的遠程方法名（內部方法用開頭“rpc.”做前綴） | 必須 |
params | Array或Object（可選） | 調用參數，可以是數組（索引參數）或對象（命名參數） | 可選 |
id | String、Number或Null | 客戶端唯一標識符，用于匹配請求與響應，通知請求沒有此字段或用Null | 可選（通知沒有） |
請求通知（Notification）
如果請求對象沒有"id"字段，則為通知。通知代表客戶端不需要響應結果，服務端無須返回響應。
示例
// 正常請求 { "jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1 }
// 通知 { "jsonrpc": "2.0", "method": "update", "params": [1, 2, 3] }
五、響應對象（Response Object）
服務端對請求的回應，以響應對象形式出現。響應對象有以下成員：
| 成員名 | 類型 | 說明 | 是否必須 |
|---|---|---|---|
jsonrpc | String | 協議版本，必須為字符串"2.0" | 必須 |
result | 任意類型（成功時存在） | 調用成功后的返回值 | 可選 |
error | Error對象（失敗時存在） | 出現錯誤時的錯誤信息，不能與result同時出現 | 可選 |
id | String、Number或Null | 請求中的id，用于匹配請求（通知沒有此字段或用Null） | 必須 |
成功響應
{ "jsonrpc": "2.0", "result": 19, "id": 1 }
失敗響應（錯誤對象）
{ "jsonrpc": "2.0", "error": { "code": -32601, "message": "Method not found" }, "id": 1 }
ID對應關系說明
- 若請求中
id是字符串或數字，響應中應保持一致，確保客戶端可以正確匹配。 - 通知請求不應有響應。
六、錯誤對象（Error Object）
錯誤信息定義如下：
| 成員名 | 類型 | 說明 | 是否必須 |
|---|---|---|---|
code | Integer | 錯誤類型代碼，用于區分錯誤類別 | 必須 |
message | String | 簡要描述錯誤信息 | 必須 |
data | 任意類型 | 可選，附加錯誤信息（嵌套結構、詳細信息等） | 可選 |
預定義錯誤碼
| 碼值 | 描述 | 說明 |
|---|---|---|
| -32700 | Parse error（解析錯誤） | JSON格式不正確，解析失敗 |
| -32600 | Invalid Request（無效請求） | 請求結構無效或格式錯誤 |
| -32601 | Method not found（方法不存在） | 調用的方法未定義 |
| -32602 | Invalid params（參數無效） | 參數不符合預期 |
| -32603 | Internal error（內部錯誤） | 服務器內部錯誤 |
| -32000至-32099 | Server error（服務器錯誤） | 預留用于定義自定義錯誤碼 |
七、批量請求（Batch）
批量請求允許一次發起多個請求或通知，服務端將會逐個處理，并返回包含所有響應的數組。
特點
- 請求體為數組，每個元素都是請求或通知對象。
- 只要有一個請求無效，返回的響應數組中會對應錯誤。
- 通知（無id請求）沒有響應。
- 可以混合請求和通知。
舉例
[ { "jsonrpc": "2.0", "method": "sum", "params": [1, 2, 3], "id": "1" }, { "jsonrpc": "2.0", "method": "notify_hello", "params": [7] }, { "jsonrpc": "2.0", "method": "subtract", "params": [10, 5], "id": "2" } ]
對應的響應：
[ { "jsonrpc": "2.0", "result": 6, "id": "1" }, // 通知無響應 { "jsonrpc": "2.0", "result": 5, "id": "2" } ]
特別留意：
- 若請求數組為空或無效，服務端應返回錯誤響應（非數組）。
- 批量中所有通知都沒有響應（集合為空），也不返回任何內容。
八、示例：常用調用場景
- 正常調用：
{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
- 通知調用：
{"jsonrpc": "2.0", "method": "update", "params": [1, 2, 3]}
- 錯誤示例：
請求中包含無效JSON或缺失必要字段，解析失敗：
{"jsonrpc": "2.0", "method": "unknown_method", "params": {}, "id": 10}
服務端響應：
{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": 10}
九、擴展機制
以rpc開頭的方法名保留給系統擴展，不應在正常業務調用中使用。所有擴展都應有對應的文檔說明，且實現為可選。
十、版權聲明
本協議由JSON-RPC工作組首次發布，任何人可自由使用、復用、修改，須包含版權聲明并遵守共享協議。
結語
JSON-RPC 2.0以其簡潔、靈活的設計理念，為各種應用提供了標準的遠程調用解決方案。理解并正確使用該協議，可以極大豐富你的系統交互能力，提升開發效率。
附錄：常用誤區和注意事項
- 不要在通知中使用
id字段，否則會被誤認為是請求。 params可以為數組或對象，根據API設計需要選擇。- 保持
jsonrpc字段的版本一致，避免兼容性問題。 - 正確處理錯誤碼和錯誤消息，提升調試效率。
- 充分利用批量操作和通知機制，優化通信效率。
這份詳細的JSON-RPC 2.0規范中文版旨在幫助開發者深入理解協議本質，正確實現與使用。希望你能在實際項目中靈活應用這一標準，搭建高效、可靠的分布式系統。
版權及免責聲明：本文內容參考自官方規范及公開資源，所有內容旨在教育和技術交流，非商業用途。如有侵權，請聯系刪除。
)
