WebSocket

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

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

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

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

import { Elysia } from 'elysia'

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

WebSocket 消息验证：

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

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 值。

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 处理程序。

示例：

import { Elysia } from 'elysia'

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

类型：

.ws(endpoint: path, options: Partial<WebSocketHandler<Context>>): this

• endpoint - 作为 WebSocket 处理程序暴露的路径
• options - 自定义 WebSocket 处理程序行为

WebSocketHandler

WebSocketHandler 扩展自 config 的配置。

以下是 ws 接受的配置。

open

新的 WebSocket 连接的回调函数。

类型：

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

message

传入 WebSocket 消息的回调函数。

类型：

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

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

close

关闭 WebSocket 连接的回调函数。

类型：

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

drain

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

类型：

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 消息之前执行。

header

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

贡献者

一纸忘忧

页面历史

最后编辑于 5 分钟前

查看完整历史

034becf-Merge remote-tracking branch 'origin/upstream'