第一部分 概述

JSON-RPC 2.0是一种基于JSON（JavaScript Object Notation）的远程过程调用（RPC）协议。它是一种轻量级的、无状态的、跨语言的通信协议，常用于客户端与服务端之间的交互。

第二部分 基本特点

• 简单直观：消息结构清晰，仅由JSON对象组成。
• 双向通信：支持客户端调用服务端方法，服务端也可通知客户端。
• 无状态：协议本身不维护会话状态。
• 支持批量请求：允许在一个JSON数组中发送多个请求，提升效率。
• 错误处理：定义了标准的错误对象，便于排查和处理异常。

第三部分 消息格式

在JSON-RPC 2.0中，有以下三种主要的消息类型：

• 请求对象（Request Object）
• 响应对象（Response Object）
• 通知对象（Notification Object）

3.1 请求对象

用于客户端调用服务端的方法，结构如下：

json
{
  "jsonrpc": "2.0",
  "method": "methodName",
  "params": ["param1", "param2"],
  "id": 1
}

• jsonrpc：协议版本，固定为2.0。
• method：调用的远程方法名。
• params：方法参数，可以是数组或对象。
• id：唯一标识请求的ID，用于匹配响应。可为数字、字符串或null。

示例：

json
{
  "jsonrpc": "2.0",
  "method": "add",
  "params": [4, 5],
  "id": 123
}

3.2 响应对象

用于服务端返回结果或错误信息，结构如下：

成功响应：

json
{
  "jsonrpc": "2.0",
  "result": 9,
  "id": 123
}

• jsonrpc：协议版本。
• result：调用方法的返回结果。
• id：与请求对象中的id一致，用于匹配响应。

错误响应：

json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": "Additional information if available"
  },
  "id": null
}

• error：包含错误信息的对象。
  • code：标准错误码。
  • message：错误描述信息。
  • data：可选的额外错误信息。
• id：如果无法解析请求或无法响应，则id设为null。

---

3.3 通知对象

通知是一种特殊的请求，不需要响应。用于不关心结果的场景，例如日志记录等。

通知对象示例：

json
{
  "jsonrpc": "2.0",
  "method": "logMessage",
  "params": ["User logged in"]
}

• 没有id字段。
• 不会有响应对象返回。

第四部分 错误码列表

JSON-RPC 2.0定义了一组标准错误码：

错误码	错误类型	描述
-32700	Parse Error	无法解析 JSON 数据
-32600	Invalid Request	请求对象无效
-32601	Method Not Found	方法不存在或不可用
-32602	Invalid Params	参数无效
-32603	Internal Error	服务端内部错误
-32000~-32099	Server Error	自定义服务器错误

第五部分 批量请求与响应

JSON-RPC 2.0支持在一个请求中发送多个调用，服务端也会以数组形式返回响应。

批量请求示例：

json
[
  {
    "jsonrpc": "2.0",
    "method": "add",
    "params": [1, 2],
    "id": 1
  },
  {
    "jsonrpc": "2.0",
    "method": "subtract",
    "params": [5, 3],
    "id": 2
  }
]

批量响应示例：

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

如果某个请求是通知或者出错，也会在响应中反映：

json
[
  {
    "jsonrpc": "2.0",
    "result": 3,
    "id": 1
  },
  {
    "jsonrpc": "2.0",
    "error": {
      "code": -32601,
      "message": "Method not found"
    },
    "id": 2
  }
]

第六部分 示例场景

场景1：简单调用 客户端请求服务端进行加法运算：

json
{
  "jsonrpc": "2.0",
  "method": "add",
  "params": [10, 20],
  "id": 100
}

服务端返回结果：

json
{
  "jsonrpc": "2.0",
  "result": 30,
  "id": 100
}

---

场景2：错误处理 客户端请求一个不存在的方法：

json
{
  "jsonrpc": "2.0",
  "method": "unknownMethod",
  "params": [],
  "id": 101
}

服务端返回错误：

json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found"
  },
  "id": 101
}

场景3：通知 客户端发送通知，不需要返回结果：

json
{
  "jsonrpc": "2.0",
  "method": "notifyEvent",
  "params": ["EventData"]
}

服务端不会返回任何响应。

第七部分 总结

JSON-RPC 2.0提供了一种简洁、灵活且强大的通信方式，特别适用于：

• 分布式系统中的服务调用
• 微服务架构下的跨语言交互
• 物联网设备与后端服务的通信

通过JSON-RPC 2.0，可以高效地管理远程方法调用、错误处理和批量操作，提升系统的整体性能和可靠性。