C++ JSON-RPC框架libjson-rpc-cpp实战：从原理到异构系统集成

1. 项目概述：为什么你需要关注libjson-rpc-cpp？

如果你正在用C++开发分布式系统、微服务，或者需要让一个C++进程和前端、移动端、甚至是另一个用不同语言写的服务进行通信，那么“远程过程调用”这个概念你一定不陌生。简单说，就是让一个程序能像调用本地函数一样，去调用网络上另一台机器上的函数。JSON-RPC就是实现这个目标的一种轻量级、基于JSON的协议。而libjson-rpc-cpp，就是一个帮你快速在C++项目中落地JSON-RPC的成熟框架。

我最早接触这个框架是在一个工业控制的项目里，我们需要把底层的C++数据采集服务暴露给一个用Python写的数据分析平台。当时评估了gRPC、Thrift等方案，但考虑到协议简单、调试方便（直接看JSON）、以及C++端的轻量级需求，最终选择了libjson-rpc-cpp。几年用下来，它在中小规模的RPC场景里，尤其是在异构系统集成时，表现非常稳定和高效。

这个框架的核心价值在于“省心”。它帮你处理了协议解析、网络通信、序列化/反序列化这些繁琐的底层细节，你只需要像写本地类一样定义好接口，然后用它提供的工具生成客户端和服务端的桩代码，就能快速搭建起通信桥梁。对于C++开发者来说，这意味着你可以把精力集中在业务逻辑上，而不是去反复造轮子处理JSON格式校验或者TCP粘包问题。

2. 核心设计思路与架构拆解

2.1 JSON-RPC协议简析：框架的基石

要理解libjson-rpc-cpp，先得明白它实现的协议。JSON-RPC 2.0是一个非常简洁的规范。一次典型的请求看起来像这样：

{ "jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 3 }

对应的成功响应则是：

{ "jsonrpc": "2.0", "result": 19, "id": 3 }

框架的核心工作，就是自动帮你把这样的JSON结构和你C++中的函数调用对应起来。它内部做了几件关键事：第一，验证传入的JSON是否符合协议规范；第二，根据method字段找到你注册的对应C++方法；第三，将params中的JSON值反序列化成C++函数参数；第四，执行你的函数；第五，将返回值序列化成JSON格式的result；最后，通过网络把响应发回去。整个过程对开发者几乎是透明的。

2.2 框架的模块化架构：可插拔的通信层

libjson-rpc-cpp采用了一种清晰的分层架构，这是它易于使用和扩展的关键。

1. 核心层（libjsonrpccpp-common）：这一层是协议实现的核心，与具体的网络传输方式无关。它定义了Procedure（代表一个远程方法）、Handler（处理请求）等抽象，并负责JSON-RPC报文的解析、验证、构建和分发。无论你底层用HTTP还是TCP，上层的业务逻辑处理都是复用这一套。

2. 服务端抽象与实现（libjsonrpccpp-server）：这一层提供了服务端的基类AbstractServer和具体的服务器实现。它的巧妙之处在于将“协议处理”与“网络监听”解耦。你继承生成的抽象桩类，实现业务逻辑，这部分只关心协议。而网络监听部分，框架提供了多种“连接器”：

• HttpServer：基于libmicrohttpd，提供HTTP/HTTPS服务。这是最常用的方式，因为HTTP穿透性好，容易被各种客户端（包括浏览器）调用。
• TcpSocketServer：基于原生TCP Socket。性能更高，延迟更低，适合内部服务间的高频通信，但需要自己处理连接管理。
• UnixDomainSocketServer：基于Unix域套接字。用于同一台机器上的进程间通信，速度最快，完全绕过了网络协议栈。
• FileDescriptorServer：基于文件描述符。这是一个更通用的接口，可以适配任何能提供文件描述符的通信机制，比如管道或自定义的IPC。

这种设计让你可以根据场景灵活选择。比如，对公网暴露用HttpServer，内部微服务集群用TcpSocketServer，而同一主机上的插件系统通信则用UnixDomainSocketServer。

3. 客户端抽象与实现（libjsonrpccpp-client）：与服务端对应，客户端也抽象出了Client基类和多种连接器实现（HttpClient，TcpSocketClient等）。生成的客户端桩类会继承自这个Client，并将你的本地方法调用，转换为对相应连接器的调用，最终发出JSON-RPC请求。

4. 桩代码生成器（jsonrpcstub）：这是框架的“生产力工具”。你不需要手动编写序列化/反序列化代码，只需要在一个JSON文件里描述你的接口（方法名、参数、返回值类型），运行这个工具，它就会自动生成服务端的抽象类和客户端的具体类。生成的客户端类让你像调用本地对象一样进行远程调用，极大地减少了样板代码和出错的可能。

2.3 与同类框架的对比选型思考

为什么选它而不是gRPC或Thrift？这取决于你的具体场景。

• vs gRPC：gRPC功能强大，基于HTTP/2和Protocol Buffers，支持流、双向通信、认证等高级特性，适合大型、复杂的微服务架构。但它的依赖更重，协议是二进制的，调试时不如JSON直观。如果你的需求是简单的请求-响应，且希望接口对人类友好、易于用脚本测试，libjson-rpc-cpp更轻快。
• vs Thrift：Thrift也是一个成熟的RPC框架，支持多种语言和传输协议。它和gRPC类似，有自己的接口定义语言（IDL）和二进制编码。libjson-rpc-cpp的优势在于其协议（JSON-RPC）是标准化的，而不是Apache Thrift自定义的。这意味着你的服务可以更容易地被任何实现了JSON-RPC标准的客户端调用，无论它用什么语言写成。
• vs 手写RESTful API：用HTTP+JSON自己实现一套CRUD接口当然可以。但JSON-RPC提供了更严格的规范（比如请求ID匹配、错误对象标准化），并且libjson-rpc-cpp帮你自动完成了函数映射，避免了你在每个接口里手动解析json::Value的重复劳动。

个人心得：我的选择标准通常是，如果项目是纯粹的C++内部服务集群，且追求极致性能，可能会考虑更二进制的方案。但只要涉及到需要与前端（JavaScript）、脚本语言（Python）或其他异构系统交互，JSON-RPC的通用性和libjson-rpc-cpp的便捷性优势就非常明显。它的学习曲线平缓，能让团队快速上手。

3. 从零开始：环境搭建与项目初始化

3.1 系统依赖安装与编译选项详解

框架的编译依赖CMake，以及几个可选的库。在Ubuntu/Debian系统上，一条命令就能安装主要依赖和开发工具：

sudo apt-get update sudo apt-get install libjsonrpccpp-dev libjsonrpccpp-tools libjsoncpp-dev libmicrohttpd-dev libcurl4-openssl-dev cmake build-essential

这里libjsonrpccpp-dev是核心库，libjsonrpccpp-tools包含了关键的jsonrpcstub生成器。其他库是通信层依赖：libjsoncpp用于JSON处理，libmicrohttpd用于HTTP服务器，libcurl用于HTTP客户端。

如果你从源码编译，以获得最大的定制灵活性，步骤如下：

git clone https://github.com/cinemast/libjson-rpc-cpp.git cd libjson-rpc-cpp mkdir build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release make -j$(nproc) sudo make install sudo ldconfig # Linux系统需要，用于更新动态库链接缓存

重点在于CMake的编译选项，它们让你可以按需裁剪功能，减少不必要的依赖：

• -DCOMPILE_STUBGEN=NO：如果你只需要运行时库，不需要生成桩代码的工具，可以关闭。
• -DHTTP_SERVER=NO/-DHTTP_CLIENT=NO：如果你的应用只做客户端或服务端，或者打算使用其他传输方式（如TCP），可以禁用HTTP支持，从而移除对libmicrohttpd或libcurl的依赖。
• -DTCP_SOCKET_SERVER=YES/-DTCP_SOCKET_CLIENT=YES：默认不编译TCP支持，如果你需要，必须显式开启。
• -DUNIX_DOMAIN_SOCKET_SERVER=YES：开启Unix域套接字服务器支持，用于进程间通信。
• -DREDIS_SERVER=YES：这是一个实验性功能，允许通过Redis Pub/Sub作为传输层，用于特定的消息队列场景。

踩坑记录：在嵌入式环境或追求最小化部署时，务必使用这些选项进行裁剪。我曾在一个资源受限的设备上，因为默认编译包含了所有功能，导致可执行文件体积大了好几兆。后来通过-DHTTP_SERVER=NO -DCOMPILE_EXAMPLES=NO -DCOMPILE_TESTS=NO进行精简，效果立竿见影。

3.2 创建你的第一个JSON-RPC服务：规范文件定义

一切从定义接口开始。我们创建一个名为calculator.json的规范文件：

[ { "name": "add", "params": {"a": 0, "b": 0}, "returns": 0, "description": "Add two numbers" }, { "name": "subtract", "params": {"minuend": 0, "subtrahend": 0}, "returns": 0 }, { "name": "notifyStatus", "params": {"message": ""}, "notification": true } ]

这个文件定义了三个远程方法：

1. add：接收两个数字参数a和b，返回一个数字。description字段是可选的，会体现在生成的代码注释中。
2. subtract：同样接收两个数字，返回一个数字。注意参数名可以任意定义，只要类型是数字。
3. notifyStatus：这是一个“通知”。JSON-RPC 2.0中，通知是没有id字段的请求，服务端执行后不返回任何响应。这里我们设置"notification": true，并且它有一个字符串参数message。

关键点解析：params和returns字段的值，不仅定义了参数名，更重要的是定义了类型。框架通过这个初始值来推断类型：

• 0->int(或double， 取决于C++端的实现映射，通常是Json::Value，可容纳多种数字类型)
• ""->std::string
• []->Json::Value(数组类型)
• {}->Json::Value(对象类型)
• false->bool

这种类型推断虽然方便，但不够精确。对于复杂对象，你可能需要更细致的控制，这时可以查阅框架文档使用更高级的规范语法。

3.3 使用桩代码生成器：自动化接口绑定

有了规范文件，下一步就是生成C++桩代码。这是框架最实用的功能之一：

jsonrpcstub calculator.json --cpp-server=AbstractCalculatorServer --cpp-client=CalculatorClient

这条命令会生成两个文件：

• abstractcalculatorserver.h：服务端抽象基类。里面为add和subtract定义了纯虚函数，你需要继承这个类并实现它们。对于notifyStatus这个通知，它会生成一个空的虚拟函数，你可以选择重写。
• calculatorclient.h：客户端具体类。它已经实现了add,subtract,notifyStatus等方法，你直接实例化这个类就可以调用远程服务。

实操技巧：我习惯将生成的代码放在一个单独的目录，比如./generated，并在CMakeLists.txt中将其包含到头文件搜索路径中。这样可以将接口定义（JSON文件）和生成的代码与业务逻辑代码清晰分离，也便于版本管理。记住，生成的桩代码不要手动修改，因为每次修改接口规范后都需要重新生成。所有自定义逻辑都应该写在你的实现类里。

4. 服务端深度实现与高级配置

4.1 继承与实现：编写业务逻辑

现在，我们创建服务端实现文件calculator_server.cpp：

#include <jsonrpccpp/server.h> #include <jsonrpccpp/server/connectors/httpserver.h> #include "generated/abstractcalculatorserver.h" // 引入生成的抽象类 #include <iostream> using namespace jsonrpc; using namespace std; class ConcreteCalculatorServer : public AbstractCalculatorServer { public: ConcreteCalculatorServer(AbstractServerConnector &connector) : AbstractCalculatorServer(connector) {} // 实现纯虚函数 add virtual int add(int a, int b) override { int result = a + b; cout << "[Server] Received add(" << a << ", " << b << ") -> " << result << endl; return result; } // 实现纯虚函数 subtract virtual int subtract(int minuend, int subtrahend) override { int result = minuend - subtrahend; cout << "[Server] Received subtract(" << minuend << ", " << subtrahend << ") -> " << result << endl; return result; } // 重写通知处理函数（非纯虚，可选） virtual void notifyStatus(const std::string &message) override { cout << "[Server] Received notification: " << message << endl; // 通知没有返回值 } }; int main() { // 1. 创建一个HTTP服务器连接器，监听8080端口 HttpServer httpserver(8080); // 2. 创建我们的服务实例，并绑定连接器 ConcreteCalculatorServer server(httpserver); // 3. 启动服务器，开始监听请求 cout << "Calculator JSON-RPC server started on port 8080..." << endl; if (server.StartListening()) { cout << "Server listening successfully. Press Enter to stop." << endl; getchar(); // 等待输入，阻塞主线程 server.StopListening(); } else { cerr << "Failed to start server on port 8080." << endl; return 1; } return 0; }

编译这个服务端：

g++ -std=c++11 calculator_server.cpp -ljsoncpp -lmicrohttpd -ljsonrpccpp-common -ljsonrpccpp-server -o calculator_server

关键点解析：

1. 继承与构造函数：你的具体服务器类必须继承自生成的抽象类，并在构造函数中调用父类构造函数，传入连接器引用。这个连接器对象（此处是HttpServer）的生命周期必须长于服务器对象，通常直接在main函数栈上创建即可。
2. 方法实现：add和subtract的参数和返回值类型与规范文件中定义的类型严格对应。框架在底层会将JSON值转换为对应的C++类型。如果客户端传递的参数类型不匹配，框架会自动返回一个标准的JSON-RPC错误响应（Invalid params）。
3. 通知处理：对于通知，实现函数返回类型是void。即使你什么都不做，也最好像上面一样重写一下，以便记录日志或触发其他操作。
4. 启动与停止：StartListening()是一个非阻塞调用，它会启动一个后台线程来处理连接。所以我们需要用getchar()或一个循环来阻止主线程退出。在生产环境中，你可能会用信号量或条件变量来控制服务器生命周期。

4.2 探索不同的服务器连接器

除了HTTP，框架还支持其他连接器，适用于不同场景。

TCP Socket 服务器：

#include <jsonrpccpp/server/connectors/tcpsocketserver.h> // ... TcpSocketServer tcpserver("127.0.0.1", 9000); ConcreteCalculatorServer server(tcpserver);

TCP方式性能更好，但没有HTTP的通用性。它使用自定义的简单帧协议（通常是长度前缀+数据），适合内部高性能服务通信。

Unix域套接字服务器（同一主机进程间通信，最快）：

#include <jsonrpccpp/server/connectors/unixdomainsocketserver.h> // ... UnixDomainSocketServer unixserver("/tmp/calculator.socket"); ConcreteCalculatorServer server(unixserver);

使用前需要确保有权限在指定路径创建socket文件。通信结束后，这个文件不会自动删除，需要手动清理。

性能对比心得：在我的基准测试中，对于小数据量的请求，Unix域套接字的延迟大约是TCP本地回环的1/3，是HTTP的1/10。如果你的客户端和服务端部署在同一台物理机上，且对延迟极其敏感（比如高频交易系统内部的组件通信），Unix域套接字是绝佳选择。但它的缺点是无法跨机器。

4.3 高级服务端特性：错误处理与自定义绑定

自定义错误码与错误信息： JSON-RPC协议定义了标准的错误对象。你可以在服务端方法中抛出jsonrpc::JsonRpcException异常来返回错误。

virtual int divide(int a, int b) override { if (b == 0) { throw JsonRpcException(ERROR_SERVER_PROCEDURE_IS_METHOD, "Division by zero is not allowed."); } return a / b; }

ERROR_SERVER_PROCEDURE_IS_METHOD是框架预定义的错误码（对应JSON-RPC的-32602）。你也可以使用自定义错误码（范围是-32099到-32000，供服务器应用定义使用）。

绑定非成员函数或现有类方法： 有时，你不想让RPC服务器类继承自生成的抽象类，而是希望将RPC方法绑定到已有的业务逻辑类上。这可以通过Method和Notification类手动绑定实现。

class BusinessLogic { public: int compute(int x) { return x * 2; } }; int main() { HttpServer connector(8080); JsonRpcServer server(connector); // 使用通用的JsonRpcServer，而非生成的类 BusinessLogic logic; server.AddMethod(new Procedure("compute", PARAMS_BY_NAME, JSON_INTEGER, "x", JSON_INTEGER, NULL), &logic, &BusinessLogic::compute); // 参数解释：方法名，参数传递方式，返回类型，参数1名，参数1类型，...，对象指针，成员函数指针 server.StartListening(); // ... }

这种方式更灵活，但需要手动管理参数类型映射，不如桩代码生成器方便和安全。

5. 客户端开发实战与最佳实践

5.1 使用生成的客户端桩类

客户端的使用直观得多。创建calculator_client.cpp：

#include <iostream> #include "generated/calculatorclient.h" #include <jsonrpccpp/client/connectors/httpclient.h> using namespace jsonrpc; using namespace std; int main() { // 1. 创建一个HTTP客户端连接器，指向服务端地址 HttpClient httpclient("http://localhost:8080"); // 2. 使用生成的客户端类 CalculatorClient client(httpclient); try { // 3. 像调用本地对象一样进行远程调用 int sum = client.add(5, 3); cout << "5 + 3 = " << sum << endl; int difference = client.subtract(10, 4); cout << "10 - 4 = " << difference << endl; // 4. 发送一个通知（不期待响应） client.notifyStatus("Client is shutting down."); cout << "Notification sent." << endl; } catch (const JsonRpcException &e) { cerr << "JSON-RPC Error: " << e.what() << endl; cerr << "Error code: " << e.GetCode() << endl; cerr << "Error data: " << e.GetData() << endl; } catch (const exception &e) { cerr << "Standard Exception: " << e.what() << endl; } return 0; }

编译客户端：

g++ -std=c++11 calculator_client.cpp -ljsoncpp -lcurl -ljsonrpccpp-common -ljsonrpccpp-client -o calculator_client

运行客户端前，确保服务端calculator_server已经在运行。你会看到客户端输出计算结果，服务端控制台输出接收到的请求日志。

关键点解析：

1. 连接器配置：客户端也需要一个连接器（HttpClient），其构造参数是服务端的URL。
2. 异常处理：务必将远程调用包裹在try-catch块中。网络超时、连接拒绝、服务端返回错误（如除零错误）都会抛出JsonRpcException。这是与本地调用最大的区别，必须进行健壮的错误处理。
3. 同步调用：上面展示的是同步调用，客户端会阻塞直到收到响应或超时。框架也支持异步调用，但需要更复杂的回调机制。

5.2 客户端连接器选型与配置

与服务器端类似，客户端也支持多种连接器。

TCP Socket 客户端：

#include <jsonrpccpp/client/connectors/tcpsocketclient.h> TcpSocketClient tcpclient("127.0.0.1", 9000); CalculatorClient client(tcpclient);

需要确保和服务端使用同一种连接器类型（TCP对TCP）。

连接超时与配置： 对于HttpClient，你可以通过其底层使用的libcurl进行更细粒度的配置，但这通常需要修改框架源码或使用更高级的初始化方式。一个常见的需求是设置超时。默认的超时可能不适合你的网络环境。如果遇到超时问题，可能需要深入研究HttpClient的构造函数或寻找设置CURL选项的方法。

避坑指南：在生产环境中，客户端的超时、重试和连接池管理是必须考虑的。libjson-rpc-cpp的客户端比较基础，它没有内置的重试机制。如果你的网络不稳定，需要在业务逻辑层或使用一个包装类来实现重试逻辑。例如，捕获超时异常（JsonRpcException中可能包含网络错误码），等待一段时间后重试，并设置最大重试次数。

5.3 处理复杂数据类型与自定义结构

前面的例子只用了基本类型。实际应用中，参数和返回值常常是复杂对象或数组。

在规范文件中定义对象：

[ { "name": "getUserInfo", "params": {"userId": 0}, "returns": { "name": "", "age": 0, "email": "" } }, { "name": "batchProcess", "params": {"items": []}, "returns": [] } ]

对于getUserInfo，返回值是一个对象。对于batchProcess，参数和返回值都是数组。

在C++端的处理： 框架会将复杂的JSON对象或数组映射为Json::Value类型（来自jsoncpp库）。在你的实现函数中，你需要手动解析这个Json::Value。

#include <json/json.h> // jsoncpp 头文件 virtual Json::Value getUserInfo(int userId) override { Json::Value result; result["name"] = "Alice"; result["age"] = 30; result["email"] = "alice@example.com"; // 可以从数据库或其他服务获取真实数据 return result; // 自动被序列化为JSON对象 } virtual Json::Value batchProcess(const Json::Value &items) override { Json::Value results(Json::arrayValue); // 创建一个JSON数组 for (const auto &item : items) { // 处理每个item... Json::Value processed; processed["id"] = item["id"]; processed["status"] = "done"; results.append(processed); } return results; }

这种方式给了你最大的灵活性，但也带来了更多的手动解析工作。你需要熟悉jsoncpp库的API来操作Json::Value。

更优雅的方案：使用自定义类型与转换器（高级）： 你可以通过特化框架内部的模板，实现自定义C++结构体与Json::Value的自动转换。但这需要深入框架内部，并编写额外的模板代码，复杂度较高。对于大多数项目，直接使用Json::Value并在业务层进行转换是更务实的选择。

6. 常见问题排查与性能调优实录

6.1 编译与链接问题速查表

6.2 运行时错误与调试技巧

1. 连接被拒绝 (Connection refused)

• 检查服务端是否运行：netstat -tlnp | grep :8080
• 检查防火墙：确保服务端口（如8080）对客户端开放。
• 检查地址和端口：客户端连接字符串是否正确。

2. 收到Method not found(-32601) 错误

• 检查方法名拼写：JSON-RPC区分大小写，客户端调用的method必须与规范文件中定义的name完全一致。
• 检查服务端是否注册了该方法：如果你使用手动绑定（AddMethod），确认绑定成功。如果使用生成的桩类，确认你实例化的是正确的具体类。
• 检查规范文件：重新生成桩代码，并确保服务端和客户端使用的是同一版本的规范文件生成的代码。这是最常见的原因。

3. 收到Invalid params(-32602) 错误

• 检查参数数量和名称：如果规范中定义的是PARAMS_BY_NAME（按名称），则客户端JSON中的参数名必须匹配。如果是PARAMS_BY_POSITION（按位置），则顺序必须正确。桩代码生成器默认使用PARAMS_BY_NAME。
• 检查参数类型：客户端传递的JSON参数类型必须与规范中推断的类型兼容。例如，规范中定义"params": {"a": 0}，期望是数字，如果你传了字符串"a":"hello"，就会出错。

4. 服务端无响应或客户端超时

• 检查服务端日志：服务端可能在处理请求时崩溃或陷入死循环。在服务端方法实现中加入日志，观察请求是否到达。
• 使用网络调试工具：用curl直接发送原始JSON-RPC请求来测试服务端，排除客户端代码问题。

curl -X POST http://localhost:8080 -H "Content-Type: application/json" -d '{"jsonrpc":"2.0", "method":"add", "params":{"a":5, "b":3}, "id":1}'

• 调整超时设置：如前所述，可能需要修改客户端底层（如libcurl）的超时设置。

6.3 性能调优要点

1. 选择合适的连接器

• 内部高频调用：优先选择TcpSocketServer/TcpSocketClient或UnixDomainSocketServer。
• 对公网或需要通用性：使用HttpServer/HttpClient。
• 单机进程间通信：UnixDomainSocketServer性能最佳。

2. 服务端并发处理HttpServer基于libmicrohttpd，默认使用线程池处理并发请求。你可以通过libmicrohttpd的选项来调整线程池大小，但这需要修改libjson-rpc-cpp的源码或构造参数。对于TcpSocketServer，它使用的是简单的每连接一线程模型，在高并发下需要注意线程资源。

3. JSON序列化开销JSON是文本格式，序列化和反序列化（尤其是复杂、嵌套深的对象）是性能瓶颈。如果经过 profiling 发现此处是热点，可以考虑：

• 压缩传输：在HTTP层启用gzip压缩（需配置Web服务器或客户端）。
• 优化数据结构：尽量减少嵌套层级，使用更扁平的数据结构。
• 评估替代方案：如果JSON处理真的成为瓶颈，说明你的场景可能更需要像Protocol Buffers或MessagePack这样的二进制协议，这时应该重新评估是否选用libjson-rpc-cpp。

4. 连接复用对于HTTP客户端，确保HttpClient对象是长生命周期的，并被复用。反复创建和销毁连接器对象会带来不小的TCP连接开销。理想情况下，客户端对象应该作为单例或通过连接池管理。

在我经历的一个数据采集服务项目中，最初每个数据点上报都创建一个新的客户端，导致大量TIME_WAIT连接，很快耗尽了端口。改为全局共享一个客户端实例后，性能提升了数十倍。这个教训非常深刻：在RPC客户端中，连接器是昂贵的资源，必须复用。

7. 项目集成与生产环境考量

7.1 在CMake项目中集成

将libjson-rpc-cpp集成到现代CMake项目中是最佳实践。

cmake_minimum_required(VERSION 3.10) project(MyJsonRpcService) # 查找依赖包 find_package(jsonrpccpp REQUIRED) find_package(JsonCpp REQUIRED) # 如果需要直接操作Json::Value # 生成桩代码 find_program(JSONRPCSTUB_EXECUTABLE jsonrpcstub) if(NOT JSONRPCSTUB_EXECUTABLE) message(FATAL_ERROR "jsonrpcstub not found!") endif() set(SPEC_FILE ${CMAKE_CURRENT_SOURCE_DIR}/spec/calculator.json) set(GENERATED_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated) file(MAKE_DIRECTORY ${GENERATED_DIR}) add_custom_command( OUTPUT ${GENERATED_DIR}/abstractcalculatorserver.h ${GENERATED_DIR}/calculatorclient.h COMMAND ${JSONRPCSTUB_EXECUTABLE} ${SPEC_FILE} --cpp-server=AbstractCalculatorServer --cpp-client=CalculatorClient COMMAND ${CMAKE_COMMAND} -E rename abstractcalculatorserver.h ${GENERATED_DIR}/abstractcalculatorserver.h COMMAND ${CMAKE_COMMAND} -E rename calculatorclient.h ${GENERATED_DIR}/calculatorclient.h DEPENDS ${SPEC_FILE} COMMENT "Generating JSON-RPC stubs" ) # 定义服务器可执行文件 add_executable(my_server src/server/main.cpp src/server/calculator_impl.cpp ${GENERATED_DIR}/abstractcalculatorserver.h ) target_include_directories(my_server PRIVATE ${GENERATED_DIR}) target_link_libraries(my_server PRIVATE jsonrpccpp::server JsonCpp::JsonCpp) # 定义客户端可执行文件或库 add_executable(my_client src/client/main.cpp ${GENERATED_DIR}/calculatorclient.h ) target_include_directories(my_client PRIVATE ${GENERATED_DIR}) target_link_libraries(my_client PRIVATE jsonrpccpp::client)

这样，每次修改calculator.json规范文件后，重新运行CMake构建，桩代码会自动重新生成，确保接口同步。

7.2 日志、监控与安全性

日志记录：框架本身提供的日志信息有限。你必须在服务端的方法实现和客户端调用处，加入详细的日志记录（比如使用spdlog或glog）。记录入参、出参、耗时、异常信息，这对于调试和运维至关重要。

监控指标：考虑集成监控系统（如Prometheus）。可以在服务端包装一层，在每次RPC调用前后记录：调用次数、成功/失败次数、耗时分布（直方图）。这能帮你及时发现性能退化或异常方法。

安全性考虑：

1. 认证与授权：基础的HTTP服务器不支持内置的认证。如果需要，可以考虑：
   • 在HTTP层之上使用反向代理（如Nginx）进行Basic Auth或Token验证。
   • 修改服务端代码，在处理请求前，从HTTP头中解析并验证Token。
   • 使用更复杂的方案，如集成liboauth等。
2. 输入验证：框架会做基本的JSON-RPC协议和参数类型验证，但业务层面的验证（如参数范围、字符串格式）必须在你的方法实现中完成，防止非法输入导致业务逻辑错误。
3. HTTPS：如果服务暴露在公网，必须使用HTTPS。HttpServer支持HTTPS，你需要在构造时提供证书和私钥文件的路径。

   HttpServer httpserver(8080, "/path/to/cert.pem", "/path/to/key.pem", "/path/to/dh.pem");

4. 防暴力攻击：考虑对客户端IP或调用频率做限制，防止DoS攻击。

7.3 版本管理与接口演进

随着项目发展，RPC接口必然需要变更。JSON-RPC本身没有内置的版本管理机制，需要你自己设计策略。

• 向后兼容性：尽量以添加新方法、为已有方法添加可选参数的方式进行扩展。避免删除或重命名已有方法。
• 版本标识：可以在方法名中嵌入版本号，例如getUserInfo_v2。或者，在JSON-RPC请求中增加一个自定义的version字段，服务端根据版本来路由到不同的处理逻辑。
• 使用规范文件作为契约：将.json规范文件视为服务契约，纳入版本控制系统。客户端和服务端的代码版本应与特定的规范文件版本绑定。可以通过在接口中提供一个getApiVersion的方法来让客户端查询。

最后，关于这个框架的长期维护，需要注意到原仓库cinemast/libjson-rpc-cpp在2021年发布了v1.4.1后，活跃度有所下降。作者也提到了一个新的C++17头文件实现json-rpc-cxx。对于新项目，如果可以使用C++17，值得去评估一下那个新库。但对于大量现有的、使用C++11/14且稳定运行的项目，libjson-rpc-cpp仍然是一个非常可靠的选择，它的代码质量、文档和社区积累的示例足以支撑生产级应用。我的建议是，如果你的团队已经熟悉它并且项目运行良好，没有必要盲目升级或替换；如果是全新的绿色项目，不妨花点时间对比一下新老方案的特性再做决定。技术选型没有银弹，适合当前团队和项目上下文的技术，就是最好的技术。