从零构建现代C++ JSON-RPC框架：协议设计、传输层与容器化部署

1. 项目概述：为什么我们需要一个现代的JSON-RPC库？

如果你做过微服务、分布式系统，或者仅仅是前后端分离的项目，那么对RPC（远程过程调用）这个概念一定不陌生。简单说，就是让一个程序能像调用本地函数一样，去调用网络上另一台机器上的函数。而JSON-RPC，就是用JSON这种人类和机器都容易读写的格式，来定义这种远程调用的协议。它比古老的XML-RPC轻量，也比某些二进制协议（如gRPC）在调试和兼容性上更友好。

那为什么还要一个“JSON-RPC++”呢？我最初接触这个需求，是在一个物联网边缘计算的项目里。我们需要在资源受限的嵌入式设备（比如树莓派）和云端服务器之间进行高效、可靠的双向通信。市面上已有的库，要么像jsonrpc-cpp那样依赖较重、配置繁琐，要么功能过于简单，缺少连接管理、异步通知这些生产环境必备的特性。更别提有些库的C++标准还停留在C++98，与现代C++（C++11/14/17）的优雅和高效格格不入。

所以，“JSON-RPC++”在我理解中，不是一个特定的开源项目名字（虽然可能有同名项目），而是一个构建现代、高效、易用的C++ JSON-RPC库的实践方案。它应该具备几个核心特征：基于现代C++（至少C++11），零外部依赖或最小依赖（如仅需一个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 }

但在实际工业级应用中，原版规范有些地方需要增强：

1. 批量请求（Batch Request）：规范支持，但很多库实现不完善。我们会实现它，这对于客户端一次性发起多个查询、减少网络往返延迟很有用。
2. 通知（Notification）：即没有id字段的请求，表示客户端不期望服务器回复。这常用于服务端向客户端推送消息（如告警、状态更新）。
3. 扩展错误码：除了规范预定义的错误码（如-32601方法不存在，-32700解析错误），我们需要定义业务错误码范围（例如-32000到-32099），用于传递业务逻辑失败信息。
4. 链路追踪（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::function<void(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容器自动转换）。

1. nlohmann/json：这是社区事实上的标准。头文件库，只需包含一个json.hpp，API极其直观友好，性能也不错。对于大多数项目，它是首选。

   #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); // 反序列化

2. RapidJSON：腾讯开源的库，性能极致，但API是C风格的，使用起来稍显繁琐。如果你的项目对性能有极端要求，且愿意牺牲一点开发便利性，可以考虑它。
3. 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

整个库围绕三个核心类展开：

1. MethodRegistry（方法注册表）：一个单例或上下文类，维护方法名到可调用对象（函数、lambda、成员函数）的映射。这是RPC的“电话本”。
2. Server（服务器）：持有Transport和MethodRegistry。监听网络请求，将收到的JSON字符串交给MethodRegistry执行对应方法，并将结果序列化后通过Transport发回。
3. Client（客户端）：持有Transport。提供call和notify等方法，将调用请求序列化为JSON，通过Transport发送，并等待（或不等）响应。

一个关键设计点是异步支持。客户端的call方法应该返回一个std::future<json>，这样调用者可以选择同步等待（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_map<std::string, std::function<json(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::function<json(const json&)>; static MethodRegistry& instance() { static MethodRegistry reg; return reg; } // 绑定普通函数或静态函数 template<typename Func> void bind(const std::string& name, Func func) { handlers_[name] = [func](const json& params) -> json { // 这里需要根据Func的签名，将json params转换为函数参数 // 这是一个复杂的点，需要用到模板元编程进行参数展开 // 简化版：假设func接受一个json参数 return func(params); }; } // 绑定类成员函数 template<typename 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_map<std::string, Handler> handlers_; }; } // namespace jsonrpcpp

上面的bind函数是简化版，它假设所有被绑定的函数都接受一个json参数。但在真正的RPC中，我们希望像调用本地函数一样，参数是类型安全的。这就需要用到更高级的模板元编程技术，实现一个参数解析器，将JSON数组或对象自动转换为C++函数的参数列表。这是整个库实现中最有挑战也最精彩的部分之一。

一个常见的实现思路是：为每个参数类型提供一个特化的from_json函数（nlohmann/json本身支持），然后利用C++17的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_ptr<Transport> 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 template<typename 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_ptr<Transport> transport_; std::atomic<bool> 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_ptr<Transport> 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::future<json> 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_shared<std::promise<json>>(); std::future<json> future = promise->get_future(); { std::lock_guard<std::mutex> lock(pending_mutex_); pending_requests_[id] = promise; } if (!transport_->send(request.dump())) { std::lock_guard<std::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_ptr<std::promise<json>> promise; { std::lock_guard<std::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_ptr<Transport> transport_; std::atomic<int> next_id_; std::unordered_map<int, std::shared_ptr<std::promise<json>>> 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传输层（TcpTransport）

TCP传输层需要解决粘包/拆包问题。JSON-RPC over TCP没有固定的消息边界，我们需要定义一个简单的帧协议。常见的方法有：

1. 长度前缀法：在每个消息前加一个固定字节（如4字节）表示后续JSON数据的长度。
2. 分隔符法：用一个特殊字符（如\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_cast<uint32_t>(message.size()); std::vector<char> 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::vector<char> 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_unique<mysqlx::Session>(mysql_uri); schema_ = std::make_unique<mysqlx::Schema>(session_->getSchema("user_db")); table_ = std::make_unique<mysqlx::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_ptr<mysqlx::Session> session_; std::unique_ptr<mysqlx::Schema> schema_; std::unique_ptr<mysqlx::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:password@localhost:33060"; auto user_service = std::make_shared<UserService>(mysql_uri); // 2. 创建RPC服务器，使用TCP传输，监听8080端口 auto transport = std::make_unique<TcpTransportImpl>("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_unique<TcpTransportImpl>("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_TYPE=Release -DUSE_WEBSOCKET=OFF .. \ && 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 --from=builder /src/build/examples/server_main ./jsonrpc_server COPY --from=builder /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_URI="mysqlx://root:password@mysql:33060/user_db" \ jsonrpc-user-service

4.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 ('张三', 'zhangsan@example.com'), ('李四', 'lisi@example.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: --mysqlx=1 # 启用X Plugin jsonrpc-server: build: . container_name: jsonrpc-server depends_on: - mysql environment: MYSQL_URI: "mysqlx://root:password@mysql: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 性能瓶颈分析与优化

在实际压力测试中，你可能会发现以下瓶颈及优化方案：

1. JSON序列化/反序列化：这是CPU密集型操作。对于高频调用，可以：

   • 使用更快的JSON库：如切换到RapidJSON。
   • 使用二进制协议：在传输层使用MessagePack或Protobuf替代JSON，但会牺牲可读性。可以在Transport层做透明编解码。
   • 缓存序列化结果：如果某些响应是静态或变化不频繁的，可以缓存其JSON字符串。

2. 网络IO与线程模型：

   • 单线程瓶颈：最初的简单Server是单线程处理请求。优化方法是使用IO多路复用（如asio） + 线程池。主线程负责网络IO，收到完整请求后，将解析出的json对象和回复回调打包成任务，丢进线程池。线程池中的工作线程执行方法调用，完成后通过asio的post函数将回复任务交还给IO线程发送。
   • 连接池：对于客户端，特别是需要频繁创建短连接时，维护一个到服务器的连接池，避免TCP三次握手的开销。

3. 内存分配：频繁的std::string和json对象构造/析构会导致内存碎片。可以考虑使用内存池或对象池，尤其是对于固定大小的请求/响应缓冲区。

5.2 常见问题排查实录

问题1：客户端调用超时（Timeout）

• 排查：
  1. 网络连通性：用telnet <server_ip> <port>检查端口是否开放。
  2. 服务器负载：服务器CPU/内存是否过高？使用top或htop查看。
  3. 服务器日志：查看服务器端是否有错误日志，如数据库连接失败、方法执行异常。
  4. 防火墙规则：确保服务器防火墙（如ufw、iptables）允许该端口流量。
  5. 客户端代码：检查client.call的超时时间设置是否过短。

问题2：收到“Parse error”或无效的JSON响应

• 排查：
  1. 粘包/拆包：这是TCP传输最常见的问题。确保你的TcpTransport正确实现了长度前缀法。可以在发送和接收端打印原始十六进制数据，检查帧边界是否正确。
  2. 编码问题：确保发送的JSON字符串是UTF-8编码，且没有非法字符。
  3. 并发写入：确保没有多个线程同时向同一个TCP连接写入数据，这会导致数据交织。客户端发送请求应串行化或使用发送队列。

问题3：方法调用成功，但返回结果不对

• 排查：
  1. 参数格式：检查客户端发送的params格式是否与服务器端方法期望的一致。是JSON对象{}还是数组[]？服务器端MethodRegistry的参数解析逻辑是否匹配。
  2. 数据类型转换：JSON数字到C++int/double的转换是否有精度损失？字符串是否正确处理了Unicode？
  3. 数据库查询：直接登录MySQL，用同样的参数手动执行SQL，验证结果。

问题4：Docker容器内服务无法连接MySQL容器

• 排查：
  1. 服务发现：在Docker Compose中，使用服务名（mysql）作为主机名，而不是localhost。确保MYSQL_URI环境变量正确设置为mysqlx://root:password@mysql:33060/user_db。
  2. MySQL X Plugin：确保MySQL镜像启动了X Plugin（我们的连接使用X协议端口33060）。检查MySQL容器的日志。
  3. 依赖启动顺序：在docker-compose.yml中使用了depends_on，但这只保证容器启动顺序，不保证MySQL服务就绪。需要在服务器启动脚本中加入对MySQL端口的健康检查，等待其就绪后再启动RPC服务。

5.3 进阶扩展方向

一个基础的JSON-RPC++库搭建完成后，可以根据实际需求向不同方向深化：

1. 服务发现与负载均衡：集成Consul、Etcd或Nacos，客户端不再写死服务器地址，而是从注册中心动态获取可用服务节点列表。
2. 身份认证与授权：在传输层（如TLS）或协议层（在params外增加auth字段）加入Token或签名验证。
3. 监控与链路追踪：集成OpenTelemetry，自动在RPC调用中注入和传递TraceId、SpanId，并上报到Jaeger或Zipkin。
4. 代码生成与IDL：定义接口描述语言（IDL），自动生成服务器端骨架代码和客户端桩代码，提高开发效率，保证类型安全。这是像gRPC、Thrift等成熟RPC框架的核心特性。
5. 支持更多传输协议：除了TCP和WebSocket，可以实现HTTP传输（将JSON-RPC作为HTTP POST请求的body），这样任何能发HTTP请求的客户端都能调用，兼容性极广。

从零构建一个生产可用的RPC框架是一项系统工程，本教程为你铺平了核心道路。最重要的是理解其设计哲学：协议与传输分离、异步非阻塞、类型安全与易用性平衡。当你亲手实现一遍，再去看那些开源的大型RPC框架源码，你会发现很多设计都是相通的。