Elysia 中文文档

简体中文

English

简体中文

English

主题

WebSocket ​

WebSocket 是一种用于客户端与服务器之间通信的实时协议。

与 HTTP 不同，客户端一次又一次地询问网站信息并等待每次的回复，WebSocket 建立了一条直接的通道，使我们的客户端和服务器可以直接来回发送消息，从而使对话更快、更流畅，而无需每条消息都重新开始。

SocketIO 是一个流行的 WebSocket 库，但并不是唯一的。Elysia 使用 uWebSocket，它与 Bun 在底层使用相同的 API。

要使用 WebSocket，只需调用 Elysia.ws()：

typescript
import { Elysia } from 'elysia'

new Elysia()
    .ws('/ws', {
        message(ws, message) {
            ws.send(message)
        }
    })
    .listen(3000)

WebSocket 消息验证： ​

与普通路由相同，WebSocket 也接受一个 schema 对象来严格类型化和验证请求。

typescript
import { Elysia, t } from 'elysia'

const app = new Elysia()
    .ws('/ws', {
        // 验证传入消息
        body: t.Object({
            message: t.String()
        }),
        query: t.Object({
            id: t.String()
        }),
        message(ws, { message }) {
            // 从 `ws.data` 获取 schema
            const { id } = ws.data.query
            ws.send({
                id,
                message,
                time: Date.now()
            })
        }
    })
    .listen(3000)

WebSocket schema 可以验证如下内容：

  • message - 传入消息。
  • query - 查询字符串或 URL 参数。
  • params - 路径参数。
  • header - 请求的头部。
  • cookie - 请求的 cookie。
  • response - 从处理器返回的值。

默认情况下，Elysia 将解析传入的字符串化 JSON 消息为对象以供验证。

配置 ​

您可以通过 Elysia 构造函数设置 WebSocket 值。

ts
import { Elysia } from 'elysia'

new Elysia({
    websocket: {
        idleTimeout: 30
    }
})

Elysia 的 WebSocket 实现扩展了 Bun 的 WebSocket 配置，更多信息请参见 Bun 的 WebSocket 文档。

以下是 Bun WebSocket 的简要配置：

perMessageDeflate ​

@default false

为支持的客户端启用压缩。

默认情况下，压缩是禁用的。

maxPayloadLength ​

消息的最大大小。

idleTimeout ​

@default 120

在连接未接收到消息后，经过这一秒数将关闭连接。

backpressureLimit ​

@default 16777216 (16MB)

单个连接可以缓冲的最大字节数。

closeOnBackpressureLimit ​

@default false

如果超过背压限制，关闭连接。

方法 ​

以下是可用于 WebSocket 路由的新方法。

ws ​

创建 WebSocket 处理程序。

示例：

typescript
import { Elysia } from 'elysia'

const app = new Elysia()
    .ws('/ws', {
        message(ws, message) {
            ws.send(message)
        }
    })
    .listen(3000)

类型：

typescript
.ws(endpoint: path, options: Partial<WebSocketHandler<Context>>): this
  • endpoint - 作为 WebSocket 处理程序暴露的路径
  • options - 自定义 WebSocket 处理程序行为

WebSocketHandler ​

WebSocketHandler 扩展自 config 的配置。

以下是 ws 接受的配置。

open ​

新的 WebSocket 连接的回调函数。

类型：

typescript
open(ws: ServerWebSocket<{
    // 每个连接的 uid
    id: string
    data: Context
}>): this

message ​

传入 WebSocket 消息的回调函数。

类型：

typescript
message(
    ws: ServerWebSocket<{
        // 每个连接的 uid
        id: string
        data: Context
    }>,
    message: Message
): this

Message 类型基于 schema.message。默认是 string。

close ​

关闭 WebSocket 连接的回调函数。

类型：

typescript
close(ws: ServerWebSocket<{
    // 每个连接的 uid
    id: string
    data: Context
}>): this

drain ​

服务器准备好接受更多数据的回调函数。

类型：

typescript
drain(
    ws: ServerWebSocket<{
        // 每个连接的 uid
        id: string
        data: Context
    }>,
    code: number,
    reason: string
): this

parse ​

Parse 中间件在将 HTTP 连接升级到 WebSocket 之前解析请求。

beforeHandle ​

Before Handle 中间件在将 HTTP 连接升级到 WebSocket 之前执行。

理想的验证位置。

transform ​

Transform 中间件在验证之前执行。

transformMessage ​

类似于 transform，但在验证 WebSocket 消息之前执行。

在将连接升级到 WebSocket 之前添加的附加头。