CoreAgent/CoreAgent.WebSocketTransport/项目结构说明.md

CoreAgent.WebSocketTransport 项目结构说明

项目概述

CoreAgent.WebSocketTransport 是一个基于 .NET 8.0 的 WebSocket 传输层组件，主要负责转发协议数据给上层应用。该项目采用分层架构设计，提供高性能、可扩展的 WebSocket 通信能力。

核心设计理念

1. 单一职责原则

• IWebSocketTransport: 专注于连接管理
• IMessageChannel: 专注于消息队列操作
• IMessageSerializer: 专注于消息序列化
• IMessageMiddleware: 专注于消息处理逻辑

2. 依赖注入

• 所有组件都通过依赖注入容器管理
• 支持配置驱动的服务注册
• 提供灵活的中间件扩展机制

3. 异步编程

• 全异步 API 设计
• 支持取消令牌
• 高效的并发处理

项目结构

CoreAgent.WebSocketTransport/
├── Interfaces/           # 接口定义层
├── Services/            # 服务实现层
├── Models/              # 数据模型层
├── Middleware/          # 中间件层
├── Extensions/          # 扩展方法层
├── Examples/            # 使用示例
├── Dos/                 # 文档目录
└── CoreAgent.WebSocketTransport.csproj

详细组件说明

1. Interfaces/ - 接口定义层

IWebSocketTransport.cs

• 职责: WebSocket 连接管理接口
• 功能:
  • 连接状态管理
  • 心跳监控
  • 连接/断开操作
• 设计原则: 单一职责，只负责连接生命周期

IMessageChannel.cs

• 职责: 消息通道抽象接口
• 功能:
  • 异步消息读写
  • 非阻塞操作支持
  • 队列状态监控
  • 通道生命周期管理
• 设计原则: 提供统一的消息队列抽象

IMessageChannelManager.cs

• 职责: 消息通道管理器接口
• 功能:
  • 多通道管理（发送、接收、优先级）
  • 通道状态监控
  • 批量操作支持
• 设计原则: 统一管理多个消息通道

IMessageSerializer.cs

• 职责: 消息序列化接口
• 功能:
  • 消息序列化/反序列化
  • 支持多种数据格式
• 设计原则: 解耦序列化逻辑

IWebSocketConnection.cs

• 职责: WebSocket 连接抽象接口
• 功能:
  • 底层连接操作
  • 消息发送/接收
  • 连接状态管理
• 设计原则: 封装底层 WebSocket 操作

2. Services/ - 服务实现层

WebSocketTransport.cs

• 职责: WebSocket 传输核心实现
• 核心功能:
  • 自动连接管理
  • 消息批量发送
  • 自动重连机制
  • 心跳保活
  • 中间件管道处理
• 技术特点:
  • 多任务并发处理
  • 信号量控制连接
  • 异常恢复机制
  • 性能优化（批量发送、内存池）

WebSocketConnection.cs

• 职责: WebSocket 连接实现
• 功能:
  • 底层 WebSocket 操作封装
  • 连接状态管理
  • 消息收发处理
• 技术特点:
  • 线程安全设计
  • 异常处理机制

ChannelMessageChannel.cs

• 职责: 基于 Channel 的消息通道实现
• 功能:
  • 高性能消息队列
  • 异步读写操作
  • 容量控制
• 技术特点:
  • 使用 System.Threading.Channels
  • 支持背压控制
  • 内存高效

MessageChannelManager.cs

• 职责: 消息通道管理器实现
• 功能:
  • 多通道协调管理
  • 优先级消息处理
  • 批量操作优化
• 技术特点:
  • 通道池管理
  • 动态容量调整
  • 性能监控

JsonMessageSerializer.cs

• 职责: JSON 消息序列化实现
• 功能:
  • JSON 序列化/反序列化
  • 错误处理
  • 类型安全
• 技术特点:
  • 使用 System.Text.Json
  • 支持自定义选项

3. Models/ - 数据模型层

WebSocketConfig.cs

• 职责: WebSocket 配置模型
• 配置项:
  • 服务器地址
  • 超时设置
  • 批量处理参数
  • 重连策略
  • 队列容量
  • 缓存设置
• 特点:
  • 数据验证注解
  • 合理的默认值
  • 配置绑定支持

4. Middleware/ - 中间件层

IMessageMiddleware.cs

• 职责: 消息处理中间件接口
• 功能:
  • 发送消息预处理
  • 接收消息后处理
  • 条件跳过支持
• 设计原则: 管道模式，支持链式处理

LoggingMiddleware.cs

• 职责: 日志记录中间件
• 功能:
  • 消息发送日志
  • 消息接收日志
  • 性能监控
• 特点: 结构化日志，性能友好

CacheMiddleware.cs

• 职责: 缓存中间件
• 功能:
  • 消息缓存
  • 重复消息检测
  • TTL 管理
• 特点: 内存缓存，可配置 TTL

5. Extensions/ - 扩展方法层

WebSocketTransportExtensions.cs

• 职责: 依赖注入扩展
• 功能:
  • 服务注册
  • 配置绑定
  • 中间件注册
  • 工厂模式支持
• 特点:
  • 流式 API 设计
  • 配置驱动
  • 灵活的注册方式

6. Examples/ - 使用示例

CompositionPatternExample.cs

• 职责: 组合模式使用示例
• 展示内容:
  • 基本使用流程
  • 优先级消息处理
  • 连接状态监控
• 价值: 提供最佳实践参考

ChannelManagerTestExample.cs

• 职责: 通道管理器测试示例
• 展示内容:
  • 多通道操作
  • 性能测试
  • 异常处理
• 价值: 验证组件功能

数据流转架构

上层应用
    ↓
IMessageChannelManager (消息通道管理器)
    ↓
WebSocketTransport (传输层)
    ↓
IMessageMiddleware[] (中间件管道)
    ↓
IMessageSerializer (序列化)
    ↓
IWebSocketConnection (连接层)
    ↓
WebSocket 服务器

核心特性

1. 高性能设计

• 批量发送: 支持消息批量处理，减少网络开销
• 内存池: 使用 ArrayPool 减少内存分配
• 异步处理: 全异步 API，支持高并发
• 背压控制: 通过 Channel 实现背压机制

2. 可靠性保障

• 自动重连: 连接断开时自动重连
• 心跳保活: 定期发送心跳包
• 异常恢复: 完善的异常处理机制
• 状态监控: 实时连接状态监控

3. 可扩展性

• 中间件架构: 支持自定义消息处理逻辑
• 配置驱动: 灵活的配置管理
• 依赖注入: 松耦合的组件设计
• 接口抽象: 易于扩展和替换

4. 易用性

• 流式 API: 简洁的注册和使用方式
• 详细文档: 完整的代码注释和示例
• 类型安全: 强类型设计，编译时检查
• 错误处理: 友好的错误信息和处理

使用方式

1. 服务注册

// 使用配置文件
services.AddWebSocketTransport(configuration, "WebSocket");

// 使用委托配置
services.AddWebSocketTransport(options =>
{
    options.Url = "wss://example.com/ws";
    options.TimeoutMs = 30000;
    options.MaxBatchSize = 100;
});

2. 基本使用

// 注入服务
var transport = serviceProvider.GetRequiredService<IWebSocketTransport>();
var channelManager = serviceProvider.GetRequiredService<IMessageChannelManager>();

// 连接服务器
await transport.ConnectAsync();

// 发送消息
await channelManager.SendChannel.WriteAsync("Hello World");

// 接收消息
while (channelManager.ReceiveChannel.TryRead(out var message))
{
    Console.WriteLine($"收到消息: {message}");
}

技术栈

• .NET 8.0: 目标框架
• System.Threading.Channels: 高性能消息队列
• System.Text.Json: JSON 序列化
• Microsoft.Extensions.DependencyInjection: 依赖注入
• Microsoft.Extensions.Configuration: 配置管理
• Microsoft.Extensions.Logging: 日志记录
• Microsoft.Extensions.Caching.Memory: 内存缓存

总结

CoreAgent.WebSocketTransport 是一个设计精良的 WebSocket 传输层组件，通过分层架构、依赖注入、中间件模式等设计模式，提供了高性能、可靠、可扩展的 WebSocket 通信能力。该项目特别适合需要稳定 WebSocket 连接的应用场景，如实时通信、数据同步、消息推送等。