WSHub.Abstractions 0.0.0.36

WSHub

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

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

特性

• 发送与投递分离 — IMessageHandler（发送） + IMessageDeliveryHandler（投递）独立管道
• 多节点支持 — 水平扩展，通过 Redis（FreeRedis）或 InMemory 进行消息路由
• 多租户 — tenantId 贯穿连接/频道/消息全栈
• 二进制消息 — byte[] 管道 + 路由头（0xFE），支持 protobuf
• 连接管理 — 心跳、超时清理、per-connection 发送队列
• 事件机制 — 上线/下线/断连/频道进出事件
• 多目标框架 — net8.0 (LTS) / net9.0 / net10.0
• Native AOT — InMemory 模式支持 Docker AOT 部署
• 高覆盖率 — 551 单元测试 + 集成测试（详见 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/                   # IM 频道演示（多租户 + Channel Join）
│   ├── GameDemo/                 # Protobuf HTML5 实时游戏
│   └── AotDemo/                  # Native AOT Docker 部署示例
├── benchmarks/
│   └── WSHub.Benchmarks/         # BenchmarkDotNet 性能基准
├── tests/                        # 6 个测试项目，551 测试
├── docs/                         # 架构 + 协议文档 + 性能分析
└── .github/workflows/            # CI/CD (coverage + publish + DingTalk)

性能 (BenchmarkDotNet)

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

Samples

运行测试

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.AotTests/

运行 Benchmark

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

CI/CD

贡献

欢迎提交 Issue 和 Pull Request。

License

MIT