SDK 设计

WebSocket 客户端

以 Markdown 格式查看

Fern 从您的 AsyncAPI 通道定义生成类型化的 WebSocket 客户端。生成的客户端处理连接管理、类型化的发送/接收消息和自动重连。

Fern 为 TypeScript、Python、Java、C# 和 Rust 生成 WebSocket 客户端。Go 仅生成类型，Ruby 暂不支持。

启用 WebSocket 客户端生成

在 generators.yml 中为相关生成器添加配置标志：

1groups:
2  ts-sdk:
3    generators:
4      - name: fernapi/fern-typescript-sdk
5        version: ...
6        config:
7          generateWebSocketClients: true

Java 默认生成 WebSocket 客户端，无需额外配置。

生成的 SDK 行为

给定如下 AsyncAPI 通道定义：

asyncapi.yml
1asyncapi: 3.0.0
2info:
3  title: Plant Monitoring Service
4  version: 1.0.0
5channels:
6  plantUpdates:
7    address: /plants/{plant_id}/updates
8    parameters:
9      plant_id:
10        description: Plant identifier
11    messages:
12      SensorReading:
13        $ref: '#/components/messages/SensorReading'
14      PlantStatus:
15        $ref: '#/components/messages/PlantStatus'
16operations:
17  sendReading:
18    action: send
19    channel:
20      $ref: '#/channels/plantUpdates'
21    messages:
22      - $ref: '#/channels/plantUpdates/messages/SensorReading'
23  receivePlantStatus:
24    action: receive
25    channel:
26      $ref: '#/channels/plantUpdates'
27    messages:
28      - $ref: '#/channels/plantUpdates/messages/PlantStatus'
29components:
30  messages:
31    SensorReading:
32      payload:
33        type: object
34        properties:
35          temperature:
36            type: number
37          humidity:
38            type: number
39    PlantStatus:
40      payload:
41        type: object
42        properties:
43          health:
44            type: string
45          needsWater:
46            type: boolean

Fern 生成以下客户端代码。

发送方法命名为 send + 规范中的操作名称。sendReading 操作在 TypeScript、Python、Java 和 Rust 中生成 sendSendReading。C# 使用重载的 Send() 方法。

接收处理因语言而异：

  • TypeScript — 通用 socket.on("message", handler) 回调
  • Python — 来自 ws.recv() 的类型化响应
  • Java — 每种消息类型的处理器如 onPlantStatus(handler)
  • C# — 类型化的 Event<T> 属性如 PlantStatus.Subscribe(handler)
  • Rust — 来自 ws.recv() 的类型化枚举

TypeScript SDK 生成类型化的 socket 类，带有 send 方法、事件处理器和自动重试断开连接的 ReconnectingWebSocket。

1const client = new PlantClient({ token: "..." });
2
3const socket = await client.plantUpdates.createPlantUpdatesConnection({
4  plantId: "plant-123",
5});
6
7socket.on("open", () => {
8  console.log("Connected");
9});
10
11socket.on("message", (message) => {
12  // message 类型为 PlantStatus
13  console.log(message.health);
14});
15
16socket.on("error", (error) => {
17  console.error(error);
18});
19
20socket.sendSendReading({ temperature: 22.5, humidity: 65 });
21
22socket.close();

身份验证

在 TypeScript、Python、Java 和 Rust 中，WebSocket 客户端自动继承根客户端上配置的身份验证。头部（包括 bearer 令牌、API 密钥和自定义头部）随 WebSocket 握手请求一起发送。

1const client = new PlantClient({
2  token: "your-bearer-token",
3});
4
5// 认证头部转发到 WebSocket 握手
6const socket = await client.plantUpdates.createPlantUpdatesConnection({
7  plantId: "plant-123",
8});

在 C# 中，WebSocket 客户端使用包含连接 URL 和通道参数的 Options 对象构建。通过 HttpInvoker 选项或在底层客户端上设置头部来配置身份验证。

定义 WebSocket 通道

WebSocket 客户端从 AsyncAPI 规范中的通道定义生成。有关定义通道、消息和操作的信息，请参阅发布/订阅操作。