DevPeek

WebSocket Mock

DevPeek 可用 `.dpws` 文件 Mock WebSocket 长连接里的多轮对话：登录、心跳、进房、登出等。本文说明**何时用、怎么上手**；完整语法见独立的 .dpws 语言参考。

WebSocket Mock 能力正在接入 DevPeek 桌面端。可先按本文与语言参考编写 `.dpws`；应用内规则入口上线后即可直接使用。HTTP 请求的 Mock 仍见「Mock/断点」章节。

和 HTTP Mock 有什么不同

Mock/断点 适合单次 HTTP 请求/响应。WebSocket 是长连接：同一条连接上会有登录、心跳、进房、登出等多轮消息，需要按「对话树」来 Mock。

  • HTTP Mock：一次请求对一次响应（可篡改）。
  • WebSocket Mock：连接内多轮消息；可模拟服务端主动推送（如心跳）。
  • 规则正文是一份缩进文本 Flow，扩展名推荐 `.dpws`。

配置文件是什么

一条 WebSocket Mock 规则对应一份 Flow 文本（`.dpws`）。你在 DevPeek 里启用规则后，命中 WebSocket 连接的流量会按 Flow 模拟服务端行为。

  • 文件头 `# …` 行：地址、协议字段习惯、是否自动回 Ping 等约定。
  • 正文缩进树：`--条件` 匹配客户端消息，其下写要返回的内容。
  • 缩进统一用 4 个空格或 Tab，不要混用。

怎么读一份 Flow

心智模型很简单：本质是「返回」；`--` 条件像判断门，通过后才发该分支下的返回。

  • `--login`：客户端消息里带有 login 特征时进入这一支。
  • 缩进一层的 `loginSuccess`：向客户端发一帧（单词简写会包成 JSON，顶层 type 为 loginSuccess）。
  • 同一条件下可写多行返回，按书写顺序依次发出；可加 `+300ms` 做延迟。
  • 条件下面还可以再嵌套子条件，同一帧里字段齐全时可以连发多段返回。
  • 长连接还要关心 **scope（阶段）**：登录后进 `~auth`、登出用 `!~auth`，用来区分「已登录 / 未登录」并控制心跳等定时推送——详见下一节。

上手示例

下面是一份可跑通的最小 Flow：登录回成功、业务 ping 回 pong。抓包对照客户端明文 JSON 调整 `--` 条件即可：

# ws wss://api.example.com/ws

# profile type

# dispatch type

# format json

# ping auto



--login

    loginSuccess



--ping

    pong

Scope：连接里的阶段

Scope 表示这条 WebSocket 连接**当前处于哪个业务阶段**——例如「尚未登录」「已在 auth 登录态」「在某个房间里」。它不像变量那样存具体字段值，而是记住「现在算哪一段对话」。阶段会影响两件事：哪些 `--` 条件能匹配客户端消息，以及 `--@loop` 定时推送是否还在运行。

  • **进入阶段**：在条件行尾写 `~名称`（如 `--login ~auth`）。匹配成功并发完该分支返回后，连接进入 `auth` 阶段；该返回下的缩进子树成为后续消息的优先匹配位置。
  • **退出阶段**：写 `!~名称`（如 `--logout !~auth`）。只有连接**已经在**该阶段时，这一行才会参与匹配；命中后先退出阶段（该阶段及其子阶段下的定时推送全部停止），再发返回。
  • **分工匹配**：同一类客户端消息可以写多条分支——已登录走带 `!~auth` 的那条，未登录走普通 `--logout`。若栈上还没有 `auth`，`--logout !~auth` 整行不匹配，不会误触发。
  • **与定时推送**：挂在某阶段返回子树里的 `--@loop`，只在该阶段 active 期间推送；退出阶段后自动停止，无需手写「停止心跳」的返回。
  • **嵌套阶段**：可以在 `~auth` 里再进入 `~room1`（如进房）。`!~auth` 会一并退出内层阶段并停止所有相关定时推送。
连接建立（尚未进入任何 scope）

      │

      │  客户端发 login → 命中 --login ~auth

      ▼

  进入 ~auth 阶段 ──────► 开始 heartbeat 定时推送

      │

      │  客户端发 logout → 命中 --logout !~auth

      ▼

  退出 auth（heartbeat 自动停止）

登录 / 登出是最常见的 scope 场景：`~auth` 管登录态与心跳，两条 `--logout` 分别处理「已登录」和「未登录」：

# profile type

# dispatch type

# format json

# ping auto



--login ~auth

    loginSuccess

        --@loop 5s

            heartbeat



--logout !~auth

    logoutSuccess



--logout

    notLoggedIn
  • `--login ~auth`：登录成功后进入 auth；其返回子树下的 `--@loop 5s` 每 5 秒推 `heartbeat`。
  • `--logout !~auth`：仅已登录时匹配；退出 auth、停止 heartbeat，并回 `logoutSuccess`。
  • 根级 `--logout`：客户端在未登录时仍发 logout，走 `notLoggedIn` 错误返回。

完整语法去哪查

文件头全部指令、条件写法、同帧连发、变量与管道、生命周期、`@loop` 细节、validate 错误码与运行时边界规则，见 .dpws 语言参考。该文档面向编写 `.dpws` 的使用者，与 DevPeek 内部实现说明分开维护。

编写建议

  • 先写文件头与一条「登录成功 + ~auth」路径，确认 scope 与 heartbeat 正常，再加 logout 与未登录分支。
  • 业务层的 `--type=ping` 与协议层 Ping 不是一回事；截断上游时记得 `# ping auto`（见语言参考）。
  • 条件尽量贴近抓包里的明文 JSON；语法细节与完整示例集见语言参考。

WebSocket Mock 会改变客户端在长连接上看到的消息序列。请在自有或授权测试环境中使用，并在联调结束后关闭临时规则。