# 分布式 RPC 通信框架

**Repository Path**: gan2729583308/json-rpc-framework

## Basic Information

- **Project Name**: 分布式 RPC 通信框架
- **Description**: 一个轻量级、高效、跨语言的JSON-RPC框架，支持多种传输协议，适用于构建高性能的分布式系统和微服务架构。
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-26
- **Last Updated**: 2025-12-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于 Muduo 的高性能 JSON-RPC 框架

![Language](https://img.shields.io/badge/language-C++11-orange.svg)
![Platform](https://img.shields.io/badge/platform-Linux-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![输入图片说明](src/common/rpc2.drawio.png)
## 📖 项目简介

**JSON-RPC** 是一个轻量级、高性能的分布式 RPC (Remote Procedure Call) 框架。底通信层基于 [Muduo](https://github.com/chenshuo/muduo) 网络库实现，采用 JSON (JsonCpp) 作为序列化协议。

该框架不仅支持标准的 RPC 调用，还内置了**服务注册与发现中心**以及**消息队列（发布/订阅）**功能，能够满足微服务架构下的基本通信需求。

## ✨ 核心特性

*   **高性能通信**: 基于 Muduo 的 Reactor 模型（Epoll + 线程池），支持高并发连接。
*   **灵活的 RPC 调用**:
    *   **同步调用**: 阻塞等待结果。
    *   **异步调用**: 返回 `std::future`，支持延时获取结果。
    *   **回调模式**: 传入回调函数，非阻塞处理响应。
*   **服务治理**:
    *   内置 **RegistryServer**（注册中心），支持服务自动注册与发现。
    *   支持服务上线/下线通知，客户端自动更新服务地址缓存。
    *   简单的负载均衡策略（轮询）。
*   **发布/订阅模型**: 提供 Topic Server，支持消息的广播、订阅、取消订阅及主题管理。
*   **参数校验**: 服务端支持强类型的参数校验（Bool, Int, String, Array, Object 等），减少非法请求进入业务逻辑。
*   **协议**: 自定义 Length-Value 协议，解决 TCP 粘包/拆包问题。

## 🛠️ 环境依赖

在编译和运行本项目前，请确保您的 Linux 环境已安装以下依赖：

*   **C++ 编译器**: 支持 C++11 及以上 (g++)
*   **Muduo 网络库**: [安装教程](https://github.com/chenshuo/muduo)
*   **JsonCpp**:用于 JSON 序列化与反序列化
*   **CMake**: 构建工具

**Ubuntu/Debian 安装示例:**

```bash
sudo apt-get install libmuduo-dev libjsoncpp-dev cmake g++
```

## 🚀 快速开始

### 1. 定义与发布 RPC 服务 (Server)

服务端需要定义具体的业务逻辑，并通过 `ServiceDescribeFactory` 描述接口签名（参数类型、返回值类型）。

```cpp
#include "rpc_server.hpp"
#include <iostream>

using namespace gchrpc;
using namespace gchrpc::server;

// 1. 定义业务函数
void Add(const Json::Value& params, Json::Value& result) {
    int a = params["a"].asInt();
    int b = params["b"].asInt();
    result = a + b;
    std::cout << "Server call Add: " << a << " + " << b << " = " << result.asInt() << std::endl;
}

int main() {
    // 2. 描述服务接口
    ServiceDescribeFactory factory;
    factory.SetMethodName("add"); // 方法名
    factory.SetParamsDesc("a", VType::INTEGRAL); // 参数 a，整型
    factory.SetParamsDesc("b", VType::INTEGRAL); // 参数 b，整型
    factory.SetReturnVtype(VType::INTEGRAL);     // 返回值类型
    factory.SetServiceDescribe(Add);             // 绑定回调

    // 3. 启动 RPC 服务器
    // 参数: 绑定地址, 是否启用注册中心, 注册中心地址
    Address local_addr = {"127.0.0.1", 8080};
    Address reg_addr = {"127.0.0.1", 9999}; 
    
    // 启用服务注册
    RpcServer server(local_addr, true, reg_addr);
    
    // 4. 注册方法并启动
    server.RegistryMethod(factory.build());
    std::cout << "RPC Server started at 8080..." << std::endl;
    server.Start();

    return 0;
}
```

### 2. 调用 RPC 服务 (Client)

客户端支持同步、异步（Future）和回调三种模式。

```cpp
#include "rpc_client.hpp"
#include <iostream>

using namespace gchrpc;
using namespace gchrpc::client;

int main() {
    // 1. 初始化客户端
    // 参数: 是否启用服务发现, 注册中心IP, 注册中心端口
    // 如果不启用服务发现，则直连指定的 RPC Server
    RpcClient client(true, "127.0.0.1", 9999);

    Json::Value params;
    params["a"] = 10;
    params["b"] = 20;

    // --- 方式一：同步调用 ---
    Json::Value result;
    if (client.call("add", params, result)) {
        std::cout << "Sync Result: " << result.asInt() << std::endl;
    }

    // --- 方式二：异步 Future 调用 ---
    RpcCaller::JsonAsyncResponse future_res;
    if (client.call("add", params, future_res)) {
        // 做一些其他事情...
        Json::Value async_val = future_res.get(); // 阻塞获取
        std::cout << "Async Result: " << async_val.asInt() << std::endl;
    }

    // --- 方式三：回调模式 ---
    client.call("add", params, [](const Json::Value& res){
        std::cout << "Callback Result: " << res.asInt() << std::endl;
    });
    
    // 保持主线程运行以等待回调
    getchar();
    return 0;
}
```

### 3. 启动注册中心 (Registry Server)

如果使用了服务发现功能，需要先启动注册中心。

```cpp
#include "rpc_server.hpp"

using namespace gchrpc::server;

int main() {
    // 监听 9999 端口
    RegistryServer reg_server(9999);
    std::cout << "Registry Server started at 9999..." << std::endl;
    reg_server.Start();
    return 0;
}
```

### 4. 发布/订阅 (Pub/Sub)

GCHRPC 还包含一个轻量级的消息队列功能。

**Topic Server (消息代理):**
```cpp
#include "rpc_server.hpp"
int main() {
    gchrpc::server::TopicServer server(8888);
    server.Start();
    return 0;
}
```

**Topic Client (订阅与发布):**
```cpp
#include "rpc_client.hpp"

using namespace gchrpc::client;

int main() {
    TopicClient client("127.0.0.1", 8888);

    // 1. 创建主题
    client.Create("news");

    // 2. 订阅主题
    client.Subscribe("news", [](const std::string& key, const std::string& msg){
        std::cout << "Received on [" << key << "]: " << msg << std::endl;
    });

    // 3. 发布消息
    client.Publish("news", "Hello GCHRPC Topic!");

    getchar();
    return 0;
}
```

## 📂 项目结构

```text
.
├── common
│   ├── abstract.hpp       # 抽象基类 (Message, Connection, Server, Client)
│   ├── detail.hpp         # 工具类 (日志, UUID, JSON封装)
│   ├── dispatcher.hpp     # 消息分发器 (根据消息类型回调)
│   ├── fields.hpp         # 协议常量与枚举定义
│   ├── message.hpp        # 协议消息定义 (Request/Response)
│   └── net.hpp            # 网络层封装 (基于 Muduo)
├── server
│   ├── rpc_registry.hpp   # 服务端-注册中心逻辑
│   ├── rpc_router.hpp     # RPC 方法路由与参数校验
│   ├── rpc_server.hpp     # 各类 Server 入口 (RpcServer, RegistryServer, TopicServer)
│   └── rpc_topic.hpp      # 服务端-Topic 管理逻辑
└── client
    ├── requestor.hpp      # 请求发起者 (管理 Pending 请求)
    ├── rpc_caller.hpp     # RPC 调用逻辑封装
    ├── rpc_client.hpp     # 各类 Client 入口
    ├── rpc_registry.hpp   # 客户端-服务发现逻辑
    └── rpc_topic.hpp      # 客户端-Topic 逻辑
```

## ⚙️ 编译构建

建议使用 CMake 进行构建。创建 `CMakeLists.txt`：

```cmake
cmake_minimum_required(VERSION 3.0)
project(gchrpc_demo)

set(CMAKE_CXX_STANDARD 11)

# 查找依赖库
find_library(MUDUO_NET muduo_net)
find_library(MUDUO_BASE muduo_base)
find_library(JSONCPP jsoncpp)
find_package(Threads)

# 包含头文件路径
include_directories(${PROJECT_SOURCE_DIR})

# 编译示例
add_executable(server_main server_main.cpp)
target_link_libraries(server_main ${MUDUO_NET} ${MUDUO_BASE} ${JSONCPP} ${CMAKE_THREAD_LIBS_INIT})

add_executable(client_main client_main.cpp)
target_link_libraries(client_main ${MUDUO_NET} ${MUDUO_BASE} ${JSONCPP} ${CMAKE_THREAD_LIBS_INIT})
```

构建命令：

```bash
mkdir build && cd build
cmake ..
make
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 开源协议

MIT License.