---
url: https://mokup.icebreaker.top/zh/reference/websocket.md
---
# WebSocket mock

`mokup/ws` 拦截通过全局标准 `WebSocket` 构造器创建的连接。它使用独立于 HTTP 的控制器。

```ts
import { setupWebSocket, ws } from 'mokup/ws'

const chat = ws.link('wss://example.test/chat')
chat.addEventListener('connection', ({ client, signal }) => {
  client.addEventListener('message', (event) => {
    client.send(`echo:${String(event.data)}`)
  })
  signal.addEventListener('abort', () => {
    // 清理为这个连接创建的定时器或其他资源。
  }, { once: true })
})

const sockets = setupWebSocket(chat)
sockets.start({ onUnhandledConnection: 'error' })

// 运行应用中创建 WebSocket 连接的代码。
// 在测试清理或离开应用预览时等待 stop()。
await sockets.stop()
```

## 匹配与客户端

按照传给 `setupWebSocket` 的顺序匹配 link。第一个命中的 link 接管连接，即使它没有注册 connection 监听器。

* 完整 `ws:` 或 `wss:` URL 匹配规范化后的完整地址，包括查询字符串。
* 以 `/` 开头的字符串精确匹配路径和查询字符串，不限制主机。
* `'*'` 匹配所有 WebSocket 地址。
* 正则表达式匹配完整 URL；不同连接之间不会共享 `lastIndex`。

`link.clients` 返回当前客户端的快照。`link.broadcast(data)` 向所有当前客户端发送文本或二进制消息；使用 `{ except: [client] }` 排除特定客户端。集合只属于当前 JavaScript 环境，不会跨浏览器标签页或进程同步。

`client.send(data)` 向应用发送消息，`client.close(code?, reason?)` 关闭连接。客户端的 `message` 监听器收到应用发出的消息，`close` 监听器观察关闭。`addEventListener('connection', listener)` 返回移除此连接监听器的函数。

## 连接真实服务

默认连接由 mock 处理。调用 `server.connect()` 才会连接原始地址；连接后自动转发应用消息和服务端响应。通过 `event.preventDefault()` 可以替换或阻止任一方向的转发。

```ts
chat.addEventListener('connection', ({ client, server }) => {
  server.connect()
  client.addEventListener('message', (event) => {
    event.preventDefault()
    server.send(`modified:${String(event.data)}`)
  })
  server.addEventListener('message', (event) => {
    event.preventDefault()
    client.send(`upstream:${String(event.data)}`)
  })
})
```

`server.send(data)` 要求先调用 `server.connect()`，上游尚未打开时会排队发送。`server.close()` 仅关闭上游连接。服务端支持 `open`、`message`、`error`、`close` 事件。

## GraphQL subscription

`mokup/graphql` 的 `createGraphQLWebSocket` 会创建使用 `graphql-transport-ws` 协议的 `ws.link`。它确认 `connection_init`，接收带操作名称的 `subscribe`，发送连续的 `next`，并在每个操作结束时发送 `complete`。返回的 link 与其他 WebSocket Mock 使用同一个控制器启动。

```ts
import { createGraphQLWebSocket } from 'mokup/graphql'
import { setupWebSocket } from 'mokup/ws'

const graphql = createGraphQLWebSocket('/graphql', {
  async* Count() {
    yield { count: 1 }
    yield { count: 2 }
  },
})
const controller = setupWebSocket(graphql)
controller.start({ onUnhandledConnection: 'error' })
```

`setupWebSocket` 暴露与 HTTP session 相同的事件形状。通过
`start({ events: session.events })` 传入已有事件总线，可以把
`protocol:start`、`protocol:match`、`protocol:message`、`protocol:unhandled`、
`protocol:end` 和 `protocol:error` 合并到同一个诊断流：

```ts
const session = createMockSession()
const diagnostics = createDiagnosticsCollector(session)
const sockets = setupWebSocket(graphql)
sockets.start({ events: session.events })
// diagnostics.snapshot().timeline 现在会包含 WebSocket 连接元数据。
```

Resolver 会收到包含解析后 query、操作名称、variables、请求 ID 和可取消请求 signal 的标准 Mokup 请求上下文。HTTP/SSE 客户端可以改用 `graphql.link('/graphql').subscription(...)`。

## 生命周期与支持范围

重复调用 `start()` 不会重复安装。每个 JavaScript 环境只允许一个活动的 Mokup WebSocket 控制器，启动第二个会抛出错误，并保留当前控制器。HTTP 控制器可以同时运行。`stop()` 会中止连接的 signal、移除连接消息监听器、发起所属 mock 和上游连接的关闭、清空客户端集合，并恢复原始全局构造器。再次调用 `start()` 可建立新连接，link 定义与 connection 监听器仍可复用。

`onUnhandled` 独立于 HTTP 策略。默认 `bypass` 连接原始服务；`warn` 还会打印警告；`error` 在连接打开前以 `1008` 状态码关闭连接。传入函数时会收到共享协议事件和 `{ signal, connection }`，函数返回后仍按默认 bypass 流程处理；函数抛错会发出 `protocol:error` 并关闭连接。`onUnhandledConnection` 作为弃用兼容别名保留。

```ts
const controller = setupWebSocket(chat)
controller.start({
  onUnhandled(event, { connection, signal }) {
    console.warn(`没有匹配的 Mock：${event.url}`)
    // 回调可以检查连接，也可以自行连接原始服务。
    if (!signal.aborted) {
      connection.server.connect()
    }
  },
})
```

应用收到的 `open` 事件由拦截器控制。转发连接可能在上游握手完成前显示为打开，mock 子协议从客户端请求的协议中选择。此控制器不能用于验证真实握手时序、子协议协商、TLS、压缩、帧分片或服务端 WebSocket upgrade。

普通 WebSocket 连接会为每个线上消息发出 `protocol:message`，其中
`direction: 'inbound'` 表示应用发往 Mock，`direction: 'outbound'` 表示 Mock 或上游发往应用。GraphQL 会在这些传输事件之上追加操作级协议事件。

拥有可替换全局 WebSocket 的浏览器和 Node.js 可直接使用。如果全局构造器不可用，需要先将兼容实现（例如 `undici`）设置到 `globalThis.WebSocket`，否则 `start()` 会抛出包含接入提示的错误。发布包要求 Node.js 22.12.0 或更新版本。`import WebSocket from 'ws'` 等独立导入的构造器不会被拦截，除非在应用代码运行前将其安装为全局构造器。`start()` 之前创建的连接以及其他 JavaScript 环境中的连接不受影响。

集成测试使用 Node 的全局 WebSocket，覆盖文本和二进制 mock、真实本地 WebSocket 服务转发、双向消息改写、严格未命中策略、匹配优先级、广播、取消、停止与重启。Chrome、Firefox 和 WebKit 浏览器 conformance 已覆盖匹配消息、广播、未命中 error 策略、生命周期事件和 teardown；握手时序与子协议协商仍不在该矩阵内。
