JSON-RPC 2.0 標準結構

JSON-RPC 2.0 是一個輕量級的遠程程序呼叫 (RPC) 協議，使用 JSON 格式作為訊息交換格式。它支持單向呼叫、通知、批次請求及回應，並提供錯誤處理機制。JSON-RPC 2.0 並不限制實作細節，這讓它可以廣泛應用於不同的應用場景。

訊息結構

每個 JSON-RPC 訊息包含以下基本元素：

1. jsonrpc

• 類型: 字串
• 描述: 指定 JSON-RPC 的版本。對於所有 JSON-RPC 2.0 訊息，該字段應設為 "2.0"。

2. method

• 類型: 字串
• 描述: 要呼叫的方法名稱。這是處理請求的關鍵。

3. params

• 類型: 陣列或物件 (可選)
• 描述: 方法的引數。這個字段是可選的，取決於所呼叫的方法是否需要引數。若方法不需要參數，該字段可省略。

4. id

• 類型: 整數、字串或 null
• 描述: 用於標識請求的 ID。此 ID 在回應中會返回，以便與請求一一對應。若為通知型請求，該字段可省略。

JSON-RPC 2.0 訊息類型

JSON-RPC 2.0 支援三種主要訊息類型：Request、Response 和 Error。

Request 訊息

請求訊息由客戶端發出，要求伺服器執行某個方法。請求訊息必須包含 jsonrpc、method、params 和 id。

範例：

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": [42, 23],
  "id": 1
}

• method: 要呼叫的方法名稱，如 subtract。
• params: 呼叫方法所需的引數，這裡是 [42, 23]。
• id: 請求的唯一標識符，這裡是 1。

Response 訊息

回應訊息由伺服器回傳，表示方法執行的結果。回應訊息包含 jsonrpc、result 和 id。

範例：

{
  "jsonrpc": "2.0",
  "result": 19,
  "id": 1
}

• result: 方法執行的結果，這裡是 19。
• id: 用來對應請求訊息的 ID。

Error 訊息

錯誤訊息由伺服器回傳，表示方法執行過程中出現了錯誤。錯誤訊息包含 jsonrpc、error 和 id。

範例：

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  },
  "id": 1
}

• error: 錯誤訊息，包含錯誤代碼 code 和錯誤描述 message。
  • code: -32602 表示參數無效。
  • message: 錯誤的簡短描述，這裡是 "Invalid params"。
• id: 用來對應請求訊息的 ID。

錯誤處理

當方法執行失敗時，錯誤訊息需要包含以下字段：

1. code

• 類型: 整數
• 描述: 錯誤的代碼。標準錯誤代碼可以參考 JSON-RPC 2.0 錯誤代碼 定義。

2. message

• 類型: 字串
• 描述: 錯誤的簡短描述。

3. data (可選)

• 類型: 任意
• 描述: 用於提供附加的錯誤訊息，這是可選的。

通知

通知是 JSON-RPC 2.0 的一種特殊請求形式，它不需要 id 欄位。這表示客戶端發送請求但不期望回應。

範例：

{
  "jsonrpc": "2.0",
  "method": "sendMessage",
  "params": ["Hello, World!"]
}

批次請求

JSON-RPC 2.0 允許在一個 HTTP 請求中包含多個 JSON-RPC 請求。這被稱為批次請求。每個請求都會有自己的 jsonrpc、method、params 和 id。伺服器會對每個請求返回獨立的回應。

範例：

[
  {
    "jsonrpc": "2.0",
    "method": "subtract",
    "params": [42, 23],
    "id": 1
  },
  {
    "jsonrpc": "2.0",
    "method": "add",
    "params": [1, 2],
    "id": 2
  }
]

回應：

[
  {
    "jsonrpc": "2.0",
    "result": 19,
    "id": 1
  },
  {
    "jsonrpc": "2.0",
    "result": 3,
    "id": 2
  }
]

標準錯誤代碼

JSON-RPC 2.0 定義了一些標準的錯誤代碼，這些代碼有助於識別不同類型的錯誤。以下是一些常見的錯誤代碼：

• -32600: 無效的請求
• -32601: 方法未找到
• -32602: 無效的參數
• -32603: 內部錯誤
• -32700: 解析錯誤

小結

JSON-RPC 2.0 是一個靈活且強大的 RPC 協議，廣泛應用於各種分布式系統中。它具有簡單、清晰的結構，可以輕鬆地進行擴展和調整以符合不同的需求。