Skip to content

Commit 2b7ff10

Browse files
CyaimCyaim
committed
chore: 更新文档
1 parent a45cd9a commit 2b7ff10

5 files changed

Lines changed: 933 additions & 67 deletions

File tree

‎Cyaim.WebSocketServer/docs/README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Welcome to the Cyaim.WebSocketServer documentation center. This documentation pr
2424
- **[Cluster Transports](./en/CLUSTER_TRANSPORTS.md)** - Redis, RabbitMQ transport implementations
2525
- **[Metrics](./en/METRICS.md)** - OpenTelemetry integration, performance monitoring
2626
- **[Dashboard](./en/DASHBOARD.md)** - Monitoring panel, API interfaces, frontend UI
27+
- **[Clients](./en/CLIENTS.md)** - Multi-language client SDKs with automatic endpoint discovery
2728

2829
## 🚀 Quick Navigation
2930

@@ -51,6 +52,12 @@ Welcome to the Cyaim.WebSocketServer documentation center. This documentation pr
5152
2. Refer to [API Reference](./en/API_REFERENCE.md) for detailed parameters
5253
3. Check configuration files in sample projects
5354

55+
### I need to use the client SDK
56+
57+
1. Read [Clients](./en/CLIENTS.md) to understand available client SDKs
58+
2. Choose your preferred language (C#, TypeScript, Rust, Java, Dart, Python)
59+
3. Follow the quick start guide for your language
60+
5461
## 📦 Project Structure
5562

5663
```
@@ -65,6 +72,13 @@ Cyaim.WebSocketServer/
6572
│ └── ...
6673
├── Cyaim.WebSocketServer.Dashboard/ # Dashboard backend
6774
├── Cyaim.WebSocketServer.Cluster.*/ # Cluster transport extensions
75+
├── Clients/ # Multi-language client SDKs
76+
│ ├── Cyaim.WebSocketServer.Client/ # C# client
77+
│ ├── cyaim-websocket-client-js/ # TypeScript/JavaScript client
78+
│ ├── cyaim-websocket-client-rs/ # Rust client
79+
│ ├── cyaim-websocket-client-java/ # Java client
80+
│ ├── cyaim-websocket-client-dart/ # Dart client
81+
│ └── cyaim-websocket-client-python/ # Python client
6882
├── Sample/ # Sample projects
6983
└── docs/ # Documentation directory
7084
├── en/ # English documentation
@@ -96,6 +110,13 @@ Cyaim.WebSocketServer/
96110
- ✅ **Dashboard** - Visual monitoring interface
97111
- ✅ **Performance Analysis** - Detailed performance metrics
98112

113+
### Client SDK Features
114+
115+
- ✅ **Multi-language Support** - C#, TypeScript, Rust, Java, Dart, Python
116+
- ✅ **Automatic Endpoint Discovery** - Auto-fetch endpoints from server
117+
- ✅ **Interface Contract** - Type-safe interface-based calling
118+
- ✅ **Flexible Configuration** - Lazy loading, validation options
119+
99120
## 🔧 Supported .NET Versions
100121

101122
- .NET Standard 2.1
@@ -133,3 +154,16 @@ This project is licensed under [LICENSE](../LICENSE).
133154
---
134155

135156
**Last Updated**: 2024-12-XX
157+
158+
## 📦 Client SDKs
159+
160+
We now provide multi-language client SDKs for easy integration:
161+
162+
- **C#** - Full .NET support with dynamic proxy
163+
- **TypeScript/JavaScript** - Type-safe client for web and Node.js
164+
- **Rust** - High-performance async client
165+
- **Java** - Maven package for Java applications
166+
- **Dart** - Flutter and Dart support
167+
- **Python** - Async client for Python 3.8+
168+
169+
See [Clients Documentation](./en/CLIENTS.md) for details.

‎Cyaim.WebSocketServer/docs/en/CLIENTS.md‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
# Client SDKs
2+
3+
Cyaim.WebSocketServer provides multi-language client SDKs that support automatic endpoint discovery and interface contract-based calling.
4+
5+
## Supported Languages
6+
7+
### ✅ C# (.NET)
8+
9+
- **Package**: `Cyaim.WebSocketServer.Client`
10+
- **Target Frameworks**: .NET 8.0, 9.0, 10.0
11+
- **Features**:
12+
- Dynamic proxy using `DispatchProxy`
13+
- `[WebSocketEndpoint]` attribute support
14+
- Lazy loading and custom options
15+
- **Location**: `Clients/Cyaim.WebSocketServer.Client/`
16+
- **Documentation**: [README.md](../../Clients/Cyaim.WebSocketServer.Client/README.md)
17+
18+
### ✅ TypeScript/JavaScript
19+
20+
- **Package**: `@cyaim/websocket-client`
21+
- **Features**:
22+
- Full TypeScript support
23+
- Decorator support for endpoint specification
24+
- Based on `ws` library
25+
- **Location**: `Clients/cyaim-websocket-client-js/`
26+
- **Documentation**: [README.md](../../Clients/cyaim-websocket-client-js/README.md)
27+
28+
### ✅ Rust
29+
30+
- **Package**: `cyaim-websocket-client`
31+
- **Features**:
32+
- Based on `tokio-tungstenite`
33+
- Async support
34+
- Type safety
35+
- **Location**: `Clients/cyaim-websocket-client-rs/`
36+
- **Documentation**: [README.md](../../Clients/cyaim-websocket-client-rs/README.md)
37+
38+
### ✅ Java
39+
40+
- **Package**: `com.cyaim:websocket-client`
41+
- **Features**:
42+
- Maven support
43+
- Based on `Java-WebSocket`
44+
- Java 11+ support
45+
- **Location**: `Clients/cyaim-websocket-client-java/`
46+
- **Documentation**: [README.md](../../Clients/cyaim-websocket-client-java/README.md)
47+
48+
### ✅ Dart
49+
50+
- **Package**: `cyaim_websocket_client`
51+
- **Features**:
52+
- Flutter/Dart support
53+
- Based on `web_socket_channel`
54+
- Async support
55+
- **Location**: `Clients/cyaim-websocket-client-dart/`
56+
- **Documentation**: [README.md](../../Clients/cyaim-websocket-client-dart/README.md)
57+
58+
### ✅ Python
59+
60+
- **Package**: `cyaim-websocket-client`
61+
- **Features**:
62+
- Based on `websockets` and `aiohttp`
63+
- Async support (asyncio)
64+
- Python 3.8+
65+
- **Location**: `Clients/cyaim-websocket-client-python/`
66+
- **Documentation**: [README.md](../../Clients/cyaim-websocket-client-python/README.md)
67+
68+
## Core Features
69+
70+
All client SDKs implement the following core features:
71+
72+
### 1. Automatic Endpoint Discovery
73+
74+
Clients automatically fetch available endpoints from the server's `/ws_server/api/endpoints` API:
75+
76+
```json
77+
{
78+
"success": true,
79+
"data": [
80+
{
81+
"controller": "WeatherForecast",
82+
"action": "Get",
83+
"methodPath": "weatherforecast.get",
84+
"methods": ["GET"],
85+
"fullName": "WeatherForecast.Get",
86+
"target": "weatherforecast.get"
87+
}
88+
]
89+
}
90+
```
91+
92+
### 2. Interface Contract-Based Calling
93+
94+
Define interfaces/types and call methods directly, without manually constructing requests:
95+
96+
**C# Example:**
97+
```csharp
98+
public interface IWeatherService
99+
{
100+
Task<WeatherForecast[]> GetForecastsAsync();
101+
Task<WeatherForecast> GetForecastAsync(string city);
102+
}
103+
104+
var factory = new WebSocketClientFactory("http://localhost:5000", "/ws");
105+
var client = await factory.CreateClientAsync<IWeatherService>();
106+
var forecasts = await client.GetForecastsAsync();
107+
```
108+
109+
**TypeScript Example:**
110+
```typescript
111+
interface IWeatherService {
112+
getForecasts(): Promise<WeatherForecast[]>;
113+
getForecast(city: string): Promise<WeatherForecast>;
114+
}
115+
116+
const factory = new WebSocketClientFactory('http://localhost:5000', '/ws');
117+
const client = await factory.createClient<IWeatherService>({
118+
getForecasts: async () => {},
119+
getForecast: async (city: string) => {}
120+
});
121+
const forecasts = await client.getForecasts();
122+
```
123+
124+
### 3. Type Safety
125+
126+
All clients provide strong typing for requests and responses:
127+
128+
- Compile-time type checking (where supported)
129+
- Runtime type validation
130+
- Automatic serialization/deserialization
131+
132+
### 4. Flexible Configuration
133+
134+
All clients support flexible configuration options:
135+
136+
- **Lazy Loading**: Load endpoints on-demand instead of upfront
137+
- **Validation**: Optional validation of all methods have corresponding endpoints
138+
- **Error Handling**: Configurable error handling behavior
139+
140+
## Quick Start Examples
141+
142+
### C#
143+
144+
```csharp
145+
using Cyaim.WebSocketServer.Client;
146+
147+
var factory = new WebSocketClientFactory("http://localhost:5000", "/ws");
148+
var client = await factory.CreateClientAsync<IWeatherService>();
149+
var forecasts = await client.GetForecastsAsync();
150+
```
151+
152+
### TypeScript
153+
154+
```typescript
155+
import { WebSocketClientFactory } from '@cyaim/websocket-client';
156+
157+
const factory = new WebSocketClientFactory('http://localhost:5000', '/ws');
158+
const client = await factory.createClient<IWeatherService>({
159+
getForecasts: async () => {}
160+
});
161+
const forecasts = await client.getForecasts();
162+
```
163+
164+
### Rust
165+
166+
```rust
167+
use cyaim_websocket_client::WebSocketClientFactory;
168+
169+
let mut factory = WebSocketClientFactory::new(
170+
"http://localhost:5000".to_string(),
171+
"/ws".to_string(),
172+
None,
173+
);
174+
let client = factory.create_client();
175+
let forecasts: Vec<WeatherForecast> = client
176+
.send_request("weatherforecast.get", None::<()>)
177+
.await?;
178+
```
179+
180+
### Java
181+
182+
```java
183+
import com.cyaim.websocket.*;
184+
185+
WebSocketClientFactory factory = new WebSocketClientFactory(
186+
"http://localhost:5000", "/ws", new WebSocketClientOptions());
187+
WebSocketClient client = factory.createClient();
188+
client.connect().get();
189+
List<WeatherForecast> forecasts = client.sendRequest(
190+
"weatherforecast.get", null, new TypeToken<List<WeatherForecast>>(){}.getType()
191+
).get();
192+
```
193+
194+
### Dart
195+
196+
```dart
197+
import 'package:cyaim_websocket_client/cyaim_websocket_client.dart';
198+
199+
final factory = WebSocketClientFactory('http://localhost:5000', '/ws');
200+
final client = factory.createClient();
201+
await client.connect();
202+
final forecasts = await client.sendRequest<List<Map<String, dynamic>>>(
203+
'weatherforecast.get',
204+
);
205+
```
206+
207+
### Python
208+
209+
```python
210+
from cyaim_websocket_client import WebSocketClientFactory
211+
212+
factory = WebSocketClientFactory('http://localhost:5000', '/ws')
213+
client = factory.create_client()
214+
await client.connect()
215+
forecasts = await client.send_request('weatherforecast.get')
216+
```
217+
218+
## Server Requirements
219+
220+
All clients require the server to provide the following API endpoint:
221+
222+
- **GET** `/ws_server/api/endpoints` - Returns all available WebSocket endpoints
223+
224+
This endpoint is automatically provided by the Dashboard module. Make sure the Dashboard is configured in your server:
225+
226+
```csharp
227+
builder.Services.AddWebSocketDashboard();
228+
app.UseWebSocketDashboard("/dashboard");
229+
```
230+
231+
## Advanced Usage
232+
233+
### Custom Endpoint Mapping
234+
235+
If method names don't match server endpoints, you can specify custom mappings:
236+
237+
**C#:**
238+
```csharp
239+
public interface IUserService
240+
{
241+
[WebSocketEndpoint("user.getbyid")]
242+
Task<User> GetUserByIdAsync(int id);
243+
}
244+
```
245+
246+
**TypeScript:**
247+
```typescript
248+
import { endpoint } from '@cyaim/websocket-client';
249+
250+
const client = await factory.createClient<IUserService>({
251+
[endpoint('user.getbyid')]: async (id: number) => {}
252+
});
253+
```
254+
255+
### Lazy Loading
256+
257+
Load endpoints only when needed:
258+
259+
**C#:**
260+
```csharp
261+
var options = new WebSocketClientOptions
262+
{
263+
LazyLoadEndpoints = true
264+
};
265+
var factory = new WebSocketClientFactory("http://localhost:5000", "/ws", options);
266+
```
267+
268+
**TypeScript:**
269+
```typescript
270+
const options = new WebSocketClientOptions();
271+
options.lazyLoadEndpoints = true;
272+
const factory = new WebSocketClientFactory('http://localhost:5000', '/ws', options);
273+
```
274+
275+
## Best Practices
276+
277+
1. **Define Minimal Interfaces**: Only define the methods you need, not all available endpoints
278+
2. **Use Type Safety**: Leverage your language's type system for compile-time safety
279+
3. **Handle Errors**: Always handle potential errors from WebSocket operations
280+
4. **Connection Management**: Let the client manage connections automatically
281+
5. **Endpoint Caching**: Clients cache endpoints by default for better performance
282+
283+
## Troubleshooting
284+
285+
### Endpoint Not Found
286+
287+
If you get an "endpoint not found" error:
288+
289+
1. Check that the server is running and accessible
290+
2. Verify the Dashboard API is enabled (`/ws_server/api/endpoints`)
291+
3. Use `[WebSocketEndpoint]` attribute or decorator to specify the exact endpoint target
292+
4. Check method name matches server action name (case-insensitive)
293+
294+
### Connection Issues
295+
296+
If you have connection problems:
297+
298+
1. Verify the server URL and channel path are correct
299+
2. Check firewall and network settings
300+
3. Ensure WebSocket is enabled on the server
301+
4. Check server logs for errors
302+
303+
## Related Documentation
304+
305+
- [Core Library](./CORE.md) - Server-side implementation
306+
- [Dashboard](./DASHBOARD.md) - Dashboard and API endpoints
307+
- [Quick Start](./QUICK_START.md) - Getting started guide
308+
309+
## License
310+
311+
All client SDKs are licensed under MIT License.
312+
313+
Copyright © Cyaim Studio
314+

0 commit comments

Comments
 (0)