Skip to content

Commit 930add5

Browse files
CyaimCyaim
committed
chore: 完善文档
1 parent e5b6efa commit 930add5

4 files changed

Lines changed: 614 additions & 0 deletions

File tree

‎Cyaim.WebSocketServer/docs/zh-cn/API_REFERENCE.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,131 @@ public interface IWebSocketHandler
5252
}
5353
```
5454

55+
### WebSocketManager
56+
57+
WebSocketManager 提供了统一的发送方法，自动适配单机和集群模式。
58+
59+
#### 统一发送方法（单机和集群）
60+
61+
```csharp
62+
public static class WebSocketManager
63+
{
64+
// 发送字节数组到单个连接
65+
public static async Task<bool> SendAsync(
66+
string connectionId,
67+
byte[] data,
68+
WebSocketMessageType messageType = WebSocketMessageType.Text);
69+
70+
// 发送字节数组到多个连接
71+
public static async Task<Dictionary<string, bool>> SendAsync(
72+
IEnumerable<string> connectionIds,
73+
byte[] data,
74+
WebSocketMessageType messageType = WebSocketMessageType.Text);
75+
76+
// 发送文本到单个连接
77+
public static async Task<bool> SendAsync(
78+
string connectionId,
79+
string text,
80+
Encoding encoding = null);
81+
82+
// 发送文本到多个连接
83+
public static async Task<Dictionary<string, bool>> SendAsync(
84+
IEnumerable<string> connectionIds,
85+
string text,
86+
Encoding encoding = null);
87+
88+
// 发送 JSON 对象到单个连接
89+
public static async Task<bool> SendAsync<T>(
90+
string connectionId,
91+
T data,
92+
JsonSerializerOptions options = null,
93+
Encoding encoding = null);
94+
95+
// 发送 JSON 对象到多个连接
96+
public static async Task<Dictionary<string, bool>> SendAsync<T>(
97+
IEnumerable<string> connectionIds,
98+
T data,
99+
JsonSerializerOptions options = null,
100+
Encoding encoding = null);
101+
}
102+
```
103+
104+
#### 扩展方法（便于使用）
105+
106+
```csharp
107+
// 字节数组扩展方法
108+
public static async Task<bool> SendAsync(
109+
this byte[] data,
110+
string connectionId,
111+
WebSocketMessageType messageType = WebSocketMessageType.Text);
112+
113+
public static async Task<Dictionary<string, bool>> SendAsync(
114+
this byte[] data,
115+
IEnumerable<string> connectionIds,
116+
WebSocketMessageType messageType = WebSocketMessageType.Text);
117+
118+
// 文本扩展方法
119+
public static async Task<bool> SendTextAsync(
120+
this string text,
121+
string connectionId,
122+
Encoding encoding = null);
123+
124+
public static async Task<Dictionary<string, bool>> SendTextAsync(
125+
this string text,
126+
IEnumerable<string> connectionIds,
127+
Encoding encoding = null);
128+
129+
// JSON 对象扩展方法
130+
public static async Task<bool> SendJsonAsync<T>(
131+
this T data,
132+
string connectionId,
133+
JsonSerializerOptions options = null,
134+
Encoding encoding = null)
135+
where T : class;
136+
137+
public static async Task<Dictionary<string, bool>> SendJsonAsync<T>(
138+
this T data,
139+
IEnumerable<string> connectionIds,
140+
JsonSerializerOptions options = null,
141+
Encoding encoding = null)
142+
where T : class;
143+
144+
// 流扩展方法（支持大文件、网络流等）
145+
public static async Task<bool> SendAsync(
146+
this Stream stream,
147+
string connectionId,
148+
WebSocketMessageType messageType = WebSocketMessageType.Binary,
149+
int chunkSize = 64 * 1024,
150+
CancellationToken cancellationToken = default);
151+
152+
public static async Task<Dictionary<string, bool>> SendAsync(
153+
this Stream stream,
154+
IEnumerable<string> connectionIds,
155+
WebSocketMessageType messageType = WebSocketMessageType.Binary,
156+
int chunkSize = 64 * 1024,
157+
CancellationToken cancellationToken = default);
158+
```
159+
160+
#### 使用示例
161+
162+
```csharp
163+
// 使用扩展方法发送文本
164+
await "Hello World".SendTextAsync("connectionId");
165+
166+
// 使用扩展方法发送 JSON 对象
167+
var user = new { Id = 1, Name = "Alice" };
168+
await user.SendJsonAsync("connectionId");
169+
170+
// 使用扩展方法发送流
171+
using var fileStream = File.OpenRead("largefile.bin");
172+
await fileStream.SendAsync("connectionId");
173+
174+
// 批量发送
175+
var connectionIds = new[] { "conn1", "conn2", "conn3" };
176+
await "Hello".SendTextAsync(connectionIds);
177+
await fileStream.SendAsync(connectionIds);
178+
```
179+
55180
## 集群 API
56181

57182
### ClusterManager
@@ -84,6 +209,27 @@ public class ClusterManager
84209
byte[] data,
85210
int messageType);
86211

212+
// 流转发方法 - 支持大文件、网络流等
213+
// Stream routing methods - supports large files, network streams, etc.
214+
215+
// 向单个连接路由流（支持分块传输）
216+
// Route stream to single connection (supports chunked transmission)
217+
public Task<bool> RouteStreamAsync(
218+
string connectionId,
219+
Stream stream,
220+
WebSocketMessageType messageType = WebSocketMessageType.Binary,
221+
int chunkSize = 64 * 1024,
222+
CancellationToken cancellationToken = default);
223+
224+
// 向多个连接路由流（支持跨节点、分块传输）
225+
// Route stream to multiple connections (supports cross-node, chunked transmission)
226+
public Task<Dictionary<string, bool>> RouteStreamsAsync(
227+
IEnumerable<string> connectionIds,
228+
Stream stream,
229+
WebSocketMessageType messageType = WebSocketMessageType.Binary,
230+
int chunkSize = 64 * 1024,
231+
CancellationToken cancellationToken = default);
232+
87233
public void SetConnectionProvider(IWebSocketConnectionProvider provider);
88234
public void SetMetricsCollector(WebSocketMetricsCollector metricsCollector);
89235

@@ -416,6 +562,23 @@ public class MvcResponseScheme
416562
}
417563
```
418564

565+
### ForwardWebSocketStream
566+
567+
```csharp
568+
public class ForwardWebSocketStream
569+
{
570+
public string ConnectionId { get; set; }
571+
public string TargetNodeId { get; set; }
572+
public string StreamId { get; set; } // 流ID，用于块关联
573+
public int ChunkIndex { get; set; } // 块索引（从0开始）
574+
public bool IsLastChunk { get; set; } // 是否是最后一块
575+
public byte[] Data { get; set; } // 块数据
576+
public int MessageType { get; set; } // WebSocket消息类型
577+
public long? TotalSize { get; set; } // 流总大小（可选，用于进度跟踪）
578+
public string Endpoint { get; set; } // 端点
579+
}
580+
```
581+
419582
### ClusterMessage
420583

421584
```csharp

‎Cyaim.WebSocketServer/docs/zh-cn/CLUSTER.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,61 @@ connectionId -> nodeId
228228
- 并行处理：所有消息并行发送，提高效率
229229
- 结果追踪：可以查看每个连接是否成功接收消息
230230

231+
### 流转发（支持大文件、网络流等）
232+
233+
集群支持流转发功能，可以高效地传输大文件、网络流等数据：
234+
235+
- **`RouteStreamAsync`**: 向单个连接发送流，自动分块传输
236+
- **`RouteStreamsAsync`**: 向多个连接批量发送流，支持跨节点
237+
- **分块传输**: 自动将大流分块（默认 64KB），避免内存溢出
238+
- **自动重组**: 接收端自动重组分块数据，确保数据完整性
239+
- **支持所有流类型**: 文件流、网络流、内存流等
240+
241+
#### 流转发示例
242+
243+
```csharp
244+
// 发送文件流
245+
using var fileStream = File.OpenRead("largefile.bin");
246+
var success = await clusterManager.RouteStreamAsync(
247+
connectionId: "connection-123",
248+
stream: fileStream,
249+
messageType: WebSocketMessageType.Binary,
250+
chunkSize: 64 * 1024 // 可选：自定义块大小
251+
);
252+
253+
// 批量发送流到多个连接（支持跨节点）
254+
var connectionIds = new[] { "connection-1", "connection-2", "connection-3" };
255+
var results = await clusterManager.RouteStreamsAsync(
256+
connectionIds: connectionIds,
257+
stream: fileStream,
258+
messageType: WebSocketMessageType.Binary
259+
);
260+
261+
// 发送网络流
262+
using var networkStream = new NetworkStream(socket);
263+
await clusterManager.RouteStreamAsync("connection-123", networkStream);
264+
265+
// 发送内存流
266+
using var memoryStream = new MemoryStream(data);
267+
await clusterManager.RouteStreamAsync("connection-123", memoryStream);
268+
```
269+
270+
#### 流转发工作原理
271+
272+
1. **分块读取**: 从流中按块大小（默认 64KB）读取数据
273+
2. **生成流ID**: 为每个流生成唯一的 StreamId
274+
3. **分块发送**: 将每个块封装为 `ForwardWebSocketStream` 消息发送
275+
4. **接收重组**: 目标节点接收所有块后自动重组
276+
5. **发送到客户端**: 重组完成后发送到目标 WebSocket 连接
277+
278+
#### 流转发特性
279+
280+
- ✅ **内存高效**: 分块传输，不会一次性加载整个流到内存
281+
- ✅ **自动重试**: 支持网络错误重试
282+
- ✅ **顺序保证**: 确保数据块按顺序重组
283+
- ✅ **进度跟踪**: 可选的总大小参数用于进度跟踪
284+
- ✅ **跨节点支持**: 自动路由到正确的节点
285+
231286
### 路由示例
232287

233288
```csharp

0 commit comments

Comments
 (0)