行情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

使用建议

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

多市场统一 symbol 示意图

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'] }
}));

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

常见错误

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 时，首先明确当前处于哪个阶段：

启动系统
展示页面
实时监控

根据阶段选择合适的接口。
可以避免系统设计不合理导致的性能问题和维护困难。

系列说明

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

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

参考资料

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

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

行情API的正确使用方式