股票API接口如何设计实时行情订阅和数据缓存机制？

对于使用股票 API 构建行情看板、交易终端的金融科技开发者来说，难点不仅是获取实时价格，还包括如何减少重复请求、应对高并发读取，以及避免旧行情覆盖新行情。

一种实用的设计是：通过 WebSocket 接收实时行情，在服务端统一处理数据，再使用 Redis 缓存最新状态。这样既能减少上游连接数量，也能让多个应用实例共享行情数据。

为什么股票 API 需要 WebSocket 和缓存

REST API 适合按需查询行情快照和历史 K 线，但如果客户端持续轮询最新价格，就可能产生大量重复请求。WebSocket 则适合接收连续推送的 Tick 数据。

两者解决的问题不同：WebSocket 负责行情接入，Redis 负责快速读取。推荐的基本架构是：

行情源 → WebSocket 接入服务 → 数据校验 → Redis → 应用服务 → 客户端

行情接入服务维护上游连接，应用服务从缓存读取最新报价。不要让每个前端用户都单独连接上游行情源，也不要把 API Token 暴露在浏览器代码中。

如何通过 WebSocket 订阅实时股票行情

以 AllTick API 为例，港股、美股和 A 股使用股票 WebSocket 接口。订阅最新成交 Tick 时，需要在连接 URL 中携带有效 Token，并按接口协议发送请求。

连接地址：

wss://quote.alltick.co/quote-stock-b-ws-api?token=YOUR_TOKEN

订阅请求示例：

{
  "cmd_id": 22004,
  "seq_id": 1,
  "trace": "stock-demo-001",
  "data": {
    "symbol_list": [
      {"code": "700.HK"}
    ]
  }
}

收到订阅确认后，服务端会推送相应行情。开发者应解析返回的 JSON，并根据实际消息结构提取股票代码、成交价、成交量和报价时间。

生产环境还需要定期发送心跳、处理连接异常，并在断线后重新订阅。AllTick 的该类接口要求每 10 秒发送一次心跳；重连时也应遵守对应套餐的连接限制。

如何设计 Redis 实时行情缓存

行情页面通常需要的是每只股票的最新状态，而不是每次更新的完整历史记录。可以按股票代码设置独立的 Redis Key，例如：

stock:quote:700.HK

缓存值可以采用以下结构：

{
  "symbol": "700.HK",
  "price": 320.50,
  "volume": 125000,
  "timestamp": 1787041200000
}

以上仅为数据结构示例，并非真实行情。实际字段应以接口返回内容为准。

收到新 Tick 后，接入服务更新对应缓存；客户端查询时直接读取 Redis，避免重复请求上游。若需要保存逐笔历史，应另外写入持久化存储或消息队列，不能把只保留最新状态的缓存当作历史数据库。

如何避免旧行情覆盖新行情

网络延迟、消息积压和断线重连都可能导致旧消息晚于新消息到达。如果每次收到数据就直接覆盖缓存，页面可能出现价格回退。

因此，更新前应比较同一股票的报价时间：

if new_tick["timestamp"] > old_tick["timestamp"]:
    update_cache(new_tick)

这段代码仅展示判断逻辑。多线程或多实例环境下，读取、比较和写入必须通过 Redis Lua 脚本等原子操作完成，避免并发更新产生竞争。若时间戳相同，还应结合接口提供的序号或其他可靠规则处理，不能仅凭接收顺序判断新旧。

如何兼顾实时性与历史数据

缓存和历史存储应承担不同职责：

如果系统需要从 Tick 生成分钟 K 线，还应处理重复消息、时间窗口边界、交易时段和缺失数据等问题。Redis 中的最新报价不能直接替代经过校验的历史数据。

如何开始接入

对于希望快速交付行情功能的金融科技开发者，可以先验证单只股票的 WebSocket 订阅，再加入 Redis 缓存、断线重连和并发读取测试，逐步扩展到多只股票。

可以先查看 AllTick WebSocket 行情订阅文档，核对认证方式、请求协议和返回字段，再根据应用的订阅规模设计缓存与数据处理流程。

合理划分行情接入、最新状态缓存和历史存储，才能让股票 API 应用在提高读取效率的同时，兼顾数据一致性与后续扩展能力。