1. 概述

JSON-RPC 是一个无状态、轻量级的远程过程调用(RPC)协议。它具有以下特点：

• 传输协议无关：可以在同一进程内、通过 Socket、HTTP 或其他消息传递环境中使用

• 使用 JSON 作为数据格式

• 设计简单易用

2. 基本概念

2.1 角色定义

• 客户端(Client)：Request 对象的发起者，Response 对象的处理者

• 服务端(Server)：Response 对象的发起者，Request 对象的处理者

2.2 数据类型

JSON-RPC 使用 JSON 的类型系统，包括：

• 4种基本类型：字符串(String)、数字(Number)、布尔值(Boolean)、空值(Null)

• 2种结构化类型：对象(Object)、数组(Array)

3. 通信协议

3.1 请求对象(Request Object)

请求对象包含以下字段：

3.2 响应对象(Response Object)

响应对象包含以下字段：

3.3 错误对象(Error Object)

错误对象包含以下字段：

3.4 预定义错误代码

4. 特殊请求类型

4.1 通知(Notification)

• 通知是一个没有 id 字段的请求对象

• 服务端不应该对通知做出响应

• 客户端不会收到执行结果和错误信息

4.2 批量请求(Batch)

• 客户端可以发送包含多个请求对象的数组

• 服务端应该返回包含对应响应对象的数组

• 通知请求不会在响应数组中产生对应项

• 响应顺序可以与请求顺序不同

• 批量请求可以并行处理

5. 使用示例

5.1 基本调用（位置参数）

// 左 --> 右  ## 左边代表客户端、右边代表服务端
--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

5.2 命名参数调用

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

5.3 通知调用

--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}

5.4 异常返回

rpc call of non-existent method:
--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "1"}

rpc call with invalid JSON:
--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

rpc call with invalid Request object:
--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

5.5 批量调用

--> [
        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
        {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"}
    ]
<-- [
        {"jsonrpc": "2.0", "result": 7, "id": "1"},
        {"jsonrpc": "2.0", "result": 19, "id": "2"}
    ]

6. 最佳实践

1. ID 生成：

   • 避免使用 null 作为 id 值

   • 数字 id 不应包含小数部分

2. 方法命名：

   • 以 “rpc.” 开头的方法名保留给系统扩展使用

   • 方法名大小写敏感

3. 错误处理：

   • 错误消息应该简洁明了

   • 可以通过 data 字段提供详细错误信息

4. 批量处理：

   • 合理使用批量请求以提高性能

   • 注意处理批量请求中的错误情况

7. 安全考虑

1. 传输层安全：

   • 在生产环境中使用 HTTPS

   • 考虑添加认证机制

2. 输入验证：

   • 验证方法名的合法性

   • 验证参数的类型和范围

3. 错误处理：

   • 避免在错误信息中暴露敏感信息

   • 对客户端错误和服务端错误做出明确区分

参考资料

• JSON-RPC 2.0 规范