行情API的正确使用方式
在行情系统开发中，常见以下问题： 这些问题的根源在于缺乏正确的使用心智模型。 大多数 API 文档会说明接口返回的数据结构。 行情 API 不是接口的集合，而是一套数据分层系统。 构建行情系统时，系统在不同阶段对数据的需求完全不同： 理解这三个维度，可以明确每个接口的适用场景。 系统启动的第一步是获取可用品种列表。 硬编码品种代码会导致以下问题： 建议在系统启动时调用品种列表接口，并缓存结果。 多市场统一命名的价值 统一的命名规则可以用同一套代码逻辑处理不同市场的数据： 这避免了为每个市场编写适配层。 接口示例 使用建议 Ticker 接口适用于大部分"显示当前价格"的场景。 使用 K 线接口获取最新价存在以下问题： Ticker 接口的优势： 接口示例 返回数据 使用建议 只要不是需要实时价格跳动的场景。 K 线接口的核心参数是 不同的分析场景对数据颗粒度的要求不同： 接口示例 使用建议 WebSocket 的代价包括： 适用场景 不适用场景 以上场景使用 REST API + 定时刷新即可。 接口示例 设计限制 外汇品种通常仅支持 ticker 频道（不支持 depth 和 trade）。 以港股行情监控系统为例： 目的：获取系统支持的港股品种，缓存到本地。 首页行情列表 图表展示 刷新策略：每 5-10 秒刷新一次 Ticker。 刷新频率建议： 仅在需要实时推送的场景建立 WebSocket 连接： 退出实时监控页面时，必须取消订阅并关闭连接。 错误做法：系统启动就建立 WebSocket，订阅所有品种。 问题：首页显示 50 个品种的行情。 正确做法：大部分场景使用 REST API。 错误做法：每秒调用 K 线接口获取最新价。 问题：K 线接口是为历史数据设计的。 正确做法：K 线用于历史数据和图表。 错误做法：每次查询行情前都调用 问题：可用品种列表通常不会频繁变化。 正确做法：启动时调用一次，缓存结果。 错误做法：不管什么场景都使用 问题：1 分钟 K 线数据量大。 正确做法： 错误做法：直接使用行情数据做下单决策。 问题：行情 API 提供的是市场数据。 正确做法：行情 API 用于数据展示和策略分析。 使用行情 API 时，首先明确当前处于哪个阶段： 根据阶段选择合适的接口。 本文是「行情 API 的工程化使用方式」系列的第一篇。 本文基于 TickDB API v1.0.0 撰写。行情 API 的正确使用方式
常见问题
即不清楚在什么阶段该使用什么接口。
但不会说明接口的适用场景和使用时机。行情 API 的本质：数据分层
1. 数据使用阶段
2. 数据类型
3. 系统复杂度
行情 API 的分层设计
1. 可用交易品种（Symbols）
700.HK、9988.HKAAPL.US、TSLA.USEURUSD、GBPUSDGET /v1/symbols/available?market=HK&limit=10
2. Ticker（实时快照）
行情列表页、首页概览、定时刷新的看板。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 线（结构化历史）
interval（时间间隔）。
决定了数据的颗粒度。1m：1 分钟 K 线，适合短线交易、实时图表1h：1 小时 K 线，适合日内分析1d：日 K 线，适合中长期分析、回测GET /v1/market/kline?symbol=AAPL.US&interval=1d&limit=30limit 参数（如"显示最近 30 天"）
4. WebSocket（实时流）
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'] }
}));
};
因为外汇市场是 OTC 市场，没有集中的订单簿。
股票和加密货币支持 ticker、depth、trade 三种频道。
完整使用路径示例
Step 1：启动时拉取可用品种
GET /v1/symbols/available?market=HK&limit=100Step 2：页面展示用 Ticker + K 线
GET /v1/market/ticker?symbols=700.HK,9988.HK,3690.HKGET /v1/market/kline?symbol=700.HK&interval=1d&limit=30
K 线按需加载（用户切换图表时才加载）。Step 3：关键模块用 WebSocket
ws.send(JSON.stringify({
cmd: 'subscribe',
data: { channel: 'ticker', symbols: ['700.HK'] }
}));
否则会导致连接数超限，影响新用户建立连接。常见错误
1. 过度使用 WebSocket
订阅所有品种会导致用户量上升时服务器连接数超限。
仅在需要实时推送的模块使用 WebSocket。2. K 线接口滥用
不是为实时价格设计的。
频繁调用浪费资源，且可能因时间对齐问题导致数据不准确。
实时价格使用 Ticker 或 WebSocket。3. Symbol 不缓存
/v1/symbols/available。
每次都查询是浪费。
定期（如每天）更新。4. Interval 选择不当
1m（1 分钟 K 线）。
如果只是查看"最近一个月的走势"，使用日 K 线即可。
使用 1 分钟 K 线浪费带宽，增加前端渲染压力。1m 或 5m1h1d5. 混淆行情 API 与交易 API
不考虑延迟和数据完整性。
主要用于展示和分析。
交易操作（下单、撤单）需要对接交易所的交易 API。
交易操作使用交易 API。
总结
可以避免系统设计不合理导致的性能问题和维护困难。系列说明
后续将继续讲解：参考资料
完整接口参数说明、错误码处理、API 参考：
