json-rpc 调用协议

介绍

json

这个无需解释

{
    "username":"朱厚熜"
}

rpc

RPC，允许程序调用位于另一台计算机（服务器）上的函数或过程，就像调用本地函数一样
如常用的gRPC

其实日常前后端交互用的http api接口，也可以对内抽象解释为rpc调用，例如获取用户信息API
https://www.json-rpc.com/v1/get-info
调用/get_info时，后端通过路由中间层处理，执行的也都是get_info方法

    @RequestMapping (value="/get_info", method= RequestMethod.GET)
    public String get_info(String name){
        return "123"+name;
    }

JSON-RPC

总结下来就是，数据传输json，和常见的后端api一样，这套json由一套行业规范来执行，字段啊、数据格式啊都做了规范约束，而不是后端自己定义的接口文档

也可以理解为JSON-RPC是json的一套规范约定，可以参考我的另一篇文章， 关于JSON Schema 的，很类似

1. 简单性: 使用 JSON 作为数据格式，易于理解和解析。
2. 标准化: 定义了明确的消息格式和错误处理机制。
3. 跨平台/跨语言: 能传输JSON 的语言、平台，都可以使用。
4. 无状态: 每个请求都是独立的，服务器不需要维护客户端的状态，和http请求一样。

jsonrpc 有两个版本，本文主要讲jsonrpc 2.0
文档 https://www.jsonrpc.org/specification

使用

随意来看几个例子

这里我们使用http来传输JSON-RPC，当然你也可以使用webseck tcp获取其他的

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

// 使用命名参数
{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": { "subtrahend": 23, "minuend": 42 },
  "id": 2
}

// 通知 (Notification) - 服务器无需响应
{
  "jsonrpc": "2.0",
  "method": "update",
  "params": ["foo", "bar"]
}

// 成功响应
{
  "jsonrpc": "2.0",
  "result": 19, // 结果
  "id": 1
}

// 错误响应
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601, // 错误代码
    "message": "Method not found" // 错误信息
  },
  "id": 1
}

// 客户端可以批量请求多个json体
// 请求
[
    {"jsonrpc": "2.0", "method": "sum", "params": [1, 2, 3], "id": 1},
    {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 2},
    {"jsonrpc": "2.0", "method": "getData", "params": [], "id": 3}
]

// 响应
[
    {"jsonrpc": "2.0", "result": 6, "id": 1},
    {"jsonrpc": "2.0", "result": 19}
]

格式介绍

常见常用的json几个key介绍

• jsonrpc：协议版本号，必须是"2.0"。
• method：要调用的方法名称。
• params：传递给方法的参数，可以是数组或对象。
• id：请求的唯一标识符，用于匹配响应。

code码，表示错误的类型

• -32700: Parse error (解析错误) - 服务器接收到无效的 JSON。
• -32600: Invalid Request (无效请求) - JSON 不是一个有效的 Request 对象。
• -32601: Method not found (方法未找到) - 请求的方法不存在。
• -32602: Invalid params (无效参数) - 方法接收到无效的参数。
• -32603: Internal error (内部错误) - 服务器内部错误。
• -32000 to -32099: Server error (服务器错误) - 保留给服务器自定义错误。

服务器接收到请求后，解析并执行对应的方法，然后返回一个包含result或error字段的JSON对象作为响应。
请求 {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 1}
响应 {"jsonrpc": "2.0", "result": 19, "id": 1}

各个语言有对应的轮子框架，例如

• Python: jsonrpclib, Flask-JSONRPC
• JavaScript: jayson
• Java: jsonrpc4j
• Go: gorilla/rpc/json

以官网文档介绍为主

这里是对json请求体的介绍，每个字段都有说明

返回体介绍

返回体响应码

各种数据类型、场景示例
-->表示客户端传递给服务端 <-- 表示服务端响应

下面这种两个 --> 的表示通知，不需要服务端返回

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

例如
positional parameters 顺序传参
amed parameters 命名传参
a Notification 不需要服务端返回的

总之，文档写的非常详细

使用场景

• 微服务架构: JSON-RPC 可以用于微服务之间的通信。
• 移动应用后端: JSON-RPC 可以用于构建移动应用的后端 API。
• 浏览器扩展: JSON-RPC 可以用于浏览器扩展与本地应用程序之间的通信。
• 命令行工具: JSON-RPC 可以用于构建命令行工具与服务器之间的通信。
• 物联网 (IoT): JSON-RPC 可以用在资源受限的设备上进行通信。

最近比较火的大模型领域，agent自定义服务用的较为多，例如 MCP 服务，stdio sse 都是用的 json-rpc2.0