1. 项目概述为什么我们需要一个现代的JSON-RPC库如果你做过微服务、分布式系统或者仅仅是前后端分离的项目那么对RPC远程过程调用这个概念一定不陌生。简单说就是让一个程序能像调用本地函数一样去调用网络上另一台机器上的函数。而JSON-RPC就是用JSON这种人类和机器都容易读写的格式来定义这种远程调用的协议。它比古老的XML-RPC轻量也比某些二进制协议如gRPC在调试和兼容性上更友好。那为什么还要一个“JSON-RPC”呢我最初接触这个需求是在一个物联网边缘计算的项目里。我们需要在资源受限的嵌入式设备比如树莓派和云端服务器之间进行高效、可靠的双向通信。市面上已有的库要么像jsonrpc-cpp那样依赖较重、配置繁琐要么功能过于简单缺少连接管理、异步通知这些生产环境必备的特性。更别提有些库的C标准还停留在C98与现代CC11/14/17的优雅和高效格格不入。所以“JSON-RPC”在我理解中不是一个特定的开源项目名字虽然可能有同名项目而是一个构建现代、高效、易用的C JSON-RPC库的实践方案。它应该具备几个核心特征基于现代C至少C11零外部依赖或最小依赖如仅需一个JSON解析库支持TCP/WebSocket等多种传输层内置连接池和心跳机制以及提供同步/异步两种调用模式。本教程的目的就是带你从零开始亲手搭建这样一个符合现代工程需求的JSON-RPC通信框架并最终将其容器化部署与MySQL数据库集成完成一个完整的、可复现的项目闭环。2. 核心架构设计与技术选型2.1 协议层设计JSON-RPC 2.0规范的精简与增强我们选择遵循JSON-RPC 2.0规范作为基础因为它足够简单且广泛应用。一个标准的请求Request和响应Response看起来是这样的请求{ jsonrpc: 2.0, method: subtract, params: {minuend: 42, subtrahend: 23}, id: 3 }响应成功{ jsonrpc: 2.0, result: 19, id: 3 }响应错误{ jsonrpc: 2.0, error: { code: -32601, message: Method not found }, id: 3 }但在实际工业级应用中原版规范有些地方需要增强批量请求Batch Request规范支持但很多库实现不完善。我们会实现它这对于客户端一次性发起多个查询、减少网络往返延迟很有用。通知Notification即没有id字段的请求表示客户端不期望服务器回复。这常用于服务端向客户端推送消息如告警、状态更新。扩展错误码除了规范预定义的错误码如-32601方法不存在-32700解析错误我们需要定义业务错误码范围例如-32000到-32099用于传递业务逻辑失败信息。链路追踪TraceId在微服务场景下一个请求可能穿越多个服务。我们可以在params或一个自定义的扩展字段里加入traceId便于分布式日志追踪。注意增强协议时务必保持向后兼容。任何额外的字段都应该是可选的确保与标准JSON-RPC 2.0客户端/服务器的互操作性。2.2 传输层抽象支持TCP与WebSocket网络通信是RPC的基石。我们不能把库绑定在单一协议上。因此设计一个Transport抽象基类是关键。class Transport { public: virtual ~Transport() default; // 发送数据 virtual bool send(const std::string message) 0; // 设置接收数据的回调 virtual void setReceiveHandler(std::functionvoid(const std::string) handler) 0; // 启动连接对于服务端是监听对于客户端是连接 virtual bool start() 0; // 停止 virtual void stop() 0; };然后我们为不同的协议实现具体的派生类TcpTransport基于传统的TCP Socket。高性能适合内网服务间通信。需要自己处理封包/拆包因为TCP是字节流。WebSocketTransport基于WebSocket协议。它建立在HTTP之上能穿透大多数防火墙和代理天然适合浏览器作为客户端也常用于物联网设备通过公网与服务器通信。我们可以使用像libwebsockets或Boost.Beast这样的库来实现。通过这种设计核心的RPC逻辑协议解析、方法路由、调用执行与底层网络传输完全解耦。今天用TCP明天想换成WebSocket甚至Unix Domain Socket只需要换一个Transport实现上层代码几乎不用动。2.3 序列化与反序列化选用现代JSON库C的JSON库选择很多。我们的目标是轻量、高效、易用并且支持现代C特性如移动语义、STL容器自动转换。nlohmann/json这是社区事实上的标准。头文件库只需包含一个json.hppAPI极其直观友好性能也不错。对于大多数项目它是首选。#include nlohmann/json.hpp using json nlohmann::json; json j {{method, add}, {params, {1, 2}}}; std::string serialized j.dump(); // 序列化为字符串 auto deserialized json::parse(serialized); // 反序列化RapidJSON腾讯开源的库性能极致但API是C风格的使用起来稍显繁琐。如果你的项目对性能有极端要求且愿意牺牲一点开发便利性可以考虑它。jsoncpp比较老牌的库很多系统预装。但API不如nlohmann/json现代。本教程为了开发效率和代码可读性选择nlohmann/json。它是一个纯头文件库可以通过包管理器如vcpkg、conan安装或者直接下载单头文件放入项目。实操心得使用nlohmann/json时注意它默认的json对象类型是std::map和std::vector的包装。对于频繁序列化/反序列化的大对象考虑使用json::to_msgpack和json::from_msgpack进行二进制序列化MessagePack体积更小速度更快但牺牲了可读性。2.4 核心类设计Server, Client, Registry整个库围绕三个核心类展开MethodRegistry方法注册表一个单例或上下文类维护方法名到可调用对象函数、lambda、成员函数的映射。这是RPC的“电话本”。Server服务器持有Transport和MethodRegistry。监听网络请求将收到的JSON字符串交给MethodRegistry执行对应方法并将结果序列化后通过Transport发回。Client客户端持有Transport。提供call和notify等方法将调用请求序列化为JSON通过Transport发送并等待或不等响应。一个关键设计点是异步支持。客户端的call方法应该返回一个std::futurejson这样调用者可以选择同步等待future.get()或异步处理。服务器端处理请求也应在独立线程池中进行避免阻塞网络IO线程。3. 逐步实现从零编写核心代码3.1 第一步搭建项目基础结构与依赖管理我们使用CMake作为构建系统这是C项目的标准选择。项目目录结构如下json-rpc-plus-plus/ ├── CMakeLists.txt # 根CMake配置 ├── include/ # 公共头文件 │ └── jsonrpcpp/ │ ├── core.hpp │ ├── server.hpp │ ├── client.hpp │ └── transport.hpp ├── src/ # 源代码 │ ├── core.cpp │ ├── server.cpp │ ├── client.cpp │ └── transport/ │ ├── tcp_transport.cpp │ └── websocket_transport.cpp ├── third_party/ # 放置第三方库如nlohmann/json ├── examples/ # 示例代码 ├── tests/ # 单元测试 └── Dockerfile # 容器化部署文件根目录的CMakeLists.txt关键配置cmake_minimum_required(VERSION 3.15) project(JsonRpcPlusPlus VERSION 1.0.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 将项目设为库 add_library(jsonrpcpp STATIC src/core.cpp src/server.cpp src/client.cpp src/transport/tcp_transport.cpp ) # 包含头文件目录 target_include_directories(jsonrpcpp PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR}/third_party ) # 查找并链接系统库如线程 find_package(Threads REQUIRED) target_link_libraries(jsonrpcpp PUBLIC Threads::Threads) # 对于WebSocket可能需要额外库这里以假设使用Boost.Beast为例 option(USE_WEBSOCKET Build with WebSocket support OFF) if(USE_WEBSOCKET) find_package(Boost REQUIRED COMPONENTS system) target_link_libraries(jsonrpcpp PUBLIC Boost::system) # ... 添加websocket_transport.cpp到库源文件 endif() # 安装目标便于其他项目使用 install(TARGETS jsonrpcpp ARCHIVE DESTINATION lib) install(DIRECTORY include/jsonrpcpp DESTINATION include)使用vcpkg或conan来管理nlohmann/json依赖是最佳实践。以vcpkg为例在CMake中集成# 假设vcpkg已安装并配置了CMAKE_TOOLCHAIN_FILE find_package(nlohmann_json 3.10.5 CONFIG REQUIRED) target_link_libraries(jsonrpcpp PUBLIC nlohmann_json::nlohmann_json)3.2 第二步实现MethodRegistry与方法绑定MethodRegistry的核心是一个std::unordered_mapstd::string, std::functionjson(const json)。但我们需要支持更丰富的绑定方式普通函数、类成员函数、lambda表达式。// include/jsonrpcpp/core.hpp #pragma once #include nlohmann/json.hpp #include functional #include string #include unordered_map namespace jsonrpcpp { using json nlohmann::json; class MethodRegistry { public: using Handler std::functionjson(const json); static MethodRegistry instance() { static MethodRegistry reg; return reg; } // 绑定普通函数或静态函数 templatetypename Func void bind(const std::string name, Func func) { handlers_[name] [func](const json params) - json { // 这里需要根据Func的签名将json params转换为函数参数 // 这是一个复杂的点需要用到模板元编程进行参数展开 // 简化版假设func接受一个json参数 return func(params); }; } // 绑定类成员函数 templatetypename Class, typename... Args void bind(const std::string name, Class* obj, json (Class::*method)(const json)) { handlers_[name] [obj, method](const json params) - json { return (obj-*method)(params); }; } json invoke(const std::string method, const json params) { auto it handlers_.find(method); if (it handlers_.end()) { throw std::runtime_error(Method not found: method); } return it-second(params); } private: MethodRegistry() default; std::unordered_mapstd::string, Handler handlers_; }; } // namespace jsonrpcpp上面的bind函数是简化版它假设所有被绑定的函数都接受一个json参数。但在真正的RPC中我们希望像调用本地函数一样参数是类型安全的。这就需要用到更高级的模板元编程技术实现一个参数解析器将JSON数组或对象自动转换为C函数的参数列表。这是整个库实现中最有挑战也最精彩的部分之一。一个常见的实现思路是为每个参数类型提供一个特化的from_json函数nlohmann/json本身支持然后利用C17的std::apply和参数包展开将JSON数组解包为函数参数。注意事项方法注册通常发生在服务器启动前。务必确保注册过程是线程安全的特别是在动态加载模块的场景下。可以使用std::call_once或简单的锁来保护handlers_映射的修改。3.3 第三步实现Server类与请求处理循环Server类负责协调Transport和MethodRegistry。它的核心是一个事件循环。// include/jsonrpcpp/server.hpp #pragma once #include core.hpp #include transport.hpp #include memory #include thread #include atomic namespace jsonrpcpp { class Server { public: Server(std::unique_ptrTransport transport) : transport_(std::move(transport)), running_(false) {} void start() { if (running_) return; running_ true; // 设置数据接收回调 transport_-setReceiveHandler([this](const std::string msg) { this-onMessage(msg); }); // 启动传输层开始监听或连接 if (!transport_-start()) { throw std::runtime_error(Failed to start transport); } // 可以在独立线程中运行事件循环这里简化为主线程循环 // 实际项目中transport_-start()可能内部就启动了事件循环如asio的io_context.run } void stop() { running_ false; transport_-stop(); } // 便捷的绑定方法转发给MethodRegistry templatetypename Func void bind(const std::string name, Func func) { MethodRegistry::instance().bind(name, func); } private: void onMessage(const std::string raw_message) { try { json request json::parse(raw_message); // 1. 验证JSON-RPC 2.0基本结构 if (!request.contains(jsonrpc) || request[jsonrpc] ! 2.0) { sendError(nullptr, -32600, Invalid Request); return; } if (!request.contains(method) || !request[method].is_string()) { sendError(nullptr, -32600, Invalid Request); return; } std::string method request[method]; json params request.value(params, json::object()); // 默认为空对象 json id request.value(id, json()); // 通知请求的id为null // 2. 调用方法 json result MethodRegistry::instance().invoke(method, params); // 3. 如果是通知id为null则不回复 if (id.is_null()) { return; } // 4. 发送成功响应 json response { {jsonrpc, 2.0}, {result, result}, {id, id} }; transport_-send(response.dump()); } catch (const json::parse_error e) { sendError(nullptr, -32700, Parse error: std::string(e.what())); } catch (const std::exception e) { // 方法执行中抛出的异常转换为JSON-RPC错误 json id json::parse(raw_message).value(id, json()); sendError(id.is_null() ? nullptr : id, -32000, Server error: std::string(e.what())); } } void sendError(const json* id, int code, const std::string message) { json error_response { {jsonrpc, 2.0}, {error, { {code, code}, {message, message} }} }; if (id !id-is_null()) { error_response[id] *id; } else { error_response[id] nullptr; // 对于通知或解析错误id为null } transport_-send(error_response.dump()); } std::unique_ptrTransport transport_; std::atomicbool running_; }; } // namespace jsonrpcpp这个Server实现是单线程的。在生产环境中你需要引入线程池。当onMessage收到请求后将其包装成一个任务std::packaged_task提交到线程池避免阻塞网络IO。线程池执行完毕后再将结果交还给IO线程或另一个发送线程进行回复。这涉及到更复杂的跨线程通信可以使用asio::post或自定义的任务队列。3.4 第四步实现Client类与异步调用Client的设计目标是让远程调用看起来像本地调用一样简单同时支持异步。// include/jsonrpcpp/client.hpp #pragma once #include transport.hpp #include nlohmann/json.hpp #include future #include unordered_map #include atomic namespace jsonrpcpp { class Client { public: Client(std::unique_ptrTransport transport) : transport_(std::move(transport)), next_id_(1) { transport_-setReceiveHandler([this](const std::string msg) { this-onResponse(msg); }); transport_-start(); } // 同步调用阻塞直到收到响应或超时 json call(const std::string method, const json params, int timeout_ms 5000) { auto future callAsync(method, params); auto status future.wait_for(std::chrono::milliseconds(timeout_ms)); if (status std::future_status::timeout) { throw std::runtime_error(RPC call timeout); } return future.get(); } // 异步调用立即返回future std::futurejson callAsync(const std::string method, const json params) { int id next_id_.fetch_add(1, std::memory_order_relaxed); json request { {jsonrpc, 2.0}, {method, method}, {params, params}, {id, id} }; auto promise std::make_sharedstd::promisejson(); std::futurejson future promise-get_future(); { std::lock_guardstd::mutex lock(pending_mutex_); pending_requests_[id] promise; } if (!transport_-send(request.dump())) { std::lock_guardstd::mutex lock(pending_mutex_); pending_requests_.erase(id); promise-set_exception(std::make_exception_ptr(std::runtime_error(Send failed))); } return future; } // 发送通知不期待回复 void notify(const std::string method, const json params) { json request { {jsonrpc, 2.0}, {method, method}, {params, params} // 注意没有id字段 }; transport_-send(request.dump()); } private: void onResponse(const std::string raw_message) { try { json response json::parse(raw_message); // 验证响应格式 if (!response.contains(jsonrpc) || response[jsonrpc] ! 2.0) return; if (!response.contains(id) || !response[id].is_number_integer()) return; int id response[id]; std::shared_ptrstd::promisejson promise; { std::lock_guardstd::mutex lock(pending_mutex_); auto it pending_requests_.find(id); if (it pending_requests_.end()) return; // 未知的响应忽略 promise it-second; pending_requests_.erase(it); } if (response.contains(error)) { // 服务器返回错误 promise-set_exception(std::make_exception_ptr( std::runtime_error(response[error][message]) )); } else if (response.contains(result)) { // 成功 promise-set_value(response[result]); } } catch (...) { // 忽略解析或处理错误 } } std::unique_ptrTransport transport_; std::atomicint next_id_; std::unordered_mapint, std::shared_ptrstd::promisejson pending_requests_; std::mutex pending_mutex_; }; } // namespace jsonrpcpp这个Client实现了一个简单的请求-响应映射。每个异步调用生成一个唯一的id并将对应的std::promise存入pending_requests_字典。当收到响应时根据id找到对应的promise并设置值结果或异常错误。call方法只是callAsync加上超时等待的包装。实操心得next_id_的自增需要使用原子操作std::atomic因为可能被多个线程同时调用callAsync。pending_requests_的访问也必须用互斥锁保护。在高并发场景下这个锁可能成为瓶颈。可以考虑使用并发容器如concurrent_unordered_map或分片锁来优化。3.5 第五步实现TCP传输层TcpTransportTCP传输层需要解决粘包/拆包问题。JSON-RPC over TCP没有固定的消息边界我们需要定义一个简单的帧协议。常见的方法有长度前缀法在每个消息前加一个固定字节如4字节表示后续JSON数据的长度。分隔符法用一个特殊字符如\n作为消息结束符。但JSON本身可能包含换行所以需要确保分隔符不会出现在内容中或者对内容进行转义。我们采用更可靠的长度前缀法。// src/transport/tcp_transport.cpp (部分关键代码) #include jsonrpcpp/transport.hpp #include asio.hpp // 使用ASIO作为网络库 #include iostream class TcpTransportImpl : public Transport { public: TcpTransportImpl(const std::string host, int port, bool is_server) : io_context_(), socket_(io_context_), is_server_(is_server), host_(host), port_(port) {} bool start() override { if (is_server_) { asio::ip::tcp::acceptor acceptor(io_context_, asio::ip::tcp::endpoint(asio::ip::tcp::v4(), port_)); // 简化只接受一个连接 acceptor.accept(socket_); } else { asio::ip::tcp::resolver resolver(io_context_); auto endpoints resolver.resolve(host_, std::to_string(port_)); asio::connect(socket_, endpoints); } // 启动读循环 doReadHeader(); // 在独立线程中运行io_context io_thread_ std::thread([this]() { io_context_.run(); }); return true; } bool send(const std::string message) override { // 构造帧4字节长度 数据 uint32_t length static_castuint32_t(message.size()); std::vectorchar frame(sizeof(length) message.size()); std::memcpy(frame.data(), length, sizeof(length)); std::memcpy(frame.data() sizeof(length), message.data(), message.size()); asio::error_code ec; asio::write(socket_, asio::buffer(frame), ec); return !ec; } void setReceiveHandler(ReceiveHandler handler) override { handler_ std::move(handler); } void stop() override { io_context_.stop(); if (io_thread_.joinable()) io_thread_.join(); socket_.close(); } private: void doReadHeader() { auto self shared_from_this(); // 假设继承自enable_shared_from_this asio::async_read(socket_, asio::buffer(next_msg_length_, sizeof(next_msg_length_)), [this, self](asio::error_code ec, std::size_t /*length*/) { if (!ec) { // 网络字节序转主机字节序如果跨平台 // next_msg_length_ ntohl(next_msg_length_); // 如果需要 doReadBody(); } }); } void doReadBody() { read_buffer_.resize(next_msg_length_); auto self shared_from_this(); asio::async_read(socket_, asio::buffer(read_buffer_), [this, self](asio::error_code ec, std::size_t /*length*/) { if (!ec handler_) { handler_(std::string(read_buffer_.begin(), read_buffer_.end())); doReadHeader(); // 继续读下一个消息头 } }); } asio::io_context io_context_; asio::ip::tcp::socket socket_; std::thread io_thread_; bool is_server_; std::string host_; int port_; ReceiveHandler handler_; uint32_t next_msg_length_; std::vectorchar read_buffer_; };这里使用了asio库来处理异步网络IO这是C中高性能网络编程的标杆。doReadHeader和doReadBody构成了一个异步读取链持续处理到来的消息。4. 项目实战构建一个用户查询服务并容器化部署现在我们将这个库用起来构建一个简单的“用户服务”它提供一个getUserInfo的RPC方法并连接MySQL数据库。最后我们将整个服务Docker化。4.1 定义服务接口与MySQL操作首先定义我们的用户服务类// examples/user_service.hpp #pragma once #include jsonrpcpp/core.hpp #include mysqlx/xdevapi.h // 使用MySQL Connector/C 的X DevAPI #include string class UserService { public: UserService(const std::string mysql_uri) { // 初始化数据库连接实际生产环境会用连接池 session_ std::make_uniquemysqlx::Session(mysql_uri); schema_ std::make_uniquemysqlx::Schema(session_-getSchema(user_db)); table_ std::make_uniquemysqlx::Table(schema_-getTable(users)); } json getUserInfo(const json params) { // 期望参数: {user_id: 123} if (!params.contains(user_id) || !params[user_id].is_number()) { throw std::invalid_argument(Missing or invalid user_id); } int user_id params[user_id]; // 执行数据库查询 mysqlx::RowResult result table_-select(id, name, email) .where(id :id) .bind(id, user_id) .execute(); if (auto row result.fetchOne()) { return { {id, row[0]}, {name, std::string(row[1])}, {email, std::string(row[2])} }; } else { // 用户未找到返回一个JSON-RPC自定义错误 json error { {code, -32001}, // 自定义业务错误码 {message, User not found} }; throw std::runtime_error(error.dump()); // Server类的onMessage会捕获并包装 } } private: std::unique_ptrmysqlx::Session session_; std::unique_ptrmysqlx::Schema schema_; std::unique_ptrmysqlx::Table table_; };4.2 编写服务器端主程序// examples/server_main.cpp #include jsonrpcpp/server.hpp #include jsonrpcpp/transport/tcp_transport.hpp // 假设我们实现了这个 #include user_service.hpp #include iostream #include memory int main() { // 1. 创建服务实例 std::string mysql_uri mysqlx://root:passwordlocalhost:33060; auto user_service std::make_sharedUserService(mysql_uri); // 2. 创建RPC服务器使用TCP传输监听8080端口 auto transport std::make_uniqueTcpTransportImpl(0.0.0.0, 8080, true); jsonrpcpp::Server server(std::move(transport)); // 3. 将服务方法绑定到RPC server.bind(getUserInfo, [user_service](const json params) - json { return user_service-getUserInfo(params); }); // 可以绑定更多方法... server.bind(echo, [](const json params) - json { return params; // 简单回显 }); // 4. 启动服务器 std::cout JSON-RPC Server starting on port 8080... std::endl; server.start(); // 5. 保持主线程运行实际中可能有信号处理等 std::this_thread::sleep_for(std::chrono::hours(1)); server.stop(); return 0; }4.3 编写客户端测试程序// examples/client_main.cpp #include jsonrpcpp/client.hpp #include jsonrpcpp/transport/tcp_transport.hpp #include iostream int main() { // 1. 创建客户端连接到服务器 auto transport std::make_uniqueTcpTransportImpl(127.0.0.1, 8080, false); jsonrpcpp::Client client(std::move(transport)); // 2. 同步调用 try { json params {{user_id, 123}}; json result client.call(getUserInfo, params); std::cout User info: result.dump(2) std::endl; } catch (const std::exception e) { std::cerr RPC call failed: e.what() std::endl; } // 3. 异步调用 auto future client.callAsync(echo, {{message, Hello Async}}); // ... 这里可以做其他事情 ... try { json async_result future.get(); // 等待结果 std::cout Echo result: async_result.dump() std::endl; } catch (...) { std::cerr Async call failed. std::endl; } // 4. 发送通知 client.notify(logMessage, {{level, info}, {msg, Client started}}); return 0; }4.4 容器化部署编写Dockerfile将我们的服务器端程序打包成Docker镜像便于分发和部署。# Dockerfile # 使用多阶段构建减小镜像体积 FROM ubuntu:22.04 AS builder # 安装构建依赖 RUN apt-get update apt-get install -y \ build-essential \ cmake \ git \ libasio-dev \ libmysqlclient-dev \ libssl-dev \ rm -rf /var/lib/apt/lists/* # 复制项目代码 WORKDIR /src COPY . . # 构建项目 RUN mkdir build cd build \ cmake -DCMAKE_BUILD_TYPERelease -DUSE_WEBSOCKETOFF .. \ make -j$(nproc) # 运行时阶段 FROM ubuntu:22.04 # 安装运行时依赖主要是MySQL客户端库 RUN apt-get update apt-get install -y \ libmysqlclient21 \ rm -rf /var/lib/apt/lists/* # 从构建阶段复制可执行文件 WORKDIR /app COPY --frombuilder /src/build/examples/server_main ./jsonrpc_server COPY --frombuilder /src/third_party/nlohmann/json.hpp ./ # 如果需要 # 暴露端口 EXPOSE 8080 # 设置启动命令 # 数据库连接信息应通过环境变量传入而非写死在代码中 CMD [./jsonrpc_server]构建并运行镜像# 构建镜像 docker build -t jsonrpc-user-service . # 运行容器链接到MySQL容器并传入环境变量 docker run -d \ --name jsonrpc-server \ -p 8080:8080 \ --link mysql-container:mysql \ -e MYSQL_URImysqlx://root:passwordmysql:33060/user_db \ jsonrpc-user-service4.5 数据库初始化与项目式教程整合为了完成“项目式教程”我们需要一个配套的MySQL数据库。创建一个init.sql文件-- init.sql CREATE DATABASE IF NOT EXISTS user_db; USE user_db; CREATE TABLE IF NOT EXISTS users ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); INSERT INTO users (name, email) VALUES (张三, zhangsanexample.com), (李四, lisiexample.com);可以使用Docker Compose来编排整个应用栈JSON-RPC服务器 MySQL这是当前最流行的微服务部署方式之一。# docker-compose.yml version: 3.8 services: mysql: image: mysql:8.0 container_name: jsonrpc-mysql environment: MYSQL_ROOT_PASSWORD: password MYSQL_DATABASE: user_db ports: - 33060:33060 # MySQL X Protocol 端口 volumes: - ./init.sql:/docker-entrypoint-initdb.d/init.sql - mysql_data:/var/lib/mysql command: --mysqlx1 # 启用X Plugin jsonrpc-server: build: . container_name: jsonrpc-server depends_on: - mysql environment: MYSQL_URI: mysqlx://root:passwordmysql:33060/user_db ports: - 8080:8080 # 假设我们的可执行文件在构建后位于/app/jsonrpc_server command: [./jsonrpc_server] volumes: mysql_data:运行docker-compose up -d一个完整的、包含数据库的JSON-RPC服务就启动起来了。客户端可以通过localhost:8080来调用getUserInfo等方法。5. 性能调优、问题排查与进阶思考5.1 性能瓶颈分析与优化在实际压力测试中你可能会发现以下瓶颈及优化方案JSON序列化/反序列化这是CPU密集型操作。对于高频调用可以使用更快的JSON库如切换到RapidJSON。使用二进制协议在传输层使用MessagePack或Protobuf替代JSON但会牺牲可读性。可以在Transport层做透明编解码。缓存序列化结果如果某些响应是静态或变化不频繁的可以缓存其JSON字符串。网络IO与线程模型单线程瓶颈最初的简单Server是单线程处理请求。优化方法是使用IO多路复用如asio 线程池。主线程负责网络IO收到完整请求后将解析出的json对象和回复回调打包成任务丢进线程池。线程池中的工作线程执行方法调用完成后通过asio的post函数将回复任务交还给IO线程发送。连接池对于客户端特别是需要频繁创建短连接时维护一个到服务器的连接池避免TCP三次握手的开销。内存分配频繁的std::string和json对象构造/析构会导致内存碎片。可以考虑使用内存池或对象池尤其是对于固定大小的请求/响应缓冲区。5.2 常见问题排查实录问题1客户端调用超时Timeout排查网络连通性用telnet server_ip port检查端口是否开放。服务器负载服务器CPU/内存是否过高使用top或htop查看。服务器日志查看服务器端是否有错误日志如数据库连接失败、方法执行异常。防火墙规则确保服务器防火墙如ufw、iptables允许该端口流量。客户端代码检查client.call的超时时间设置是否过短。问题2收到“Parse error”或无效的JSON响应排查粘包/拆包这是TCP传输最常见的问题。确保你的TcpTransport正确实现了长度前缀法。可以在发送和接收端打印原始十六进制数据检查帧边界是否正确。编码问题确保发送的JSON字符串是UTF-8编码且没有非法字符。并发写入确保没有多个线程同时向同一个TCP连接写入数据这会导致数据交织。客户端发送请求应串行化或使用发送队列。问题3方法调用成功但返回结果不对排查参数格式检查客户端发送的params格式是否与服务器端方法期望的一致。是JSON对象{}还是数组[]服务器端MethodRegistry的参数解析逻辑是否匹配。数据类型转换JSON数字到Cint/double的转换是否有精度损失字符串是否正确处理了Unicode数据库查询直接登录MySQL用同样的参数手动执行SQL验证结果。问题4Docker容器内服务无法连接MySQL容器排查服务发现在Docker Compose中使用服务名mysql作为主机名而不是localhost。确保MYSQL_URI环境变量正确设置为mysqlx://root:passwordmysql:33060/user_db。MySQL X Plugin确保MySQL镜像启动了X Plugin我们的连接使用X协议端口33060。检查MySQL容器的日志。依赖启动顺序在docker-compose.yml中使用了depends_on但这只保证容器启动顺序不保证MySQL服务就绪。需要在服务器启动脚本中加入对MySQL端口的健康检查等待其就绪后再启动RPC服务。5.3 进阶扩展方向一个基础的JSON-RPC库搭建完成后可以根据实际需求向不同方向深化服务发现与负载均衡集成Consul、Etcd或Nacos客户端不再写死服务器地址而是从注册中心动态获取可用服务节点列表。身份认证与授权在传输层如TLS或协议层在params外增加auth字段加入Token或签名验证。监控与链路追踪集成OpenTelemetry自动在RPC调用中注入和传递TraceId、SpanId并上报到Jaeger或Zipkin。代码生成与IDL定义接口描述语言IDL自动生成服务器端骨架代码和客户端桩代码提高开发效率保证类型安全。这是像gRPC、Thrift等成熟RPC框架的核心特性。支持更多传输协议除了TCP和WebSocket可以实现HTTP传输将JSON-RPC作为HTTP POST请求的body这样任何能发HTTP请求的客户端都能调用兼容性极广。从零构建一个生产可用的RPC框架是一项系统工程本教程为你铺平了核心道路。最重要的是理解其设计哲学协议与传输分离、异步非阻塞、类型安全与易用性平衡。当你亲手实现一遍再去看那些开源的大型RPC框架源码你会发现很多设计都是相通的。
