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