json-rpc 2.0

JSON-RPC 2.0 是一种 轻量级远程过程调用（RPC, Remote Procedure Call）协议，使用 JSON 作为数据格式，通常通过 HTTP、WebSocket 或 TCP 传输。

它的核心作用是：让客户端可以像调用本地函数一样调用远程服务的方法。

简单理解：JSON-RPC = 用 JSON 格式描述的函数调用协议。

适用场景：
轻量级 API 交互（如前后端通信、微服务间调用）；
跨语言/跨平台通信（JSON 通用性强）；
对协议复杂度敏感的场景（相比 gRPC 更简单，无需 proto 定义）。
与其他 RPC 协议对比
协议 优点 缺点
JSON-RPC 2.0 简单、无依赖、跨语言友好、易调试 无类型校验、不支持流式传输、性能一般
gRPC 强类型、高性能、支持流式/双向通信 依赖 proto 文件、学习成本高、调试复杂
XML-RPC 成熟、跨语言支持广 XML 冗余、解析效率低

JSON-RPC 2.0规定了 请求和响应的标准格式。

请求格式：

{
  "jsonrpc": "2.0",
  "method": "getUser",
  "params": {
    "id": 1
  },
  "id": 1
}

字段 说明
jsonrpc 协议版本，必须是 "2.0"
method 要调用的方法名
params 方法参数（可选）
id 请求ID，用于匹配响应

可以理解为method就是函数名，params就是函数的参数。

params按数组位置：

"params": [value1, value2, value3]

参数顺序必须完全匹配，客户端与服务器双方必须清楚位置含义，如果顺序错了就调用失败（服务器无法解析），参数数目要匹配缺少或多给都会报错。

这种一般适用于资源小，带宽紧张的事实控制，参数稍而且固定的场景。

params按对象名称：

"params": { "x": 1, "y": 2, "speed": 0.5 }

按对象名称提供的最灵活，最容易读，这是一个键-值对的方式，但是参数的名称必须要完全匹配（包括大小写），参数的顺序没有要求。

按数组的方式可以理解为只有原始数据，没有对应数据的标签。而按照对象的方式有数据和对应的标签。

响应格式：

{
  "jsonrpc": "2.0",
  "result": {
    "name": "Tom",
    "age": 18
  },
  "id": 1
}

字段 说明
result 方法执行结果
id 和请求ID一致

错误响应：

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

字段 说明
code 错误码
message 错误信息

标准错误码（协议定义，不可自定义）
错误码 含义描述
-32700 解析错误：请求 JSON 格式无效
-32600 无效请求：JSON 格式有效，但不符合 RPC 规范（如缺少 jsonrpc: "2.0"）
-32601 方法未找到：请求的 method 不存在
-32602 参数错误：params 格式错误或参数不匹配
-32603 内部错误：服务器执行方法时发生未知错误
-32000~-32099 服务器自定义错误：需在文档中说明具体含义

通知（无id，不需要响应）：

{
  "jsonrpc": "2.0",
  "method": "updateStatus",
  "params": {
    "status": "online"
  }
}

服务器 不会返回任何结果。这种叫 Notification。

Batch请求（批量调用）
JSON-RPC 2.0 支持 一次调用多个方法。

请求：

[
  {
    "jsonrpc": "2.0",
    "method": "getUser",
    "params": [1],
    "id": 1
  },
  {
    "jsonrpc": "2.0",
    "method": "getUser",
    "params": [2],
    "id": 2
  }
]

响应：

[
  {
    "jsonrpc": "2.0",
    "result": {"name":"Tom"},
    "id":1
  },
  {
    "jsonrpc": "2.0",
    "result": {"name":"Jerry"},
    "id":2
  }
]

关键约束与注意事项：
版本强制：jsonrpc 字段必须为字符串 "2.0"，大小写敏感；
id 匹配规则：
请求的 id 若为非 Null 有效值，响应必须返回相同 id；
若请求 id 无效（如 True、空对象），服务器返回 id: Null 的错误响应；
参数格式：params 只能是数组或对象，不能是字符串、数字等原始类型；
方法名约束：method 不能以 rpc. 开头（系统保留前缀）；
HTTP 传输建议：
仅支持 POST 方法（GET 方法不适合携带复杂 params）；
响应状态码：成功用 200 OK，解析错误用 400 Bad Request，服务器错误用 500 Internal Server Error；
批量请求限制：若批量请求为空数组（[]），服务器返回 -32600 无效请求错误。