WebSocket 客户端 | Fern Documentation

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

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

启用 WebSocket 客户端生成

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

groups:
  ts-sdk:
    generators:
      - name: fernapi/fern-typescript-sdk
        version: ...
        config:
          generateWebSocketClients: true

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

生成的 SDK 行为

给定如下 AsyncAPI 通道定义：

asyncapi.yml

asyncapi: 3.0.0
info:
  title: Plant Monitoring Service
  version: 1.0.0
channels:
  plantUpdates:
    address: /plants/{plant_id}/updates
    parameters:
      plant_id:
        description: Plant identifier
    messages:
      SensorReading:
        $ref: '#/components/messages/SensorReading'
      PlantStatus:
        $ref: '#/components/messages/PlantStatus'
operations:
  sendReading:
    action: send
    channel:
      $ref: '#/channels/plantUpdates'
    messages:
      - $ref: '#/channels/plantUpdates/messages/SensorReading'
  receivePlantStatus:
    action: receive
    channel:
      $ref: '#/channels/plantUpdates'
    messages:
      - $ref: '#/channels/plantUpdates/messages/PlantStatus'
components:
  messages:
    SensorReading:
      payload:
        type: object
        properties:
          temperature:
            type: number
          humidity:
            type: number
    PlantStatus:
      payload:
        type: object
        properties:
          health:
            type: string
          needsWater:
            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

Python

Java

C#

Rust

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

const client = new PlantClient({ token: "..." });
const socket = await client.plantUpdates.createPlantUpdatesConnection({
  plantId: "plant-123",
});
socket.on("open", () => {
  console.log("Connected");
});
socket.on("message", (message) => {
  // message 类型为 PlantStatus
  console.log(message.health);
});
socket.on("error", (error) => {
  console.error(error);
});
socket.sendSendReading({ temperature: 22.5, humidity: 65 });
socket.close();

身份验证

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

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

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

定义 WebSocket 通道

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