ApeFree.ApeRpc.BytesIO 0.0.3-alpha61009

ApeFree.ApeRpc.BytesIO

ApeFree.ApeRpc.BytesIO 是面向点对点直连通信场景的高性能轻量级 RPC 类库。基于 STTech.BytesIO 统一网络通信层抽象，将 TCP、IPC（命名管道/共享内存）、串口（SerialPort）等物理/逻辑传输通道完全标准化为 BytesClient，实现统一的全双工远程方法调用与事件订阅。

相比基于 Broker 集中代理转发的 RPC 实现（如 MQTT），ApeFree.ApeRpc.BytesIO 专注于去中心化、低延迟、点对点直连的高吞吐传输，并深度融合 BytesIO 的流式分包（Unpacker）与请求-响应匹配机制（MatchHandler），有效杜绝流传输过程中的粘包断包与乱序问题。

🌟 核心特性

• 多通信渠道无缝抽象：底层基于 BytesClient 抽象，无论是本地进程间 IPC（NamedPipe/SharedMemory）、网络 TCP 还是工控硬件串口 SerialPort，均以完全一致的 API 快速接入。
• 零拷贝流式分包协议：内置专用二进制协议帧（2 字节 Magic AR + 4 字节总长度 + 结构化元数据头 + Jbin/Json 序列化载荷），配合 BytesRpcUnpacker 自动实现流式数据切片与断帧对齐。
• MatchHandler 全双工精确匹配：基于 ReplyMatchHandler 在并发全双工链路中进行请求与响应配对，完美过滤心跳包、主动事件推送及交叉响应。
• 动态代理与远程事件：采用透明接口动态代理（DispatchProxy），支持方法超时限制（[RpcTimeout]）、只读缓存（[InvariableProperty]）以及服务端事件主动推送与强制订阅（[RpcEvent]）。
• 灵活的路由与服务端绑定：支持单通道直连、多服务目标路由表（WithServiceRoute）、多终端路由表以及服务端监听绑定（BindServer / WithServer）。
• 双协议数据载荷：支持高性能二进制紧凑格式 JbinRpc 与通用文本格式 JsonRpc，并支持运行时按通道或终端自由切换。

📦 安装方式

通过 .NET CLI 安装：

dotnet add package ApeFree.ApeRpc.BytesIO

通过 Package Manager 控制台安装：

Install-Package ApeFree.ApeRpc.BytesIO

🚀 快速上手

1. 定义公共服务契约接口

using ApeFree.ApeRpc.Attributes;
using System;

public interface ICalculatorService
{
    // 同步计算方法
    int Add(int a, int b);

    // 带超时控制的方法（单位毫秒）
    [RpcTimeout(1000)]
    string HeavyOperation();

    // 远程事件
    event EventHandler<string> StatusChanged;
}

2. 服务端实现与注册（以 TCP 服务为例）

using ApeFree.ApeRpc;
using ApeFree.ApeRpc.BytesIO;
using STTech.BytesIO.Tcp;
using System;

public class CalculatorService : ICalculatorService
{
    public event EventHandler<string> StatusChanged;

    public int Add(int a, int b) => a + b;

    public string HeavyOperation() => "Done";

    public void Report(string message) => StatusChanged?.Invoke(this, message);
}

// 初始化服务端终端
var serverTerminal = new RpcTerminal(new TerminalInfo { Name = "ServerNode" });

// 创建 TCP 服务器并绑定至 BytesRpc 插件
var tcpServer = new TcpServer { Port = 8899 };
var serverAddon = new BytesRpcTerminalAddon(serverTerminal);
serverAddon.BindServer(tcpServer);

// 注册本地服务实例
var serviceImpl = new CalculatorService();
serverTerminal.RegisterService(serviceImpl);

// 启动 TCP 监听
await tcpServer.StartAsync();

3. 客户端直连与调用（以 TCP 客户端为例）

using ApeFree.ApeRpc;
using ApeFree.ApeRpc.BytesIO;
using STTech.BytesIO.Tcp;
using System;

// 初始化客户端终端
var clientTerminal = new RpcTerminal(new TerminalInfo { Name = "ClientNode" });

// 创建 TCP 客户端并配置为默认通信通道
var tcpClient = new TcpClient { Host = "127.0.0.1", Port = 8899 };
new BytesRpcTerminalAddon(clientTerminal, tcpClient);

// 建立连接
await tcpClient.ConnectAsync();

// 获取远程服务透明代理
var proxy = clientTerminal.GetService<ICalculatorService>(nameof(CalculatorService));

// 订阅远程服务端推送的事件
proxy.StatusChanged += (sender, msg) =>
{
    Console.WriteLine($"收到服务端事件: {msg}");
};

// 远程调用
int result = proxy.Add(10, 20);
Console.WriteLine($"计算结果: {result}"); // 输出: 30

💡 高级场景

场景 A：本地进程间通信（IPC / 命名管道）

对于同一台主机上的不同跨进程通信，只需切换为 IpcClient 即可享有超低延迟的进程间 RPC：

using STTech.BytesIO.Ipc;

// 客户端使用命名管道直连服务端
var ipcClient = new NamedPipeIpcClient("MyRpcPipeName");
clientAddon.WithDefaultClient(ipcClient);
await ipcClient.ConnectAsync();

var proxy = clientTerminal.GetService<ICalculatorService>(nameof(CalculatorService));
int sum = proxy.Add(5, 6);

场景 B：工控串口通信（SerialPort）

在嵌入式或工业上位机场景下，直接通过串口进行 RPC 方法调用与硬件参数读写：

using STTech.BytesIO.Serial;

var serialClient = new SerialClient
{
    PortName = "COM3",
    BaudRate = 115200
};
clientAddon.WithDefaultClient(serialClient);
serialClient.Connect();

场景 C：网关多服务客户端路由

网关或集中管理节点可以通过 WithServiceRoute，将不同服务的 RPC 请求精准分发至不同的客户端通道：

var gateway = new RpcTerminal(new TerminalInfo { Name = "Gateway" });
new BytesRpcTerminalAddon(gateway)
    .WithServiceRoute("AuthService", tcpClientAuth)
    .WithServiceRoute("PaymentService", tcpClientPayment)
    .WithServiceRoute("HardwareService", serialClient);

// 自动按服务名路由到对应底层信道
var auth = gateway.GetService<IAuthService>("AuthService");
var payment = gateway.GetService<IPaymentService>("PaymentService");

🧩 协议规范

ApeFree.ApeRpc.BytesIO 采用紧凑高效的二进制协议帧格式：

+------------+-----------------+--------------+--------------+------------------+
| Magic (2B) | TotalLength(4B) | MsgType (1B) | Format (1B)  | RequestId (8B)   |
| 0x41, 0x52 | Big-Endian uint | Enum Byte    | Jbin / Json  | Big-Endian ulong |
+------------+-----------------+--------------+--------------+------------------+
| SrcLen(2B) | Source (UTF-8)  | DstLen (2B)  | Dest (UTF-8) | SvcLen (2B)      |
+------------+-----------------+--------------+--------------+------------------+
| ServiceName (UTF-8)          | Payload (Variable Length)                      |
+------------------------------+------------------------------------------------+

• Magic：固定魔数 0x41, 0x52（即 ASCII 'A','R'），用于流式通信中自动定位合法帧起始边界。
• TotalLength：4 字节大端整数，标识从魔数开始至整个数据包结束的总字节长度。
• Unpacker 集成：利用 BytesIO Unpacker<BytesRpcPacket> 内存切片与缓冲区自动扩展机制，零拷贝拆包。

📄 开源许可证

本项目基于 Apache License 2.0 许可证开源。