RESTful API 设计与 WebSocket 集成

REST 把 CRUD 映射到 HTTP：GET 用于读取，POST 用于创建，PATCH 用于局部更新，DELETE 用于删除。要诚实地使用状态码——返回 200 却附带一段错误 JSON 会让客户端崩溃。

在路径里做版本管理（/v1/），对大列表分页（对仅追加的流采用游标式数据源），并为破坏性变更设置一段弃用过渡期来做好文档说明。

API 密钥用于标识身份；secret 用于证明身份。对于交易类接口，要对一个规范化字符串（方法 + 路径 + 请求体 + 时间戳）做 HMAC，这样 secret 永远不会在网络上明文传输。拒绝过期的时间戳以阻断重放攻击——±30s 是常用的窗口。

OAuth 适合第三方应用；纯交易所机器人通常仍采用 密钥 + HMAC。限流方面：预期会收到 429，并遵守 Retry-After。

会话以一次带 Upgrade: websocket 的 HTTP GET 开始；服务器返回 101 Switching Protocols。此后，相比 HTTP 轮询反复进行的 TLS 握手，传输帧的开销要低得多。

订阅消息通常是 JSON：包含 method、channels，有时还有用于私有成交的鉴权签名。

成交流是逐笔数据；订单簿则是 快照 + 增量，并带有序列号。如果你漏掉了某些序列号，就要从 REST 快照重新同步，然后只应用序列号 > 快照 的增量。

心跳：发送 ping 或预期接收服务器的 ping；用带抖动的退避来重连，以避免惊群效应。

GraphQL 能为仪表盘削减过度获取（over-fetching）；许多交易所在交易热点路径上仍然提供 REST。OpenAPI（Swagger）规范有助于代码生成与 QA——务必让示例可以直接复制粘贴。

在一个任务里运行 WebSocket 循环，把最新价格推入一个线程安全的 map，并对外暴露 HTTP 以做健康检查。记录重连次数；当它激增时发出告警。