WSHub.Abstractions 0.0.2

WSHub

基于 .NET 的现代 WebSocket 即时通讯服务框架，参考并改进自 FreeIM。

职责清晰、可扩展、支持多节点部署，适用于游戏、IM、实时协作等场景。

特性

• 发送与投递分离 — IMessageHandler（发送） + IMessageDeliveryHandler（投递）独立管道
• 多节点支持 — 水平扩展，通过 Redis（FreeRedis）或 InMemory 进行消息路由
• 后端语义一致 — InMemory 与 FreeRedis 共用同一套 ChannelBus 键、引用计数订阅/退订与本地投递语义，并由 RoomDemoFreeRedisE2ETests 在真实 Redis 上交叉验收
• 多租户隔离 — 租户段由 Hub 强制注入总线键（{prefix}:ch:{tenantId}:{channelId}），业务层无法绕过
• 二进制消息 — byte[] 管道 + 路由头（0xFE），支持 protobuf
• 连接收口 — ConnectionCloser 是断连与空闲回收的唯一路径：停发送队列 → 退频道 → 注销 presence → 关 socket
• 活跃度保活 + 回板兜底 — 接收循环/心跳刷新 connIndex TTL；进程崩溃由宿主周期任务清理
• 事件机制 — 上线/下线/断连/频道进出事件
• 多目标框架 — net8.0 (LTS) / net9.0 / net10.0
• Native AOT — InMemory 模式支持 Docker AOT 部署
• 测试规模 — 662 个测试（单元 + Testcontainers/Redis 集成 + AOT 容器，详见 CI）

快速开始

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWSHub<long>(options =>
{
    options.KeyPrefix = "wshub_v1";
    options.Servers = new[] { "localhost:5299" };
    options.Server = "localhost:5299";
})
.AddClientIdConverter<long, LongClientIdConverter>()
.UseInMemoryStorage<long>()       // 开发环境；生产用 .UseFreeRedisStorage(redis)
.AddDefaultHandlers<long>();      // 一键注册 Handler + Dispatcher + 后台服务

var app = builder.Build();
app.UseWebSockets();

app.Map("/ws/{tenantId?}", async (string? tenantId, HttpContext context) =>
{
    var handler = context.RequestServices.GetRequiredService<WebSocketConnectionHandler<long>>();
    await handler.HandleAsync(tenantId, context);
});

app.Run();

完整示例见 samples/MinimalApiSample/。

文档

架构概览

客户端 WebSocket ──→ ProcessClientMessage ──→ MessageHandlerDispatcher ──→ IMessageHandler (发送)
                                                                                │
应用层主动发送 ──→ IApplicationMessageService ──→ MessageHandlerDispatcher ──→ IMessageHandler (发送)
                                                                                │
                                                                        IMessagePublisher
                                                                                │
                                                                    Redis / InMemory 消息总线
                                                                                │
                                                                        IMessageListener
                                                                                │
                                                                        HandleIncomingMessage
                                                                                │
                                                                        MessageDeliveryDispatcher ──→ IMessageDeliveryHandler (投递)
                                                                                                        │
                                                                                                ConnectionManager ──→ WebSocket

项目结构

WSHub/
├── src/
│   ├── WSHub.Abstractions/       # 接口、模型、Options
│   ├── WSHub.AspNetCore/         # ASP.NET Core 集成
│   ├── WSHub.Host/              # Control HTTP API 独立宿主
│   ├── WSHub.InMemory/           # InMemory 存储后端（开发/测试）
│   └── WSHub.FreeRedis/          # FreeRedis 存储后端（生产/多节点）
├── samples/
│   ├── MinimalApiSample/         # 基础示例 + 测试页面
│   ├── ImDemo/                   # ⚠ 绕开 Hub 的连接循环，仅作玩法参考
│   ├── GameDemo/                 # Protobuf HTML5 实时游戏
│   ├── RoomDemo/                 # 房间基础能力对照 + 可切 FreeRedis 后端的交叉验收
│   ├── RoomChatDemo/             # 多房间同时订阅 + 样例侧在线列表
│   ├── OfficialImDemo/           # 私聊/群聊走正式连接路径；历史显式标注为样例能力
│   └── AotDemo/                  # Native AOT Docker 部署示例
├── benchmarks/
│   └── WSHub.Benchmarks/         # BenchmarkDotNet 性能基准
├── tests/                        # 7 个测试项目，662 测试
├── docs/                         # 架构对照稿 + 架构规范 + 协议契约 + 性能分析
└── .github/workflows/            # CI/CD (coverage + publish + DingTalk)

性能 (BenchmarkDotNet)

详见 docs/WSHub性能优化总结-1至10.md。

Samples

运行样例

dotnet run --project samples/RoomDemo          # http://localhost:5300
dotnet run --project samples/RoomChatDemo      # http://localhost:5500
dotnet run --project samples/OfficialImDemo    # http://localhost:5400
dotnet run --project samples/ImDemo            # http://localhost:5000 ⚠ 绕开 Hub，仅作玩法参考

多目标框架的样例（net8.0;net9.0;net10.0）必须显式指定框架，否则 dotnet run 报 Your project targets multiple frameworks：

dotnet run --project samples/GameDemo --framework net10.0           # http://localhost:5200
dotnet run --project samples/MinimalApiSample --framework net10.0   # http://localhost:5299

端口来自各自的 Properties/launchSettings.json，必须与 Program.cs 里的 options.Server / options.Servers 一致 —— 连接端点返回的 ws:// 地址就是按它拼的。

每个样例页面顶部都写了操作顺序（先连接，再进房/进会话，才收得到消息）。 只连上但没进房时，发送仍然返回 200，但 Hub 无从投递给你自己。

运行测试

dotnet test tests/WSHub.Abstractions.Tests/
dotnet test tests/WSHub.AspNetCore.Tests/
dotnet test tests/WSHub.InMemory.Tests/
dotnet test tests/WSHub.FreeRedis.Tests/
dotnet test tests/WSHub.IntegrationTests/
dotnet test tests/WSHub.Samples.Tests/      # 样例端到端（含 RoomDemo 的 FreeRedis 交叉验收）
dotnet test tests/WSHub.AotTests/           # 需要 Docker：构建 AOT 镜像并起容器

WSHub.Samples.Tests 里的 RoomDemoFreeRedisE2ETests 会起一个 redis:7-alpine Testcontainer， 用真实 Redis 把 RoomDemo 的「成员收到、非成员收不到」重跑一遍 —— 样例代码不变，只切 Storage:Backend。测试机上已有 Redis 时可设 REDIS_CONNECTION_STRING 复用，跳过启动容器。

运行 Benchmark

dotnet run -c Release --project benchmarks/WSHub.Benchmarks/

CI/CD

贡献

欢迎提交 Issue 和 Pull Request。

License

MIT