json-rpc:基于仓颉语言的JSON-RPC 2.0通用框架项目

仓颉通用JSON-RPC 2.0 通用框架

Branch2Tags13
FilesLast commitLast update
1 month ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
28 days ago
1 month ago
3 months ago
2 months ago
1 month ago
3 months ago
28 days ago

ystyle::jsonrpc

JSON-RPC 2.0 通用框架(仓颉语言)

安装

[dependencies]
  "ystyle::jsonrpc" = "0.7.3"
  # 按需选择传输层
  "ystyle::jsonrpc_stdio" = "0.7.3"      # Stdio
  "ystyle::jsonrpc_tcp" = "0.7.3"        # TCP
  "ystyle::jsonrpc_unix" = "0.7.3"       # Unix Socket
  "ystyle::jsonrpc_http" = "0.7.3"       # HTTP POST
  "ystyle::jsonrpc_websocket" = "0.7.3"  # WebSocket

快速开始

服务端

import ystyle::jsonrpc.*
import ystyle::jsonrpc_stdio.*

main() {
    let transport = StdioTransport()
    let server = JsonRpcServer(transport)
    
    server.register("echo", { ctx =>
        HandlerResult.ok(ctx.getRawParams() ?? JsonValue.Null)
    })
    
    server.start()
}

客户端

import ystyle::jsonrpc.*
import ystyle::jsonrpc_stdio.*

main() {
    let transport = StdioTransport()
    let client = JsonRpcClient(transport)
    client.start()
    
    let result = client.call<JsonValue, JsonValue>("echo",
        params: Some(JsonValue.Map(HashMap<String, JsonValue>())))
    match (result) {
        case Ok(v) => println(v.stringify())
        case Err(e) => println("错误: ${e}")
    }
    
    client.close()
}

传输层

包 类 用途
jsonrpc_stdio StdioTransport LSP、进程管道
jsonrpc_tcp TcpClientTransport / TcpServerTransport 网络服务
jsonrpc_unix UnixClientTransport / UnixServerTransport 本地高性能通信
jsonrpc_http HttpClientTransport / HttpRpcHandler / HttpRpcHelper HTTP POST 短连接
jsonrpc_websocket WebSocketClientTransport / WebSocketServerHandler WebSocket 长连接

TCP

服务端:

import ystyle::jsonrpc.*
import ystyle::jsonrpc_tcp.*

main() {
    let server = TcpServerTransport(port: 8080)
    while (let Some(conn) <- server.acceptConnection()) {
        let rpc = JsonRpcServer(conn)
        rpc.register("echo", { ctx =>
            HandlerResult.ok(ctx.getRawParams() ?? JsonValue.Null)
        })
        rpc.start()
    }
}

客户端:

import ystyle::jsonrpc.*
import ystyle::jsonrpc_tcp.*

main() {
    let transport = TcpClientTransport("127.0.0.1", 8080)
    let client = JsonRpcClient(transport)
    client.start()
    
    let result = client.call<JsonValue, JsonValue>("echo",
        params: Some(JsonValue.Map(HashMap<String, JsonValue>())))
    // ...
    client.close()
}

Unix Socket

服务端:

import ystyle::jsonrpc.*
import ystyle::jsonrpc_unix.*

main() {
    let server = UnixServerTransport(path: "/tmp/rpc.sock")
    while (let Some(conn) <- server.acceptConnection()) {
        let rpc = JsonRpcServer(conn)
        rpc.register("echo", { ctx =>
            HandlerResult.ok(ctx.getRawParams() ?? JsonValue.Null)
        })
        rpc.start()
    }
}

客户端:

import ystyle::jsonrpc.*
import ystyle::jsonrpc_unix.*

main() {
    let transport = UnixClientTransport(path: "/tmp/rpc.sock")
    let client = JsonRpcClient(transport)
    client.start()
    // ...
    client.close()
}

HTTP POST

集成到现有 HTTP Server:

import ystyle::jsonrpc.*
import ystyle::jsonrpc_http.*
import stdx.net.http.*

let httpServer = ServerBuilder().addr("0.0.0.0").port(8080).build()
let rpcServer = JsonRpcServer(/* transport 由 handler 内部处理 */)
rpcServer.register("echo", { ctx => HandlerResult.ok(ctx.getRawParams() ?? JsonValue.Null) })

httpServer.route("/rpc", HttpRpcHandler(rpcServer))
httpServer.start()

客户端(复用现有 HTTP Client):

import ystyle::jsonrpc.*
import ystyle::jsonrpc_http.*
import stdx.net.http.*

let httpClient = ClientBuilder().build()
let transport = HttpClientTransport(httpClient, "http://localhost:8080/rpc")
let rpcClient = JsonRpcClient(transport)
rpcClient.start()

WebSocket 长连接

服务端(集成到现有 HTTP Server):

import ystyle::jsonrpc.*
import ystyle::jsonrpc_websocket.*
import stdx.net.http.*

let httpServer = ServerBuilder().addr("0.0.0.0").port(8080).build()
let rpcServer = JsonRpcServer(/* transport 由 handler 内部处理 */)
rpcServer.register("echo", { ctx => HandlerResult.ok(ctx.getRawParams() ?? JsonValue.Null) })

httpServer.route("/ws", WebSocketServerHandler(rpcServer))
httpServer.start()

客户端:

import ystyle::jsonrpc.*
import ystyle::jsonrpc_websocket.*
import stdx.net.http.*

let httpClient = ClientBuilder().build()
let transport = WebSocketClientTransport.connect(httpClient, "ws://localhost:8080/ws")
let rpcClient = JsonRpcClient(transport)
rpcClient.start()

API

API 按源码文件分组,与 jsonrpc/src/ 一一对应。

types.cj — 消息类型

  • RequestId — 请求 id(数字或字符串),实现 Hashable & Equatable
  • Request / Response / Notification / JsonRpcError — 协议消息类型,均实现 JsonSerializable & JsonDeserializable,可配合 serialize* / deserialize* 或 JsonValue.fromObject 使用
  • ErrorCodes — 标准错误码常量(见下方「错误码」)

message.cj — 消息编解码

函数 说明
serializeRequest(req) / deserializeRequest(bytes) 请求编解码
serializeResponse(resp) / deserializeResponse(bytes) 响应编解码
serializeNotification(notif) / deserializeNotification(bytes) 通知编解码
parseMessage(bytes): Message 解析任意消息(gjson 快速分类,含批处理)

Message 枚举:

public enum Message {
    | SingleRequest(Request)
    | SingleResponse(Response)
    | SingleNotification(Notification)
    | InvalidRequest(JsonRpcError)
    | BatchRequest(ArrayList<Message>)
    | BatchResponse(ArrayList<Response>)
}

framing.cj — 分帧

public interface Framing {
    func encode(body: Array<Byte>): Array<Byte>
    func decode(data: Array<Byte>): ?(Array<Byte>, Int64)  // (body, consumed)
}

实现:

  • ContentLengthFraming — Content-Length 头分帧(默认,LSP 标准)
  • NewlineFraming — 换行分帧
  • 顶层便捷函数 encode(body) / decode(content) 使用 ContentLengthFraming

transport.cj — 传输接口

public interface Transport <: Resource {
    func send(data: Array<Byte>): Unit
    func receive(): ?Array<Byte>
    func isClosed(): Bool
}

具体实现见上方「传输层」各包。

exception.cj — 异常与结果

  • JsonRpcException — 协议异常,code 携带 JSON-RPC 错误码
  • Result<T> — call / request 的返回类型:
public enum Result<T> {
    | Ok(T)
    | Err(String)
}

server.cj — JsonRpcServer

方法 说明
init(transport, framing!) 构造(默认 ContentLengthFraming)
register(method, handler) 注册同步处理器
registerAsync(method, handler) 注册异步处理器:handler 内 spawn 任务后通过 complete(result) 回响应,不阻塞接收线程(适合 handler 内再次发起请求的场景)
registerAsyncErr(method, handler) 注册异步处理器(带错误回调):complete(result) 成功 / fail(error) 返回 JSON-RPC 错误响应
use(middleware) 添加中间件(洋葱模型)
start() 启动服务(后台线程,非阻塞)
serve() 启动服务(当前线程,阻塞至 close)
notify<T>(method, params) / notify(method) 向对端发送通知
request<T, R>(method, params, timeout) 服务端主动发起请求(如 LSP client/registerCapability),返回 Result<R>;同一时刻仅一个挂起出站请求
copyHandlersFrom(other) 复制另一 server 的处理器
copyMiddlewaresFrom(other) 复制另一 server 的中间件
getHandlers() / getMiddlewares() 获取当前注册表
isClosed() 是否已关闭

处理器类型别名:

public type Handler = (HandlerContext) -> HandlerResult
public type AsyncHandler = (HandlerContext, (JsonValue) -> Unit) -> Unit
public type AsyncHandlerErr = (HandlerContext, (JsonValue) -> Unit, (JsonRpcError) -> Unit) -> Unit
public type Middleware = (RequestContext, () -> HandlerResult) -> HandlerResult

client.cj — JsonRpcClient

方法 说明
init(transport, framing!) 构造(默认 ContentLengthFraming)
call<T, R>(method, params, timeout) 同步调用,返回 Result<R>
call(method, timeout) 无参数调用,返回 Result<JsonValue>
notify<T>(method, params) / notify(method) 发送通知(无响应)
setNotificationCallback(cb) 设置单个通知回调(覆盖已有)
setNotificationCallback(cbs) 设置多个通知回调(整体覆盖)
addNotificationCallback(cb) 追加通知回调(保留已有,支持多订阅)
registerRequestHandler(method, handler) 处理服务端发来的请求(双工),handler 返回 ?JsonValue(None = 不回复)
sendResponse(id, result) 显式回复服务端请求
start() 启动接收循环(后台线程)
close() / isClosed() 关闭 / 查询状态

HandlerContext(server.cj)

成员 说明
getParam(key) 获取单个参数
getParamAs<T>(key) 获取并转换类型
getParams<T>() 获取整个参数对象
getRawParams() 获取原始 JsonValue

requestId(v0.7.3):当前请求 id,仅请求消息有值(通知为 None)。

HandlerResult(server.cj)

方法 说明
ok(value) 成功结果(JsonValue)
ok<T>(value) 成功结果(自动序列化)
err(code, message) 返回错误
err(code, message, data) 返回错误(带 data)

RequestContext(request + transport,见上方 Middleware 别名)与 PendingRequest(setResponse / waitForResponse)为内部组件,通常无需直接使用。

双向 RPC(双工)

同一连接上两端都可主动发起请求/通知并回复对方请求(JSON-RPC 2.0 对等模型,如 LSP 的 client/registerCapability)。

import ystyle::jsonrpc.*
import ystyle::jsonrpc_stdio.*

main() {
    // ── 对等端 A:注册本地服务 + 处理对端请求 + 订阅通知
    let a = JsonRpcClient(StdioTransport())
    a.registerRequestHandler("ping", { req => Some(JsonValue.Bool(true)) })
    a.setNotificationCallback({ notif => println("A got notify: ${notif.method}") })
    a.start()

    // ── 对等端 B:注册本地服务,并主动向 A 发请求 / 通知
    let b = JsonRpcServer(StdioTransport())
    b.register("echo", { ctx => HandlerResult.ok(ctx.getRawParams() ?? JsonValue.Null) })
    b.start()

    // 服务端主动发起请求(B → A)
    let r = b.request<JsonValue, JsonValue>("ping", params: None)
    match (r) {
        case Ok(v) => println("B <- A: ${v.stringify()}")
        case Err(e) => println("请求失败: ${e}")
    }
}

错误码

常量 代码
ErrorCodes.PARSE_ERROR -32700
ErrorCodes.INVALID_REQUEST -32600
ErrorCodes.METHOD_NOT_FOUND -32601
ErrorCodes.INVALID_PARAMS -32602
ErrorCodes.INTERNAL_ERROR -32603

文档

License

MIT

Introduction

仓颉通用JSON-RPC 2.0 通用框架

Customize your domain