行情 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
这避免了为每个市场编写适配层。
接口示例
bash
GET /v1/symbols/available?market=HK&limit=10使用建议
- 系统启动时调用一次，缓存结果
- 不要在每次查询行情前调用此接口
- 定期更新建议频率为每天一次
2. Ticker（实时快照）
Ticker 接口适用于大部分"显示当前价格"的场景：行情列表页、首页概览、定时刷新的看板。
使用 K 线接口获取最新价存在以下问题：
- K 线接口返回的数据结构更复杂
- 需要处理时间对齐问题
- 无法一次查询多个品种
Ticker 接口的优势：
- 返回数据轻量
- 一次请求可查询多个品种（通常支持 50 个左右）
- 不需要处理时间对齐问题
接口示例
bash
GET /v1/market/ticker?symbols=700.HK,AAPL.US返回数据
json
{
"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 线，适合中长期分析、回测（数据量小，适合长周期策略）
接口示例
bash
GET /v1/market/kline?symbol=AAPL.US&interval=1d&limit=30使用建议
- 图表展示：使用
limit参数（如"显示最近 30 天"） - 历史回测：使用时间范围参数（如"2023 年 1 月到 3 月的数据"）
4. WebSocket（实时流）
WebSocket 的代价包括：
- 维护长连接（心跳、重连、异常处理）
- 处理订阅管理
- 处理消息队列
- 处理网络波动
适用场景
- 实时盯盘（延迟要求在秒级以内）
- 价格预警（价格触发阈值时需要立即通知）
- 高频数据监控（需要毫秒级数据更新）
不适用场景
- 行情列表页
- 历史图表
- 低频监控
以上场景使用 REST API + 定时刷新即可。
接口示例
javascript
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：启动时拉取可用品种
bash
GET /v1/symbols/available?market=HK&limit=100目的：获取系统支持的港股品种，缓存到本地。
Step 2：页面展示用 Ticker + K 线
首页行情列表
bash
GET /v1/market/ticker?symbols=700.HK,9988.HK,3690.HK图表展示
bash
GET /v1/market/kline?symbol=700.HK&interval=1d&limit=30刷新策略：每 5-10 秒刷新一次 Ticker，K 线按需加载（用户切换图表时才加载）。
刷新频率建议：
- 太快（如每秒刷新）会增加服务器压力
- 太慢（如 30 秒）数据实时性不足
- 5-10 秒是平衡点
Step 3：关键模块用 WebSocket
仅在需要实时推送的场景建立 WebSocket 连接：
javascript
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 参考：