JSON-RPC 2.0 Library for Cangjie

一个使用仓颉编程语言实现的完整、类型安全的JSON-RPC 2.0协议库，支持请求、响应、通知和批处理操作。

项目概述

这是一个JSON-RPC 2.0库实现，使用仓颉编程语言编写。它提供了完整的、类型安全的JSON-RPC协议实现，支持请求、响应、通知和批处理操作。

主要特性

• ✅ 完整的JSON-RPC 2.0协议支持 - 严格遵循JSON-RPC 2.0规范
• ✅ 类型安全 - 使用仓颉的类型系统确保运行时安全
• ✅ 模块化架构 - 清晰分离的核心组件和接口
• ✅ 批处理支持 - 完整的批量请求和响应处理
• ✅ 扩展性 - 基于接口的设计允许自定义处理器实现
• ✅ 完整测试覆盖 - 59个单元测试 + 23个性能基准测试
• ✅ 高性能 - 优化的序列化和解析性能

快速开始

安装和构建

# 构建项目
cjpm build

# 运行测试
cjpm test

# 运行性能基准测试
cjpm bench

# 清理构建文件
cjpm clean

基本使用示例

1. 创建服务器

import jsonrpc.server.*
import jsonrpc.core.*
import stdx.encoding.json.*

// 创建处理器
let handler = SimpleJsonRpcHandler()

// 注册方法处理器
let echoHandler: RequestHandler = { params =>
    match (params) {
        case Some(value) => JsonRpcResult.Success(value)
        case None => JsonRpcResult.Success(JsonString("empty"))
    }
}
handler.registerMethod("echo", echoHandler)

// 创建服务器
let server = JsonRpcServer(handler)

// 启动服务器
match (server.start()) {
    case JsonRpcResult.Success(_) => println("服务器已启动")
    case JsonRpcResult.Error(err) => println("启动失败: ${err}")
}

2. 处理请求

// 处理JSON-RPC请求
let requestJson = '{"jsonrpc":"2.0","method":"echo","params":"hello","id":"1"}'
match (server.processMessage(requestJson)) {
    case JsonRpcResult.Success(Some(response)) => println("响应: ${response}")
    case JsonRpcResult.Success(None) => println("处理通知消息")
    case JsonRpcResult.Error(err) => println("处理错误: ${err}")
}

3. 批处理请求

// 处理批量请求
let batchJson = '[
    {"jsonrpc":"2.0","method":"echo","params":"hello","id":"1"},
    {"jsonrpc":"2.0","method":"echo","params":"world","id":"2"}
]'
match (server.processBatchMessage(batchJson)) {
    case JsonRpcResult.Success(responses) => println("批量响应: ${responses}")
    case JsonRpcResult.Error(err) => println("批处理错误: ${err}")
}

架构设计

核心组件

项目采用模块化架构，具有完整的测试覆盖：

src/core/ - 核心消息类型和测试

实现: src/core/message.cj 包含JSON-RPC 2.0的基础消息结构：

• RequestId 枚举 - 处理字符串、数字或null类型的ID
• JsonRpcRequest 结构 - 带有方法、参数和ID的请求消息
• JsonRpcResponse 结构 - 带有结果或错误的响应消息
• JsonRpcNotification 结构 - 通知消息（无ID）
• JsonRpcError 结构 - 标准化错误对象

测试: src/core/message_test.cj (18个测试用例) 全面的单元测试，覆盖所有核心消息功能。

src/codec/ - 消息解析和验证

实现: src/codec/parser.cj 中心解析逻辑：

• JsonRpcParser 类 - 严格遵循JSON-RPC 2.0协议的主解析器
• JsonRpcMessage 枚举 - 所有消息类型的判别联合
• ParseResult 枚举 - 类型安全的解析结果
• 标准错误响应的静态工厂方法（-32700至-32603）

测试: src/codec/parser_test.cj (20个测试用例) 广泛的解析、验证和错误处理测试。

src/server/ - 服务器实现

实现: src/server/server.cj 服务器基础设施：

• JsonRpcHandler 接口 - 定义请求/通知处理
• SimpleJsonRpcHandler 类 - 基于HashMap的方法路由
• JsonRpcServer 类 - 支持单一和批量消息处理的主服务器
• 支持通过函数引用进行方法注册
• 全面的错误处理和响应生成

测试: src/server/server_test.cj (21个测试用例) 完整的服务器功能、处理器注册和消息处理测试。

src/benchmark/ - 性能测试

实现: src/benchmark/benchmark.cj 使用仓颉@Bench宏的综合性能测试套件，涵盖：

• 所有类型的消息序列化性能
• 各种JSON-RPC消息格式的解析性能
• 服务器吞吐量和处理能力
• 处理器注册和查找性能
• 错误处理和恢复性能

设计模式

1. 类型安全: 广泛使用Option类型和模式匹配来消除空指针错误
2. 协议合规: 严格遵循JSON-RPC 2.0规范，进行适当验证
3. 错误处理: 完整的错误分类，支持标准错误码和自定义错误
4. 扩展性: 基于接口的设计允许自定义处理器实现
5. 批处理: 完全支持JSON-RPC 2.0规范中的批量请求

测试

测试覆盖

项目拥有完整的测试套件，包括单元测试和性能基准测试：

单元测试 (59个测试用例)

核心消息类型测试 - src/core/message_test.cj (18个测试用例):

• RequestIdTests (6个测试用例) - 字符串、数字、null ID的创建和序列化
• JsonRpcRequestTests (4个测试用例) - 请求消息创建、参数处理、验证
• JsonRpcResponseTests (3个测试用例) - 成功和错误响应处理
• JsonRpcNotificationTests (3个测试用例) - 通知消息处理
• JsonRpcMessageTests (2个测试用例) - 消息类型枚举和序列化

编解码器测试 - src/codec/parser_test.cj (20个测试用例):

• ParserConfigTests (2个测试用例) - 解析器配置
• JsonRpcParserTests (10个测试用例) - 各种消息类型解析和错误处理
• JsonRpcParserFactoryTests (5个测试用例) - 标准错误响应创建
• JsonRpcParserValidationTests (3个测试用例) - 消息验证逻辑

服务器实现测试 - src/server/server_test.cj (21个测试用例):

• ServerConfigTests (2个测试用例) - 服务器配置
• ServerStatsTests (2个测试用例) - 统计信息
• SimpleJsonRpcHandlerTests (5个测试用例) - 处理器注册和调用
• JsonRpcServerTests (9个测试用例) - 完整服务器功能
• CompositeJsonRpcHandlerTests (3个测试用例) - 复合处理器功能

性能基准测试 (23个基准测试)

消息序列化基准测试:

• 请求序列化性能（基本和带参数）
• 响应和错误响应序列化性能
• 通知序列化性能

消息解析基准测试:

• 各种JSON-RPC消息类型的解析性能
• 批量请求解析性能

服务器性能基准测试:

• 简单请求和计算请求处理性能
• 通知和无效请求处理性能
• 批量请求处理性能

处理器基准测试:

• 方法注册和查找性能
• 未知方法查找性能
• 支持方法列表获取性能

错误处理基准测试:

• 标准错误和自定义错误创建性能
• 错误序列化和响应创建性能

运行测试

# 运行所有单元测试
cjpm test

# 运行性能基准测试
cjpm bench

# 查看详细的测试报告
cjpm test --verbose

# 生成HTML性能报告
cjpm bench --report-format=html

# 导出性能数据为CSV
cjpm bench --report-format=csv-raw

测试结果

• 单元测试: 59/59 通过 ✅
• 性能测试: 23/23 通过 ✅
• 构建状态: 成功 ✅
• 协议合规: JSON-RPC 2.0完全兼容 ✅

API 参考

完整的API文档请参考 docs/api-reference.md

核心消息类型

• RequestId - JSON-RPC请求标识符（字符串、数字或null）
• JsonRpcRequest - JSON-RPC请求消息
• JsonRpcResponse - JSON-RPC响应消息
• JsonRpcNotification - JSON-RPC通知消息（无ID）
• JsonRpcError - 标准化错误对象

服务器组件

• JsonRpcHandler - 处理器接口
• SimpleJsonRpcHandler - 简单处理器实现
• JsonRpcServer - 主服务器类
• CompositeJsonRpcHandler - 复合处理器

解析和序列化

• JsonRpcParser - 消息解析器
• JsonRpcMessage - 消息类型枚举
• ParseResult - 解析结果枚举

依赖项

• 核心依赖: stdx.encoding.json 用于JSON处理
• 集合类: std.collection.HashMap 和 ArrayList 用于数据结构
• 扩展库: 使用位于 third_party/stdx/ 的仓颉扩展标准库

扩展库提供预编译的二进制文件和头文件：

• JSON编解码 (stdx.encoding.json)
• HTTP网络 (stdx.net.http)
• 加密功能 (stdx.crypto)
• 增强测试功能 (stdx.unittest)

语言特性

使用的仓颉语言特性

1. 模式匹配: 广泛使用match语句进行类型判别
2. Option类型: 使用Option<T>和Some/None模式安全处理空值
3. 带数据的枚举: 如RequestId和JsonRpcMessage等丰富的枚举类型
4. 接口和类: 使用JsonRpcHandler接口实现清晰的关注点分离
5. 异常处理: 使用try/catch块进行适当的错误传播
6. 函数类型: 方法处理器使用一等函数(Option<JsonValue>) -> JsonValue

错误处理策略

库实现了多层错误处理方法：

• 解析级别: ParseResult枚举捕获JSON和协议错误
• 协议级别: 标准JSON-RPC错误码和适当的错误对象
• 应用级别: 方法处理器中的异常处理和错误响应生成
• 批处理级别: 批处理内单个消息错误隔离

开发工作流

在这个代码库上工作时：

1. 添加新方法: 通过SimpleJsonRpcHandler.registerMethod()注册处理器
2. 自定义处理器: 为复杂路由实现JsonRpcHandler接口
3. 测试更改: 始终运行cjpm test确保所有59个测试用例通过
4. 性能影响: 使用cjpm bench验证没有性能回归
5. 协议合规: 确保所有更改保持JSON-RPC 2.0规范合规

代码质量标准

• 所有新功能必须包含相应的单元测试
• 性能关键代码应包含基准测试
• 使用仓颉惯用法：模式匹配、Option类型、适当的错误处理
• 遵循既定的命名约定和代码组织
• 为公共API维护全面的文档

许可证

本项目基于MIT许可证开源。

贡献

欢迎贡献！请确保：

1. 所有测试通过
2. 遵循代码风格指南
3. 为新功能添加测试
4. 更新相关文档

---

这个库专为在大型仓颉语言服务器或基于RPC的应用程序中用作依赖项而设计。