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. 服务注册
```csharp
// 使用配置文件
services.AddWebSocketTransport(configuration, "WebSocket");

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

### 2. 基本使用
```csharp
// 注入服务
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 连接的应用场景，如实时通信、数据同步、消息推送等。