Hoppscotch 实时通信测试教程：WebSocket 与 SSE 连接、日志查看与排错指南

Hoppscotch 实时通信测试教程：WebSocket 与 SSE 连接、日志查看与排错指南

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch

Hoppscotch 是一款轻量级开源 API 开发生态系统，内置 WebSocket、SSE 等实时通信测试能力，特别适合前后端联调时需要快速验证实时数据链路的开发者和刚接触实时协议的工程师。读完本文，你可以从零完成一次「连接 → 发送 → 接收 → 日志验证」的完整流程，并掌握常见连接异常的排查方法。

先说清楚：这个功能解决什么问题

实时接口不像普通 HTTP 请求那样「一发一收」，连接是否建立、消息是否到达、事件类型是否正确，都需要一个能持续观察的界面。Hoppscotch 把这部分做进了「Realtime」模块：

• WebSocket：双向通信，适合聊天、协作类场景
• SSE：服务器单向推送，基于 HTTP，适合通知、实时更新类场景
• 另提供 Socket.IO、MQTT 两个标签页，本文聚焦前两者

对应源码位置，便于你想深入时查阅：

• 核心源码：packages/hoppscotch-common/src/newstore/WebSocketSession.ts
• 核心源码：packages/hoppscotch-common/src/newstore/SSESession.ts
• 日志类型定义：packages/hoppscotch-common/src/helpers/types/HoppRealtimeLog.ts

桌面端使用体验与网页一致，适合需要长期挂接实时通道的场景：

WebSocket 连接 5 步跑通（最小可用路径）

1. 打开入口：在左侧导航点击 Realtime（地址栏会跳转到/realtime），默认停在 WebSocket 标签页。
2. 确认端点：Endpoint 输入框默认填好了一个公共回显服务wss://echo-websocket.hoppscotch.io，新手可以直接用它，无需准备自己的服务器。
3. 建立连接：点击连接按钮，观察连接状态变为已连接。
4. 发送消息：在消息输入区输入内容并点击 Send。发送 JSON 时，输入区会做语法提示，例如：

{ "action": "subscribe", "channel": "news-updates" }

5. 验证结果：连接 echo 服务时，你发什么它回什么。日志区出现一条与发送内容一致的接收记录，即表示链路通了。✅

判断标准很简单：发出的内容和接收的内容一致，时间戳晚于发送时间戳，就说明双向通道正常。

WebSocket 子协议怎么配置

如果服务端要求指定子协议（例如graphql-ws），在连接配置区域操作：

1. 点击「Add Protocol」添加一条子协议。
2. 输入协议名称，如graphql-ws。
3. 勾选 Active 使其生效；不需要的协议用 Delete 移除。

每个协议都有独立的启用开关，方便你在多个候选协议之间切换测试，不用删掉重加。

SSE 连接配置与事件过滤

SSE 基于 HTTP，只能由服务器向客户端推送，配置比 WebSocket 更简单：

1. 在 Realtime 页面切换到SSE标签页。
2. 端点默认填入示例服务https://express-eventsource.herokuapp.com/events，可替换为你自己的 SSE 接口地址。
3. 确认 Event Type 输入框。它默认值为data，即监听默认事件。
4. 点击连接，服务器推送的事件会按时间顺序出现在日志区，每条包含事件类型、数据内容、时间戳，服务器提供的话还会带事件 ID。

如何只监听某一类事件

如果服务端会推送多种类型的事件，日志会变得很杂。做法：

• 在Event Type输入框填写目标事件类型，日志区只显示匹配的事件。
• 清空输入框，恢复显示全部事件。

一个实用技巧：先用默认类型连上，观察日志里出现了哪些事件类型，再回头精确填写过滤条件。

实时日志怎么看：方向、时间戳与复制

WebSocket 和 SSE 共用同一套日志机制，日志区位于页面下方，阅读时关注三点：

• 方向标识：不同方向（发送/接收）的消息用不同颜色区分，快速判断某条消息是谁发的。
• 时间戳：精确到毫秒，适合对照两端日志做时序分析。
• 复制：支持复制单条日志或全部日志，方便贴到工单或聊天窗口里和后端同学对问题。

日志的每行结构对应HoppRealtimeLogLine类型：内容（payload）、来源（source）、时间戳（ts）等字段，理解它有助于你判断「日志没显示」是过滤问题还是连接问题。

连接失败或跨域报错怎么排查

⚠️ 排查顺序建议：先确认端点 URL 和协议前缀，再确认代理设置，最后才怀疑服务端。大部分「连不上」都是前两步的问题。

自部署实例遇到网络限制时，可参考项目中桌面端连接自建实例的说明图：

WebSocket 还是 SSE：怎么选

💡 选择原则：客户端需要主动发消息，用 WebSocket；只需要「服务器告诉我」，用 SSE，链路更简单、更容易穿透代理。

下一步

• 完成 echo 服务验证后，把端点换成你自己的接口，再测试异常场景：断网重连、发送非法 JSON、超大消息。
• 熟悉 Realtime 页面后，可以继续试 Socket.IO 和 MQTT 两个标签页，操作模式与 WebSocket 类似。
• 想理解连接管理细节，直接阅读 packages/hoppscotch-common/src/helpers/realtime/ 目录下的连接实现。
• 参与贡献或深入源码结构，可参考仓库根目录的 CONTRIBUTING.md。

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch