# NewLife.Remoting - 统一高性能远程通信框架 (RPC + HTTP + WebSocket + SRMP)         > 简单、统一、可扩展、跨多目标框架 (net45 ~ net10.0) 的远程通信基础设施。单一生态内同时覆盖： > - 二进制高性能 RPC (长连接 / 主动下发 / 海量连接与吞吐) > - 标准 HTTP / REST (易集群 / 生态丰富 / 负载均衡) > - WebSocket 指令下发与事件推送 > - SRMP (Simple Remote Message Protocol) 远程消息协议 > - 统一应用客户端基类 ClientBase（登录 / 心跳 / 升级 / 指令 / 事件） > > 源码：https://github.com/NewLifeX/NewLife.Remoting > NuGet：`NewLife.Remoting` / `NewLife.Remoting.Extensions` --- ## 🔥 RPC 核心亮点与快速用例 **5 行服务端，5 行客户端，即刻跑通 RPC 调用：** ```csharp // === 服务端 === var server = new ApiServer(12345); server.Register<MyController>(); server.Start(); public class MyController : ApiController { public String Ping(String name) => $"Hello {name}, {DateTime.Now:HH:mm:ss}"; // 流式推送：返回 IAsyncEnumerable<T> 自动逐条下发 public async IAsyncEnumerable<String> StreamLogs(Int32 count) { for (var i = 0; i < count; i++) { await Task.Delay(100); yield return $"Log #{i}: {DateTime.Now:HH:mm:ss}"; } } } // === 客户端 === var client = new ApiClient("tcp://127.0.0.1:12345"); client.Open(); // 普通调用 var rs = await client.InvokeAsync<String>("My/Ping", new { name = "dev" }); // 流式调用 — 逐条接收服务端推送 await foreach (var log in client.InvokeStreamAsync<String>("My/StreamLogs", new { count = 10 })) Console.WriteLine(log); // 元数据传递（自动注入 TraceId） client.Headers["TenantId"] = "tenant-01"; ``` | 维度 | 指标 | |------|------| | 🔌 **传输协议** | TCP / UDP / HTTP / WebSocket 统一 API | | ⚡ **单次 RPC 延迟** | ~41 μs（端到端，含 TCP 往返 + JSON 编解码） | | 🚀 **RPC 吞吐** | 典型 10 万 TPS，实验峰值 **2266 万 TPS** | | 🔗 **TCP 长连接** | 典型 1 万，实验峰值 **400 万** | | 📦 **序列化** | JSON（默认）+ IPacket 二进制直通 | | 🌊 **流式调用** | Server-Streaming（`IAsyncEnumerable<T>`），HTTP 自动兼容 SSE | | 🏷️ **元数据传递** | `client.Headers` 字典透传 TraceId/TenantId 等 | | 🔁 **集群与重试** | 故障转移 / 连接池 / 自动重试 / 401 自动重登 | | 🛡️ **可观测性** | 慢调用日志、`ITracer` 链路追踪、`ICounter` 统计 | | 🎯 **框架兼容** | net45 / net461 / netstandard2.0 / netstandard2.1 / net5.0 ~ net10.0 | --- ## 目录导航 - [NewLife.Remoting - 统一高性能远程通信框架 (RPC + HTTP + WebSocket + SRMP)](/NewLife/NewLife.Remoting/Blob/master/#newliferemoting---统一高性能远程通信框架-rpc--http--websocket--srmp) - [🔥 RPC 核心亮点与快速用例](/NewLife/NewLife.Remoting/Blob/master/#-rpc-核心亮点与快速用例) - [目录导航](/NewLife/NewLife.Remoting/Blob/master/#目录导航) - [核心特性](/NewLife/NewLife.Remoting/Blob/master/#核心特性) - [架构概览](/NewLife/NewLife.Remoting/Blob/master/#架构概览) - [适用场景对比](/NewLife/NewLife.Remoting/Blob/master/#适用场景对比) - [快速开始](/NewLife/NewLife.Remoting/Blob/master/#快速开始) - [安装模板（推荐）](/NewLife/NewLife.Remoting/Blob/master/#安装模板推荐) - [RPC 服务端最小示例](/NewLife/NewLife.Remoting/Blob/master/#rpc-服务端最小示例) - [RPC 客户端调用示例](/NewLife/NewLife.Remoting/Blob/master/#rpc-客户端调用示例) - [HTTP + WebSocket 设备接入](/NewLife/NewLife.Remoting/Blob/master/#http--websocket-设备接入) - [Server-Streaming 流式调用](/NewLife/NewLife.Remoting/Blob/master/#server-streaming-流式调用) - [元数据传递（Headers）](/NewLife/NewLife.Remoting/Blob/master/#元数据传递headers) - [统一客户端 ClientBase 能力](/NewLife/NewLife.Remoting/Blob/master/#统一客户端-clientbase-能力) - [SRMP 协议简介](/NewLife/NewLife.Remoting/Blob/master/#srmp-协议简介) - [性能指标](/NewLife/NewLife.Remoting/Blob/master/#性能指标) - [认证与安全](/NewLife/NewLife.Remoting/Blob/master/#认证与安全) - [扩展与二次开发](/NewLife/NewLife.Remoting/Blob/master/#扩展与二次开发) - [与其它 NewLife 组件协同](/NewLife/NewLife.Remoting/Blob/master/#与其它-newlife-组件协同) - [多目标框架兼容策略](/NewLife/NewLife.Remoting/Blob/master/#多目标框架兼容策略) - [项目生态矩阵](/NewLife/NewLife.Remoting/Blob/master/#项目生态矩阵) - [贡献与反馈](/NewLife/NewLife.Remoting/Blob/master/#贡献与反馈) - [快速命令回顾](/NewLife/NewLife.Remoting/Blob/master/#快速命令回顾) - [新生命项目矩阵](/NewLife/NewLife.Remoting/Blob/master/#新生命项目矩阵) - [团队与版权](/NewLife/NewLife.Remoting/Blob/master/#团队与版权) - [变更记录](/NewLife/NewLife.Remoting/Blob/master/#变更记录) - [License](/NewLife/NewLife.Remoting/Blob/master/#license) --- ## 核心特性 1. 双架构：同一套模型同时支持【高性能二进制 RPC】与【标准 HTTP/REST】 2. 海量连接：单机典型 1 万 TCP 长连接，实验峰值 400 万；吞吐典型 10 万 TPS，实验峰值 2266 万 TPS（依赖 NewLife.Net 内核） 3. 零第三方重依赖：日志 / 序列化 / 网络栈 / 对象池 均为自研生态，可控可裁剪 4. 可观测性：内置性能统计、慢调用跟踪、分布式追踪接口 (ITracer) 5. 统一客户端生命周期：登录、心跳、升级、指令、事件上报 一站式封装 6. SRMP 协议：Header + Body 简洁帧格式，支持粘拆包、双向消息、OneWay、Reply 标识 7. 安全：令牌颁发 + 可插拔密码/签名提供者 + Token 续期策略 8. WebSocket 通道：HTTP 架构下的实时指令下发与推送 9. 控制器模型：与 WebApi 类似的 Controller/Action 调用体验（ApiServer / ApiController） 10. **流式调用**：Action 返回 `IAsyncEnumerable<T>` 自动 Server-Streaming，HTTP 兼容 SSE，客户端 `await foreach` 逐条接收 11. **元数据传递**：`client.Headers` 字典注入 TraceId/TenantId 等上下文，服务端自动提取 12. 扩展组件：`NewLife.Remoting.Extensions` 提供 ASP.NET Core 设备接入基类、令牌服务、会话管理、模型绑定器 --- ## 架构概览 ``` +-------------------+ +--------------------+ | 客户端 ClientBase | | 服务端 ApiServer | | (ApiClient/HTTP) | <--- SRMP/TCP ---> | 控制器/Handler | +---------+---------+ +----+-----------+----+ | HTTP/REST 负载均衡 | 注册服务/依赖注入 v v +-------------------+ WebSocket +--------------------------+ | ApiHttpClient |<------------->| BaseDeviceController | +-------------------+ 指令/事件 +-----------+--------------+ | TokenService | SessionManager v +---------------+ | 业务/存储/缓存 | +---------------+ ``` - RPC：长连接 / 二进制 / 低开销 / 服务端可主动推送 - HTTP：标准化 / 容易接入网关 / 每次独立认证 / WebSocket 下发指令 - 二者共享：登录模型、心跳语义、令牌机制、序列化策略、事件与指令抽象 --- ## 适用场景对比 | 维度 | RPC 架构 | HTTP 架构 | | ---- | -------- | --------- | | 连接模型 | 长连接 (TCP/UDP) | 短连接 + 可选 WebSocket | | 吞吐/延迟 | 极致性能/低延迟 | 受 HTTP 栈 & 负载均衡影响 | | 推送能力 | 服务端直接下发 | 需 WebSocket 通道 | | 负载均衡 | 客户端挑选一个节点保持 | 请求级（云原生友好） | | 二进制大包 | 友好（自定义序列化） | 不适合（默认 JSON） | | 接入复杂度 | 需要 SDK/协议 | 任意 HTTP 客户端即可 | | 典型场景 | 任务调度、物联网网关、工业采集 | 设备管理平台、通用 REST、混合接入 | --- ## 快速开始 ### 安装模板（推荐） ``` dotnet new install NewLife.Templates ``` ### RPC 服务端最小示例 ``` dotnet new rpcserver --name RpcServer cd RpcServer dotnet run ``` 核心代码（示意）： ```csharp var server = new ApiServer(12345); server.Register(new MyController(), null); // 暴露控制器全部 Action server.Start(); public class MyController : ApiController { public String Ping(String name) => $"Hello {name}, {DateTime.Now:HH:mm:ss}"; } ``` ### RPC 客户端调用示例 ```csharp var client = new ApiClient("tcp://127.0.0.1:12345"); await client.OpenAsync(); var rs = await client.InvokeAsync<String>("My/Ping", new { name = "dev" }); Console.WriteLine(rs); ``` ### HTTP + WebSocket 设备接入 Program.cs 中： ```csharp builder.Services.AddRemoting(); var app = builder.Build(); app.UseRemoting(); app.MapControllers(); app.Run(); public class DeviceController : BaseDeviceController { public DeviceController(IServiceProvider p) : base(p) { } } ``` 客户端使用 ApiHttpClient 登录 + 周期 Ping，服务端可通过 WebSocket 通道下发指令。 ### Server-Streaming 流式调用 Controller Action 返回 `IAsyncEnumerable<T>` 时，框架自动以流式模式逐条推送，客户端 `await foreach` 逐条接收： ```csharp // 服务端 — 逐条推送日志 public async IAsyncEnumerable<String> GetLogs(Int32 count) { for (var i = 0; i < count; i++) { await Task.Delay(100); yield return $"Log #{i}: {DateTime.Now:HH:mm:ss}"; } } // 客户端 — 逐条接收 await foreach (var log in client.InvokeStreamAsync<String>("My/GetLogs", new { count = 10 })) Console.WriteLine(log); ``` - TCP/SRMP：二进制帧逐条下发，首帧 ~41μs，后续帧 <1ms - HTTP：自动兼容 SSE（`text/event-stream`），浏览器原生支持 - 支持 `CancellationToken` 中途取消，客户端断开时服务端自动停止推送 ### 元数据传递（Headers） `ApiClient.Headers` 字典在每次调用时自动注入到参数字典，服务端可通过 `ControllerContext.Current.Items` 读取： ```csharp // 客户端 client.Headers["TenantId"] = "tenant-01"; var rs = await client.InvokeAsync<String>("My/Ping", new { name = "dev" }); // 服务端 var headers = ControllerContext.Current.Items; var tenantId = headers?["TenantId"] as String; ``` - 常用场景：分布式链路追踪（TraceId 自动注入）、多租户标识透传 - 不改 `IMessage` 接口，不影响协议兼容性 --- ## 统一客户端 ClientBase 能力 ClientBase 抽象了设备 / 节点 / 应用常见生命周期： - 登录：多种模式（应用 AppId/AppSecret、设备 Code/Secret、OAuth） - 心跳：带服务器时间、令牌续期、保持在线状态 - 升级：统一 Upgrade 查询，返回版本与下载地址（自动补全绝对路径） - 指令：RPC 直接下发；HTTP 通过 WebSocket 推送；客户端统一 CommandReply 回执 - 事件：批量上报 EventModel[] - 安全：内置时间戳 + 签名/令牌 验证流程 --- ## SRMP 协议简介 SRMP (Simple Remote Message Protocol)： - 面向消息的远程调用与推送协议 - 支持标志位：OneWay / Reply / Streaming / EndOfStream - 设计目标：比 HTTP 更低的开销；比原始 TCP 更易解析与调试 - 在 ApiNetServer 中通过 WebSocketServerCodec + 标准消息编解码器组合使用 详见：`Doc/SRMP.MD`。 --- ## 性能指标 | 指标 | 典型值 | 实验峰值 | 说明 | | ---- | ------ | -------- | ---- | | TCP 长连接数 | 10,000 | 4,000,000 | 依赖内核与系统参数调优 | | RPC 吞吐 | 100,000 TPS | 22,660,000 TPS | 简单回显场景，基于 NewLife.Net | | HTTP 并发连接 | 1,000 | (可水平扩展) | 受 Kestrel/网关限制 | | 心跳开销 | 微秒级 | - | 轻量协议 + 对象池复用 | > 建议结合实际业务压测，关注序列化体积与对象分配。 --- ## 认证与安全 - 登录：设备 / 应用 / OAuth 三模式；成功返回访问令牌 + 过期时间 - 令牌续期：心跳内置检测，10 分钟内到期可自动刷新（可扩展策略） - 密钥保护：SaltPasswordProvider（可替换）避免明文密钥直接传输 - 会话管理：SessionManager（WebSocket 长连接登记、关闭释放） - 异常：统一 ApiException + ApiCode，避免泄漏内部实现细节 --- ## 扩展与二次开发 可扩展点： 1. 自定义序列化：实现 IJsonHost / 二进制编码器替换 Encoder 2. 自定义认证：替换 TokenService 或 IPasswordProvider 3. 控制器解析：通过 ApiServer.Register(controller, method) 4. 消息拦截：订阅 ApiServer.Received 统一埋点 / 鉴权 / 限流 5. 协议扩展：在 ApiNetServer.Init 中追加自定义 Codec 6. 事件与指令：实现 IDeviceService / 使用 CommandReply & PostEvents 7. 日志与追踪：注入 ILog / ITracer，实现链路关联 --- ## 与其它 NewLife 组件协同 | 组件 | 协同价值 | | ---- | -------- | | NewLife.Core | 日志、配置、序列化、对象池、TimerX、性能追踪 | | NewLife.Net | 高性能网络栈、WebSocket/编码器、端口复用 | | NewLife.Redis | 分布式缓存 / 消息队列，扩展会话共享或推送 fanout | | Stardust | 节点注册、配置中心、APM、发布中心；可托管 ApiServer 节点 | | AntJob | 使用 ClientBase 接入任务调度与分布式计算 | | NewLife.MQTT / Modbus / IoT | 设备层协议采集后通过 Remoting 上行 | --- ## 多目标框架兼容策略 - 支持：net45 / net461 / netstandard2.0 / netstandard2.1 / net5.0~net10.0 - 通过条件编译隔离新旧 API（Span / ValueTask / Socket 特性等） - 遵循：不主动移除旧 TFM；新增功能优先判断可用性再启用 --- ## 项目生态矩阵 完整生态与说明见下方 [新生命项目矩阵](/NewLife/NewLife.Remoting/Blob/master/#新生命项目矩阵)。Remoting 作为“通信基座”横向衔接 网关设备接入 / 调度平台 / 分布式服务治理 / IoT 协议栈。 --- ## 贡献与反馈 欢迎：Bug 反馈 / 性能优化 PR / 新协议编解码 / 控制器示例 / 文档补充。 提交前请阅读 `.github/copilot-instructions.md` 了解编码规范 & Multi‑TFM 原则。 Issue 讨论请尽量提供：运行环境、目标框架、最小可复现代码、日志摘要。 --- ## 快速命令回顾 ``` # 安装模板 dotnet new install NewLife.Templates # 创建 RPC 服务端骨架 dotnet new rpcserver --name RpcServer # 运行 dotnet run ``` --- ## 新生命项目矩阵 各项目默认支持 net9.0/netstandard2.1/netstandard2.0/net4.62/net4.5，旧版（2024.0801）支持 net4.0/net2.0 | 项目 | 年份 | 说明 | | :--: | :--: | ---- | | [NewLife.Core](https://github.com/NewLifeX/X) | 2002 | 核心库，日志、配置、缓存、网络、序列化、APM性能追踪 | | [NewLife.XCode](https://github.com/NewLifeX/NewLife.XCode) | 2005 | 大数据中间件，单表百亿级，自动分表，读写分离 | | [NewLife.Net](https://github.com/NewLifeX/NewLife.Net) | 2005 | 网络库，2266万 tps / 百万连接 | | [NewLife.Remoting](https://github.com/NewLifeX/NewLife.Remoting) | 2011 | 本项目，双协议通信框架 | | [NewLife.Cube](https://github.com/NewLifeX/NewLife.Cube) | 2010 | 快速开发平台，权限 / OAuth / SSO | | [NewLife.Agent](https://github.com/NewLifeX/NewLife.Agent) | 2008 | 服务安装 / 守护进程 / Systemd | | [NewLife.Zero](https://github.com/NewLifeX/NewLife.Zero) | 2020 | 项目脚手架模板集合 | | [NewLife.Redis](https://github.com/NewLifeX/NewLife.Redis) | 2017 | 高性能 Redis 客户端/消息队列 | | [NewLife.RocketMQ](https://github.com/NewLifeX/NewLife.RocketMQ) | 2018 | 纯托管 RocketMQ 客户端 | | [NewLife.MQTT](https://github.com/NewLifeX/NewLife.MQTT) | 2019 | 物联网 MqttClient/MqttServer | | [NewLife.IoT](https://github.com/NewLifeX/NewLife.IoT) | 2022 | IoT 通信标准模型库 | | [NewLife.Modbus](https://github.com/NewLifeX/NewLife.Modbus) | 2022 | Modbus 协议族 | | [NewLife.Siemens](https://github.com/NewLifeX/NewLife.Siemens) | 2022 | 西门子 PLC 通信 | | [NewLife.Map](https://github.com/NewLifeX/NewLife.Map) | 2022 | 地图聚合组件 | | [NewLife.Audio](https://github.com/NewLifeX/NewLife.Audio) | 2023 | 音频编解码 | | Stardust | 2018 | 分布式服务平台 (注册/配置/APM/发布) | | AntJob | 2019 | 分布式大数据计算平台 | | 等等 | - | 更多参见官网 | --- ## 团队与版权  新生命团队（NewLife）成立于 2002 年，80+ 开源项目，NuGet 累计下载 400+ 万。全部项目采用 MIT 协议，可自由修改再发行（无需声明来源）。 网站：https://newlifex.com 开源：https://github.com/NewLifeX QQ群：1600800 / 1600838 > `新生命团队始于2002年，部分开源项目具有20年以上历史，源码库保留2010年以来全部记录。` 微信公众号：  --- ## 变更记录 请关注 Release / Tag 说明或提交历史。后续可引入 CHANGELOG 简述关键性能与兼容性变更。 --- ## License MIT © NewLife. 欢迎商用与二次开发。