RPC-JSON

Note: 如果只是要快速應用，其實可以跳過這篇。這裡主要是幫大家複習一些技術底層的概念。

什麼是 RPC-JSON？

理解 RPC-JSON 之前，可以先把它拆開成兩個部分來看：RPC 與 JSON。

RPC

RPC（Remote Procedure Call）和 REST API 一樣，都是 API 設計的架構，雖然 JSON-RPC 常透過 HTTP 傳輸，但協議本身並不限於 HTTP。

在 REST 中，我們會設計不同的 URL 來操作資源，屬於「資源導向」的設計。
例如：查看某一個 GitLab MR 的 URL 可能會長這樣：

/workspace/projectName/-/merge_requests/{id}，

而在 RPC 中，則是以「呼叫函式」的方式來與服務互動。
函式通常有名稱與參數，所以同樣的操作，在 RPC 可能會寫成：

get_merge_request(project_id, merge_request_iid) 來做。

JSON

這對軟體工程師應該再熟悉不過了，他就是一種交換資料的格式，具備以下特性：

• key/value pair
• JSON object ({})不保證順序的，要保證的話需要用 JSON array ([])
• 用{ 開頭 } 結尾

{
  "keyA: "valueA",
  "keyB": 123
}

RPC-JSON 協議內容

Request Object

• jsonrpc 指定協議版本
• method: 要呼叫的方法名稱
• 參數 params 必須用Structured值,可用array or object
• id 用 id 識別對應的response是哪個request, 如果沒有(id=null)指明代表不需要response

Response Object

• jsonrpc 指定協議版本
• result: 成功必須回傳, 失敗不能有值
• error: 有錯就會勢必填, 並且須符合 error object 格式

Note: result 與 error 是互斥的，不能同時存在。

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": {
      "available_methods": ["add", "subtract", "getUser"]
    }
  },
  "id": "1"
}

Batch

上一章我們有提到 batch 的概念：

透過一次 HTTP 請求，就能同時發送多的方法呼叫。

這樣的好處是你省掉 n-1 個 http 請求了，每次建立連線都會有額外的耗時。

要做到這件事其實並不複雜。還記得我們說過 RPC 就像是呼叫函式來和不同服務互動嗎？同樣的思路，我們只要把多個「函式呼叫」包裝在同一個請求裡，一次傳送出去就好了！

值得注意的是：

• JSON-RPC 規範允許伺服器平行處理 batch 中的請求。
• 因此 client 必須根據 id 去對應結果，而不是假設有序。

範例

RESTful API 處理多個動作時，必須各自發送請求：

GET /posts/12
POST /posts

而在 RPC 中，能夠用一個批次陣列一次完成：

--> [
  {"jsonrpc": "2.0", "method": "get_post", "params": [12], "id": "1"},
  {"jsonrpc": "2.0", "method": "create_post", "params": {"title": "test", "content": "haha"}}
]

<-- [
  {
    "jsonrpc": "2.0",
    "result": {
      "title": "深入了解 JSON-RPC 協議",
      "author": "Alicia",
      "date": "2025-09-18",
      "content": "這是一篇關於 JSON-RPC...",
      "tags": ["RPC", "JSON", "網路程式"]
    },
    "id": "1"
  }
]

TIPS: 你有發現 get_post 的 params 居然不是傳 12 而是 [12] 嗎？這就是 JSON-RPC 協議規範的，params 必須是 陣列 或 物件。

好吧今天科普了一些底層知識，希望大家覺得有趣！