graphql subscription 必须通过 websocket 实现，c++ 需用 boost.beast 等第三方库支持；需正确处理连接初始化、订阅/取消协议、心跳保活、id 管理及服务端状态同步。
GraphQL Subscription 必须走 WebSocket，C++ 没有原生支持
GraphQL 的 subscription 不是 HTTP 请求，它依赖长连接——标准实现只走 WebSocket。C++ 标准库不带 WebSocket 客户端，所以你得靠第三方库搭桥，不能用 libcurl 或 httplib 直接发 subscription 查询。
常见错误现象：400 Bad Request 或连接后立刻断开，本质是把 subscription query 当成普通 POST 发给了 HTTP 端点（比如 /graphql），而没连上真正的 WebSocket endpoint（如 ws://localhost:4000/subscriptions）。
- 确认服务端暴露的 WebSocket 地址，通常不是
/graphql，而是类似/subscriptions、/graphql/subscriptions或独立域名 - 检查服务端是否启用 subscription（如 Apollo Server 需配
subscriptions选项；Hasura 默认开启但路径固定为/subscriptions） - 别在 HTTP 客户端里硬塞
{"query":"subscription {...}"}—— 协议层就不对，服务器根本不会解析
推荐用 Boost.Beast + Boost.Asio 实现 WebSocket 订阅
Boost.Beast 是目前 C++ 里最稳的 WebSocket 客户端方案：零依赖外部 OpenSSL（可选）、异步模型清晰、协议细节封装得当。比 websocketpp 更现代，比 uWebSockets C++ 绑定更可控。
使用场景：需要稳定维持连接、处理重连、解析 JSON 响应、支持自定义心跳或认证头（如 Authorization）。
立即学习“C++免费学习笔记（深入）”；
- WebSocket 连接前需手动拼接
Sec-WebSocket-Protocol（如graphql-ws），否则某些服务端（如 Apollo）拒绝握手 - 发送 subscription 必须遵循协议格式，例如
graphql-ws协议要求先发{"type":"connection_init"}，再发{"type":"subscribe","id":"1","payload":{"query":"subscription{...}"}} - 收到响应是 JSON 字符串流，需自己做
json::parse()（推荐nlohmann/json），注意"type": "next"、"type": "error"、"type": "complete"分类处理 - Beast 默认不自动重连，断线后要手动调用
async_connect并重建订阅 ID 映射关系
如何维持 WebSocket 连接不被中间件断掉？
很多代理（Nginx、Cloudflare）、防火墙或移动网络会在 60 秒无数据时关闭空闲 WebSocket 连接。GraphQL subscription 可能长时间没数据，必须主动保活。
性能 / 兼容性影响：心跳太密（如 5 秒）会增加载荷；太疏（如 90 秒）可能被 Nginx 的 proxy_read_timeout 截断（默认 60 秒）。
- 在
graphql-ws协议下，定期发{"type":"ping"}（服务端应答{"type":"pong"}），不要用 TCP 层 keepalive 代替应用层心跳 - Nginx 配置必须显式放开 WebSocket 头：
proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade"; - 移动端要注意后台进程限制：iOS/Android 可能在 App 切后台后几秒内挂起 WebSocket 线程，此时只能靠服务端推送唤醒或降级为轮询（非 subscription）
订阅 ID 冲突和取消逻辑容易漏写
一个 WebSocket 连接可承载多个 subscription，靠 id 字段区分。但 C++ 没有自动内存管理，如果忘记在析构或取消时发 {"type":"unsubscribe","id":"1"}，服务端可能持续推送已废弃的 stream，甚至泄漏资源。
常见错误现象：重启客户端后收不到新数据，或收到旧 subscription 的残留事件。
- 每个
subscribe请求必须生成唯一id（如用std::atomic<uint64_t></uint64_t>自增，别用时间戳——太快可能重复） - 取消订阅不能只停本地回调，必须走 WebSocket 发
unsubscribe指令，并等待服务端返回{"type":"complete","id":"1"}才算真正清理 - 异常断连时，重连后要重新发所有活跃 subscription（ID 重置），不能复用旧 ID，否则服务端可能报
"Subscriber for <id> already exists"</id>
最难缠的是服务端状态同步：C++ 客户端没法像 JS 那样靠闭包记住上下文，所有 ID、回调函数指针、序列化器都要显式存到 map 或 struct 里，稍不注意就 dangling pointer 或 double-free。
