行情API的正确使用方式：从接口调通到系统设计

在行情系统开发中，常见的问题不是"接口调不通"，而是"接口能调通，但系统设计不合理"。本文从工程实践角度，讲解如何正确理解和使用行情 API。

---

常见问题：接口能调通，但系统设计不合理

在行情系统开发中，常见以下问题：

• 首页行情列表每秒轮询 K 线接口获取最新价
• 所有页面都建立 WebSocket 连接以实现"实时更新"
• 系统启动时直接订阅 WebSocket，但未获取可用品种列表
• 页面切换时旧的 WebSocket 连接未关闭

这些问题的根源在于缺乏正确的使用心智模型，即不清楚在什么阶段该使用什么接口。

大多数 API 文档会说明接口返回的数据结构，但不会说明接口的适用场景和使用时机。

---

行情 API 的本质：数据分层

行情 API 不是接口的集合，而是一套数据分层系统。

构建行情系统时，系统在不同阶段对数据的需求完全不同：

1. 数据使用阶段

• 启动阶段：系统需要获取可交易品种列表
• 展示阶段：页面需要显示当前价格
• 实时阶段：需要在价格变化时主动推送

2. 数据类型

• 快照：当前时刻的价格、涨跌幅（适合列表、首页）
• 历史：过去一段时间的价格走势（适合图表、回测）
• 持续流：价格变化时主动推送（适合实时盯盘、交易执行）

3. 系统复杂度

• REST API：简单、稳定、易维护，需要主动轮询
• WebSocket：实时、高效，但需要处理连接管理、重连、心跳

理解这三个维度，可以明确每个接口的适用场景。

---

行情 API 的分层设计

1. 可用交易品种（Symbols）

系统启动的第一步是获取可用品种列表。

硬编码品种代码会导致以下问题：

• 退市品种无法及时移除
• 新上市品种无法及时添加

建议在系统启动时调用品种列表接口，并缓存结果。

多市场统一命名的价值

统一的命名规则可以用同一套代码逻辑处理不同市场的数据：

• 港股：700.HK、9988.HK
• 美股：AAPL.US、TSLA.US
• 外汇：EURUSD、GBPUSD

这避免了为每个市场编写适配层。

接口示例

GET /v1/symbols/available?market=HK&limit=10

使用建议

• 系统启动时调用一次，缓存结果
• 不要在每次查询行情前调用此接口
• 定期更新建议频率为每天一次

---

2. Ticker（实时快照）

Ticker 接口适用于大部分"显示当前价格"的场景：行情列表页、首页概览、定时刷新的看板。

使用 K 线接口获取最新价存在以下问题：

• K 线接口返回的数据结构更复杂
• 需要处理时间对齐问题
• 无法一次查询多个品种

Ticker 接口的优势：

• 返回数据轻量
• 一次请求可查询多个品种（通常支持 50 个左右）
• 不需要处理时间对齐问题

接口示例

GET /v1/market/ticker?symbols=700.HK,AAPL.US

返回数据

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "symbol": "700.HK",
      "last_price": "602.5",
      "volume_24h": "16003431",
      "high_24h": "606",
      "low_24h": "598",
      "timestamp": 1768982936000
    }
  ]
}

使用建议

只要不是需要实时价格跳动的场景，Ticker + 定时刷新（5-10 秒）即可满足需求。

---

3. K 线（结构化历史）

K 线接口的核心参数是 interval（时间间隔），决定了数据的颗粒度。

不同的分析场景对数据颗粒度的要求不同：

• 1m：1 分钟 K 线，适合短线交易、实时图表（数据量大，精度高）
• 1h：1 小时 K 线，适合日内分析（数据量适中）
• 1d：日 K 线，适合中长期分析、回测（数据量小，适合长周期策略）

接口示例

GET /v1/market/kline?symbol=AAPL.US&interval=1d&limit=30

使用建议

• 图表展示：使用 limit 参数（如"显示最近 30 天"）
• 历史回测：使用时间范围参数（如"2023 年 1 月到 3 月的数据"）

---

4. WebSocket（实时流）

WebSocket 的代价包括：

• 维护长连接（心跳、重连、异常处理）
• 处理订阅管理
• 处理消息队列
• 处理网络波动

适用场景

• 实时盯盘（延迟要求在秒级以内）
• 价格预警（价格触发阈值时需要立即通知）
• 高频数据监控（需要毫秒级数据更新）

不适用场景

• 行情列表页
• 历史图表
• 低频监控

以上场景使用 REST API + 定时刷新即可。

接口示例

const ws = new WebSocket('wss://api.example.com/v1/realtime?api_key=YOUR_API_KEY');

ws.onopen = () => {
  ws.send(JSON.stringify({
    cmd: 'subscribe',
    data: { channel: 'ticker', symbols: ['700.HK'] }
  }));
};

设计限制

外汇品种通常仅支持 ticker 频道（不支持 depth 和 trade），因为外汇市场是 OTC 市场，没有集中的订单簿。股票和加密货币支持 ticker、depth、trade 三种频道。

---

完整使用路径示例

以港股行情监控系统为例：

Step 1：启动时拉取可用品种

GET /v1/symbols/available?market=HK&limit=100

目的：获取系统支持的港股品种，缓存到本地。

---

Step 2：页面展示用 Ticker + K 线

首页行情列表

GET /v1/market/ticker?symbols=700.HK,9988.HK,3690.HK

图表展示

GET /v1/market/kline?symbol=700.HK&interval=1d&limit=30

刷新策略：每 5-10 秒刷新一次 Ticker，K 线按需加载（用户切换图表时才加载）。

刷新频率建议：

• 太快（如每秒刷新）会增加服务器压力
• 太慢（如 30 秒）数据实时性不足
• 5-10 秒是平衡点

---

Step 3：关键模块用 WebSocket

仅在需要实时推送的场景建立 WebSocket 连接：

ws.send(JSON.stringify({
  cmd: 'subscribe',
  data: { channel: 'ticker', symbols: ['700.HK'] }
}));

退出实时监控页面时，必须取消订阅并关闭连接。否则会导致连接数超限，影响新用户建立连接。

---

工程小结

使用行情 API 时，需要明确以下要点：

• 启动阶段：调用 symbols 接口获取可用品种，缓存结果
• 展示阶段：使用 Ticker 接口获取实时快照，K 线接口获取历史数据
• 实时阶段：仅在必要场景使用 WebSocket，其他场景使用 REST API + 定时刷新
• 刷新频率：Ticker 建议 5-10 秒，K 线按需加载
• 连接管理：WebSocket 连接必须在页面退出时关闭

---

常见错误

1. 过度使用 WebSocket

错误做法：系统启动就建立 WebSocket，订阅所有品种。

问题：首页显示 50 个品种的行情，订阅所有品种会导致用户量上升时服务器连接数超限。

正确做法：大部分场景使用 REST API，仅在需要实时推送的模块使用 WebSocket。

---

2. K 线接口滥用

错误做法：每秒调用 K 线接口获取最新价。

问题：K 线接口是为历史数据设计的，不是为实时价格设计的。频繁调用浪费资源，且可能因时间对齐问题导致数据不准确。

正确做法：K 线用于历史数据和图表，实时价格使用 Ticker 或 WebSocket。

---

3. Symbol 不缓存

错误做法：每次查询行情前都调用 /v1/symbols/available。

问题：可用品种列表通常不会频繁变化，每次都查询是浪费。

正确做法：启动时调用一次，缓存结果，定期（如每天）更新。

---

4. Interval 选择不当

错误做法：不管什么场景都使用 1m（1 分钟 K 线）。

问题：1 分钟 K 线数据量大，如果只是查看"最近一个月的走势"，使用日 K 线即可。使用 1 分钟 K 线浪费带宽，增加前端渲染压力。

正确做法：

• 实时图表：1m 或 5m
• 日内分析：1h
• 中长期分析：1d

---

5. 混淆行情 API 与交易 API

错误做法：直接使用行情数据做下单决策，不考虑延迟和数据完整性。

问题：行情 API 提供的是市场数据，主要用于展示和分析。交易操作（下单、撤单）需要对接交易所的交易 API。

正确做法：行情 API 用于数据展示和策略分析，交易操作使用交易 API。

---

系列说明

本文是「行情 API 的工程化使用方式」系列的第一篇，后续将继续讲解：

• WebSocket 实战：连接管理、心跳机制、数据补偿
• K 线数据的正确使用方式：interval 选择、时间对齐、数据缓存策略
• 行情系统的性能优化实践：从接口调用到前端渲染的完整优化方案
• 多市场行情数据的统一处理：如何用一套代码处理港股、美股、外汇的差异

---

参考资料

本文基于 TickDB API v1.0.0 撰写。完整接口参数说明、错误码处理、API 参考：

• GitHub：https://github.com/TickDB
• 文档：https://docs.tickdb.ai