极客工场

Appearance

共 616 字预计阅读约 2 分钟

websocat 调试 WebSocket/SSE ​

更新时间：2026-09-18。WebSocket 是有状态长连接，Postman/curl 不好交互。websocat 是「WebSocket 版 netcat」，命令行直连、手工收发帧。服务端设计见 WebSocket 心跳保活与断线重连，掉线原因短答见 WebSocket 为什么会断开。

这个工具是做什么的 ​

websocat 在终端与 ws/wss 服务器建立全双工连接：stdin 每行作为一条消息发出，服务端推送实时打印。适合验证握手、鉴权、心跳、广播、断线重连，也能脚本化造数据。

一、基本连接与收发 ​

bash
# 连接后进入交互：输入一行回车即发一帧，收到的消息实时打印
websocat ws://localhost:8080/ws

# 详细模式：打印 HTTP 升级握手、请求/响应头、101 状态码
websocat -v ws://localhost:8080/ws

握手成功关键是响应 HTTP/1.1 101 Switching Protocols；401/403 多是鉴权没带对。

二、鉴权与自定义头 ​

bash
# wss（TLS）+ header（token/cookie/origin）
websocat -H 'Authorization: Bearer xxx' -H 'Origin: https://example.com' \
  wss://api.example.com/ws

# 也常用 query 传 token（取决于服务端约定）
websocat "wss://api.example.com/ws?token=xxx"

三、脚本化发消息 / 测心跳与重连 ​

bash
# 定时发心跳，观察服务端是否在空闲超时后断开
( while true; do echo '{"type":"ping"}'; sleep 20; done ) | \
  websocat -v ws://localhost:8080/ws

# 发一批固定消息（测广播/消费）
printf '{"m":1}\n{"m":2}\n{"m":3}\n' | websocat ws://localhost:8080/ws

# 自动重连（-t 保留 TTY；--reconnector 模式按间隔重连，验证客户端重连逻辑）
websocat --reconnect -v ws://localhost:8080/ws

服务端重启、网络中断时，用 --reconnect 观察能否自动恢复、是否补发/去重，正好验证断线重连设计。

四、SSE 与其他 ​

bash
# SSE 是单向 HTTP 流，直接用 curl -N 更通用；websocat 也可连
curl -N -H 'Accept: text/event-stream' http://localhost:8080/events
# SSE 与 WebSocket 取舍见 /backend/web-protocol/sse-vs-websocket-choice.md

常见坑 ​

  1. wss 自签证书：测试环境加 --insecure（或 -k）跳过校验。
  2. 看不到握手细节：排查 401/403/101 一定要 -v，否则只看到数据面。
  3. 把 SSE 当 ws：SSE 是普通 HTTP 单向流，用 curl -N 即可，不必用 ws 客户端。
  4. 粘包/多行 JSON：websocat 默认按行发文本帧，一条消息不要跨行；二进制帧需专门参数。
  5. 鉴权位置搞错：有的服务读 header、有的读 query/cookie，按服务端约定带，先用 -v 确认实际发出的头。
  6. 空闲被断开却不知原因：用定时心跳对比「有/无 ping」的存活时长，可测出服务端/网关空闲超时与心跳间隔是否匹配。

总结 ​

websocat 是 WebSocket 版 netcat：stdin 每行发一帧、服务端推送实时打印，用 -v 看到 HTTP 101 升级握手与鉴权头，用 -H 或 query 带 token/cookie/origin 连 wss，配合 shell while 循环定时发心跳可测服务端空闲超时，printf 灌多行 JSON 可测广播消费，--reconnect 可在服务端重启/断网时验证自动重连与消息去重；注意自签证书加 --insecure、SSE 是单向 HTTP 流应直接用 curl -N、默认按行发文本帧不能跨行，并根据服务端约定选择 header 还是 query 鉴权。