1. 项目概述与核心价值最近在重构一个老项目的内部服务通信模块原来的协议五花八门有自定义的二进制格式也有简单的HTTP接口维护和联调起来非常头疼。痛定思痛决定引入一个标准化的RPC框架来统一管理。考察了一圈像gRPC、Thrift这些虽然功能强大但依赖和部署成本对当前这个体量的项目来说有点重。而JSON-RPC协议以其基于JSON的轻量级、人类可读、与HTTP天然结合的特性成了我的首选。市面上成熟的C JSON-RPC库不少比如json-rpc-cxx但直接拿来用总觉得少了点什么——一是想彻底吃透协议细节二是希望框架能完全贴合自己项目的代码风格和异常处理逻辑。于是我决定动手从零实现一个。这个“从零实现”的过程远不止是调用几个现成的JSON解析库那么简单。它涉及到网络通信模型的选择、请求/响应协议的封装、方法的动态注册与分发、以及如何设计一套既安全又易用的API。最终产出的不仅仅是一个可用的库更是一份对JSON-RPC 2.0规范、C现代特性如移动语义、类型安全以及网络编程的深度实践笔记。无论你是想在自己的C项目中引入轻量级RPC还是希望通过一个综合性项目来锤炼网络编程和框架设计能力跟着走一遍这个过程收获都会远超预期。2. 整体架构设计与核心思路一个完整的JSON-RPC框架可以清晰地划分为几个层次。我的设计目标是核心协议层与网络传输层解耦让框架既能用于简单的本地进程间通信也能轻松接入HTTP、WebSocket等网络协议。2.1 分层架构解析最底层是传输层。这一层只负责字节流的收发对内容不做任何假设。它可能是一个TCP Socket、一个HTTP服务器连接甚至是一块共享内存。框架核心不应该绑定在任何特定的网络库上因此我定义了一个简单的Transport接口类任何实现了sendData(const std::string)方法的对象都可以作为传输通道。核心是协议层。这是框架的大脑严格遵循 JSON-RPC 2.0 Specification 。它的职责包括解析与验证校验收到的JSON字符串是否符合规范检查必备字段jsonrpc,method,params,id等。请求处理根据method字段在注册的方法表中查找对应的处理函数。参数绑定将JSON格式的params无论是数组形式还是对象形式转换为C函数所需的强类型参数。这是最具挑战性的部分之一。执行与响应调用找到的函数捕获返回值或异常并将其组装成合规的JSON-RPC响应或错误响应。序列化将C的返回值或异常信息序列化为JSON字符串。最上层是服务注册与API层。这一层面向框架使用者提供简洁的接口让他们能够方便地注册自己的类成员函数或普通函数作为RPC方法并启动服务。2.2 关键技术选型与考量1. JSON库为什么选择 nlohmann/jsonC的JSON库选择很多如RapidJSON、JsonCpp等。我最终选择了 nlohmann/json 。原因有三一是其API极其直观支持类似json[key] value的现代语法二是它提供了强大的类型转换能力能自动在JSON类型和C标准类型包括STL容器、自定义类型间转换三是头文件库集成简单无需额外编译链接。这对于我们这样一个旨在轻量、易集成的框架来说是首要优势。2. 网络库保持灵活提供默认实现框架核心不应强制使用任何网络库。但我需要提供一个“开箱即用”的体验。因此我设计了一个基于Boost.Asio的默认HTTP服务器实现作为可选模块。Boost.Asio是异步I/O的业界标准模型成熟稳定避免了从头手写事件循环的复杂性。使用者如果已有其他网络库如libevent、muduo可以轻松替换传输层。3. 方法注册与调用std::function 与模板元编程为了支持注册任意签名的函数我必须使用std::function并结合变参模板。核心思路是将注册的函数包装成一个统一的调用接口std::functionjson(const json)。当调用发生时通过模板元编程技术从JSON数组中提取出对应数量和类型的参数然后调用原始函数。这里需要仔细处理参数类型的推导和转换确保类型安全。4. 错误处理自定义异常体系JSON-RPC规范定义了一套标准的错误码和错误信息。我构建了一个JsonRpcException异常基类并派生出ParseError、InvalidRequest、MethodNotFound、InvalidParams等具体异常。在框架内部捕获所有异常将其转换为规范的JSON-RPC错误响应。这保证了服务端程序的健壮性任何未处理的异常都不会导致服务崩溃而是以错误响应的形式告知客户端。3. 核心模块实现细节3.1 请求与响应对象的封装首先我们需要定义代表JSON-RPC请求和响应的数据结构。这不仅仅是简单的JSON对象还需要包含验证和序列化逻辑。#include nlohmann/json.hpp using json nlohmann::json; class JsonRpcRequest { public: // 解析构造函数 explicit JsonRpcRequest(const json j) { // 1. 验证 jsonrpc 版本 if (j.contains(jsonrpc) j[jsonrpc] 2.0) { jsonrpc j[jsonrpc]; } else { throw ParseError(Invalid or missing jsonrpc field); } // 2. 提取 method if (j.contains(method) j[method].is_string()) { method j[method].getstd::string(); } else { throw InvalidRequest(Missing or invalid method field); } // 3. 提取 params (可选) if (j.contains(params)) { if (j[params].is_array() || j[params].is_object()) { params j[params]; } else { throw InvalidParams(params must be array or object); } } // 4. 提取 id (可选通知请求没有id) if (j.contains(id)) { // id可以是字符串、数字或null我们统一存为json id j[id]; } // 否则 id 保持为 json::value_t::null } bool isNotification() const { return id.is_null(); } std::string jsonrpc; std::string method; json params; json id; // 使用json类型存储以支持字符串、整型等多种形式 }; class JsonRpcResponse { public: static JsonRpcResponse Success(const json id, const json result) { JsonRpcResponse resp; resp.jsonrpc 2.0; resp.result result; resp.id id; return resp; } static JsonRpcResponse Error(const json id, const JsonRpcException e) { JsonRpcResponse resp; resp.jsonrpc 2.0; resp.error { {code, e.code()}, {message, e.message()}, {data, e.data()} // data字段可选 }; resp.id id; return resp; } json toJson() const { json j; j[jsonrpc] jsonrpc; if (error.is_null()) { j[result] result; } else { j[error] error; } j[id] id; return j; } std::string jsonrpc; json result; json error; json id; };注意在JsonRpcRequest的构造函数中执行严格的验证非常重要。早期拦截非法格式的请求可以避免后续处理逻辑出现未定义行为。特别是对params字段必须检查其是否为数组或对象这是规范明确要求的。3.2 方法注册与分发器Dispatcher的实现这是框架的核心。我们需要一个Dispatcher类它内部维护一个从方法名到处理函数的映射表。关键挑战在于处理函数的签名可能是int(int, int)也可能是std::string(const std::vectordouble)千变万化。我的解决方案是使用一个“类型擦除”的包装器将任何函数都包装成统一的std::functionjson(const json)。具体实现需要借助C的模板和std::index_sequence等元编程工具。class Dispatcher { public: templatetypename Func void bind(const std::string method_name, Func func) { // 将函数func包装成一个统一接口的调用器 handlers_[method_name] [func](const json params) - json { return invoke(func, params); }; } // 绑定类成员函数 templatetypename Class, typename... Args void bind(const std::string method_name, Class* obj, json (Class::*mem_func)(Args...)) { handlers_[method_name] [obj, mem_func](const json params) - json { return invokeMember(obj, mem_func, params); }; } JsonRpcResponse handleRequest(const JsonRpcRequest req) { auto it handlers_.find(req.method); if (it handlers_.end()) { throw MethodNotFound(Method req.method not found); } try { json result it-second(req.params); // 调用包装好的函数 if (!req.isNotification()) { return JsonRpcResponse::Success(req.id, result); } // 对于通知请求不返回响应 return JsonRpcResponse(); // 返回一个空的响应对象外部判断是否需要发送 } catch (const JsonRpcException e) { throw; // 重新抛出JSON-RPC标准异常 } catch (const std::exception e) { // 捕获用户函数抛出的其他异常转换为InternalError throw InternalError(e.what()); } catch (...) { throw InternalError(Unknown internal error); } } private: // 关键将普通函数调用适配到json参数 templatetypename Func, size_t... I static auto callFunc(Func func, const json params, std::index_sequenceI...) { // 此函数需要根据Func的返回值类型和参数类型进行特化是元编程的核心 // 简化示意假设params是数组并按顺序提取参数 // 实际实现需要处理params是对象按参数名匹配的情况并做严格的类型转换检查 return func(params[I].gettypename std::tuple_elementI, ArgsTuple::type()...); } templatetypename Func static json invoke(Func func, const json params) { using Traits function_traitsFunc; // 需要一个traits来提取函数签名信息 constexpr size_t arg_count Traits::arity; if (params.is_array() params.size() ! arg_count) { throw InvalidParams(Parameter count mismatch); } // 创建index_sequence并调用 auto result callFunc(func, params, std::make_index_sequencearg_count{}); return json(result); // 依赖nlohmann/json的自动转换 } std::unordered_mapstd::string, std::functionjson(const json) handlers_; };实操心得invoke函数的实现是整个框架最复杂的部分。为了使其健壮我编写了一个function_traits类模板用于在编译期提取函数的返回类型、参数个数、各参数类型。这样我们就能在运行时检查传入的JSON参数数组的大小是否与函数参数个数匹配并能将JSON值准确地转换为对应的C类型。这部分代码模板较多但一旦完成对外提供的bind接口将非常简洁安全。3.3 传输层抽象与HTTP服务器实现为了让框架灵活我定义了一个纯虚的ServerTransport接口。class ServerTransport { public: virtual ~ServerTransport() default; virtual void start() 0; virtual void stop() 0; // 核心当收到数据时调用此回调 using RequestHandler std::functionstd::string(const std::string); virtual void setRequestHandler(RequestHandler handler) 0; };然后基于Boost.Asio实现一个具体的HttpServerTransport。class HttpServerTransport : public ServerTransport { public: HttpServerTransport(const std::string address, uint16_t port) : io_context_(), acceptor_(io_context_), request_handler_(nullptr) { tcp::endpoint endpoint(asio::ip::make_address(address), port); acceptor_.open(endpoint.protocol()); acceptor_.set_option(tcp::acceptor::reuse_address(true)); acceptor_.bind(endpoint); acceptor_.listen(); } void setRequestHandler(RequestHandler handler) override { request_handler_ std::move(handler); } void start() override { doAccept(); io_context_.run(); } void stop() override { io_context_.stop(); } private: void doAccept() { acceptor_.async_accept([this](std::error_code ec, tcp::socket socket) { if (!ec) { // 为每个连接创建一个会话 std::make_sharedHttpSession(std::move(socket), request_handler_)-start(); } doAccept(); // 继续接受新连接 }); } asio::io_context io_context_; tcp::acceptor acceptor_; RequestHandler request_handler_; };HttpSession类负责处理单个HTTP连接的生命周期读取请求、解析HTTP头、提取JSON-RPC请求体、交给RequestHandler处理、然后写回HTTP响应。注意事项在生产环境中io_context::run()会阻塞当前线程。通常我们需要一个线程池来运行多个io_context或者使用一个io_context配合线程池asio::thread_pool来并发处理连接以避免单个线程成为性能瓶颈。在我们的示例实现中为了简洁先使用单线程模型。4. 框架集成与使用示例将上述模块组合起来形成一个易于使用的JsonRpcServer类。class JsonRpcServer { public: JsonRpcServer(std::unique_ptrServerTransport transport) : transport_(std::move(transport)) { // 将框架的请求处理逻辑绑定到传输层 transport_-setRequestHandler([this](const std::string request_data) { return handleRawRequest(request_data); }); } templatetypename Func void bind(const std::string method_name, Func func) { dispatcher_.bind(method_name, func); } void start() { transport_-start(); } private: std::string handleRawRequest(const std::string request_data) { try { json j json::parse(request_data); JsonRpcRequest req(j); auto resp dispatcher_.handleRequest(req); if (!resp.id.is_null()) { // 如果不是通知请求则返回响应 return resp.toJson().dump(); // 序列化为字符串 } return ; // 通知请求返回空字符串HTTP层应返回204 No Content } catch (const JsonRpcException e) { // 即使请求解析失败如果请求有id也需要返回错误响应 json error_id json::value_t::null; // 这里需要尝试从原始json中提取id略复杂代码省略 JsonRpcResponse error_resp JsonRpcResponse::Error(error_id, e); return error_resp.toJson().dump(); } catch (const json::exception e) { // JSON解析失败属于ParseError ParseError parse_err(e.what()); JsonRpcResponse error_resp JsonRpcResponse::Error(json::value_t::null, parse_err); return error_resp.toJson().dump(); } } Dispatcher dispatcher_; std::unique_ptrServerTransport transport_; };现在我们可以像下面这样使用这个框架// 1. 定义一些RPC函数 json add(const json params) { // params 预期是数组 [a, b] int a params[0].getint(); int b params[1].getint(); return a b; } json getUserInfo(const json params) { // params 预期是对象 {user_id: 123} int user_id params[user_id].getint(); // ... 查询数据库 return {{id, user_id}, {name, Alice}, {email, aliceexample.com}}; } // 2. 创建并配置服务器 int main() { auto transport std::make_uniqueHttpServerTransport(0.0.0.0, 8080); JsonRpcServer server(std::move(transport)); // 3. 绑定方法 server.bind(add, add); server.bind(get_user_info, getUserInfo); // 4. 也可以绑定lambda server.bind(echo, [](const json params) - json { return params; // 原样返回参数 }); std::cout JSON-RPC server starting on port 8080...\n; server.start(); // 阻塞直到服务停止 return 0; }客户端可以使用任何HTTP客户端如curl或JSON-RPC客户端库进行调用# 调用 add 方法 curl -X POST http://localhost:8080/ \ -H Content-Type: application/json \ -d {jsonrpc: 2.0, method: add, params: [5, 3], id: 1} # 响应{jsonrpc: 2.0, result: 8, id: 1} # 调用 get_user_info 方法参数为对象 curl -X POST http://localhost:8080/ \ -H Content-Type: application/json \ -d {jsonrpc: 2.0, method: get_user_info, params: {user_id: 123}, id: 2} # 调用通知没有id字段 curl -X POST http://localhost:8080/ \ -H Content-Type: application/json \ -d {jsonrpc: 2.0, method: log_message, params: [Server started]}5. 高级特性实现与优化一个基础的框架已经完成但要投入实际生产还需要考虑更多。5.1 批量请求Batch Request支持JSON-RPC 2.0支持批量请求即一个HTTP请求体内包含多个JSON-RPC请求对象数组。服务器需要按顺序处理每个请求并将所有响应通知请求除外组成数组返回。实现思路是在handleRawRequest中首先判断解析出的JSON是对象还是数组。如果是数组则遍历其中每个元素分别处理每个请求收集非通知请求的响应最后将响应数组序列化返回。这里需要注意批量请求中的某个请求解析失败不应影响其他请求的处理。5.2 参数类型安全与自动转换增强目前的invoke函数是一个简化示意。一个工业级的实现需要处理更多细节参数模式判断根据params是数组还是对象决定是按位置绑定还是按名称绑定。更精确的类型转换不仅支持基本类型和STL容器还应支持自定义类型的from_json/to_json方法nlohmann/json支持这个。默认参数支持C函数可以有默认参数在JSON参数缺失时应能使用默认值。参数验证在调用函数前可以集成如JSON Schema的验证确保传入参数符合业务规则。5.3 中间件Middleware或钩子Hooks机制为了提供更好的扩展性可以引入中间件机制。例如在请求被分发器处理前后允许用户插入自定义逻辑认证/授权检查请求头中的Token。日志记录记录每个请求的方法、参数、耗时和结果。限流限制某个客户端或某个方法的调用频率。指标收集统计方法调用次数、成功率等。可以在Dispatcher::handleRequest前后预留出接口允许用户注册一系列可调用的钩子函数形成一个处理管道。5.4 异步方法支持目前我们的框架是同步的即处理函数必须立即返回结果。对于需要长时间运行的操作如文件I/O、数据库复杂查询这会阻塞工作线程。我们可以利用C的std::future或回调函数来支持异步RPC方法。一种设计是允许绑定返回std::futurejson的函数。在Dispatcher中如果检测到返回值是future则将其提交到线程池中执行并立即返回一个表示“处理中”的响应或者使用长连接等待。更现代的做法是集成协程C20的coroutine但这会大幅增加框架的复杂度。6. 常见问题、调试技巧与性能考量在实际开发和测试中我遇到了不少典型问题。6.1 编译与链接问题问题使用nlohmann/json时如果多个编译单元包含其头文件在开启某些优化选项时可能导致链接错误如multiple definition。解决确保项目统一使用#include nlohmann/json.hpp并且最好在单独的.cpp文件中定义json的全局别名其他地方包含这个.cpp文件的头文件。或者直接使用single_include版本的头文件。问题Boost.Asio的编译依赖。Boost库体积较大。解决对于轻量级使用可以考虑使用Asio的独立版本asio库不依赖Boost。或者将网络传输层实现完全剥离为可选模块让用户自行提供传输实现。6.2 运行时问题排查表现象可能原因排查步骤客户端收到ParseError1. 请求JSON格式错误。2. 请求体编码不是UTF-8。3. HTTP头Content-Type不是application/json。1. 用在线JSON校验工具检查请求体。2. 使用curl -v查看原始请求。3. 在服务器端打印接收到的原始字符串确认无误。收到MethodNotFound1. 方法名拼写错误。2. 方法未成功绑定到分发器。3. 服务器重启后未重新绑定。1. 检查客户端调用方法名与服务器绑定名是否完全一致大小写敏感。2. 在服务器启动后打印Dispatcher内部的方法名列表进行确认。收到InvalidParams1.params类型错误不是数组或对象。2. 参数个数不匹配。3. 参数类型无法转换如JSON字符串传给C int。1. 检查客户端发送的params结构。2. 在服务器端的invoke函数中添加详细日志打印期望的参数类型和实际收到的JSON值。服务器无响应或连接被重置1. 服务器进程崩溃。2. 处理函数中抛出未捕获的异常。3. 网络防火墙或策略限制。1. 检查服务器日志是否有崩溃记录。2. 确保所有用户函数异常都被框架的try...catch块捕获。3. 使用telnet或nc测试端口连通性。性能低下请求延迟高1. 单线程模型处理慢。2. 某个RPC方法本身是计算密集型或阻塞式I/O。3. JSON序列化/反序列化成为瓶颈。1. 实现多线程或线程池模型。2. 对耗时方法进行性能剖析考虑异步化或优化算法。3. 对于简单参数可尝试更快的JSON库如RapidJSON但这会牺牲易用性。6.3 性能优化点连接管理与线程模型使用asio::thread_pool实现固定大小的线程池每个连接在其整个生命周期内可能被分配到不同的线程处理但单个请求的处理是同步的。对于更高并发可以考虑每个连接一个协程的模型C20。JSON处理优化nlohmann/json的易用性牺牲了一些性能。在性能关键路径上可以考虑复用json对象避免在每次请求处理中创建大量临时json对象。使用静态json对于固定的错误响应模板可以预先构造静态的json对象。探索其他库在性能要求极高的场景可将核心协议层与RapidJSON集成但会提高代码复杂度。内存分配频繁的字符串和容器创建会导致内存碎片。可以考虑使用内存池或自定义分配器特别是在处理大量小请求时。6.4 安全性考量输入验证框架已经做了基础的协议合规性验证。但业务层必须对参数内容进行二次验证防止注入攻击如SQL注入、命令注入。资源限制应限制单个请求体的最大尺寸防止内存耗尽攻击DoS。在HTTP服务器层就可以实现。认证与授权务必通过中间件机制实现强身份认证如JWT和方法级授权切勿相信未经验证的请求。传输安全如果通过公网暴露必须使用HTTPSWSS for WebSocket来加密通信。这可以在反向代理如Nginx或传输层实现。从零实现一个JSON-RPC框架是一个将网络协议、C现代特性、软件设计模式融会贯通的绝佳练习。它强迫你去思考接口设计如何才优雅、错误处理如何才健壮、性能瓶颈可能在哪里。最终得到的不仅仅是一个工具更是一套适用于构建各种服务间通信组件的思维模式。当你再使用其他RPC框架时你会更清楚它背后做了什么以及如何更好地利用它。