WebSocket 動態訂閱實戰：建構高穩定性美股行情與訂單簿數據鏈路

在量化策略研發、歷史回測系統建置與自動交易工具開發的過程中，行情數據的即時性、連續性與完整性，是決定模型運算結果與交易執行品質的根本基礎。

過往使用傳統行情介面時，經常遇到各式各樣的問題：REST 輪詢不僅延遲偏高，高頻存取也容易觸發存取限制；一般 WebSocket 每當新增、移除訂閱標的，就必須強制斷線並重新連線，不僅容易引發重連風暴，也會造成訊息重複計算；即便連線沒有中斷，網路輕微波動也會導致 Socket 假死、行情串流中斷，對於高頻策略、盤口因子模型都會造成明顯干擾。

為了徹底改善上述問題，我導入 WebSocket 動態訂閱架構，透過單一長連線重複使用的設計，完成美股即時報價、多層級訂單簿深度數據的完整串接。本文將從核心概念、介面比較、參數配置、程式實作、線上除錯等面向完整分享實戰經驗，同時說明此架構在量化回測、交易模型與數據工具中的應用價值。

一、核心概念：何謂動態增減訂閱

動態增減訂閱，意指維持一條持續運作的 WebSocket 長連線，透過標準指令線上新增、移除交易標的編碼，全程無須中斷、重建連線。

相較於傳統數據擷取方式，彼此差異十分明確：

1. REST 輪詢：透過週期性請求主動拉取數據，即時性存在先天缺陷；

2. 一般 WebSocket：變更訂閱清單就必須重建連線，難以確保前後狀態一致；

3. 動態訂閱 WebSocket：在既有連線上變更訂閱關係，從架構層面保障數據串流不中斷，非常適合多標的同步觀測、動態調倉等量化場景。

二、主流行情介面橫向比較

針對美股 Tick 數據、多層級訂單這兩類量化核心數據，我以數據延遲、連線穩定性、數據時序、維護成本四大維度，比較三種主流接入方案。

1. REST 介面

實作門檻低，但數據更新頻率完全取決於輪詢間隔，無法滿足 Tick 等級的高頻需求。高頻輪詢除了容易遭到存取限制，也會造成數據延遲、內容失真，不僅影響即時交易，更會導致回測資料產生偏差，不適合量化模型開發。

2. 基礎 WebSocket

長連線由伺服器主動推送數據，延遲表現優於 REST。但其核心短板明顯：新增 / 取消訂閱標的時，必須銷毀並重建連線。頻繁重連會引發連線風暴，造成訂閱狀態不一致、訂單簿欄位錯位，進而污染因子運算結果，讓回測結論與真實盤面出現落差。

3. 支援動態訂閱的 WebSocket

這是本次最終導入的方案。此架構遵循標準 WSS 協定，依照金融商品分類獨立接入位址，原生支援動態訂閱與訂單簿快照 + 增量更新兩大能力。單一長連線即可彈性管理所有訂閱標的，傳輸效率與執行穩定性兼備，是量化數據採集的最佳選擇。

美股行情專用 WSS 位址：

wss://quote.alltick.co/quo...

外匯、加密資產、貴金屬等品項皆有獨立端點，介面分層清晰，便於多品項採集服務統一開發與維護。

三、場景化參數配置（開發與回測適用）

以下依照實務開發、除錯、線上維護的常用場景逐一說明，所有指令皆遵循介面官方規範，可直接套用在數據擷取模組與回測數據管道。所有訂閱相關指令統一使用 cmd_id=22004。

場景一：連線初始化 + 批次訂閱美股標的

常見問題

服務啟動後無法接收行情、請求封包格式錯誤，造成回測資料初始化失敗。

配置方式

在 on_open 連線成功回呼內發送指令，範例封包如下：

{  "cmd_id": 22004,  "action": "subscribe",  "code": ["NASDAQ:AAPL","NASDAQ:TSLA"]}

驗證方式

檢視系統日誌，確認完整請求封包內容、標的代碼格式皆正確，並觀察首批行情正常推送。

場景二：服務執行中新增訂閱標的

常見問題

為新增標的強制重建連線，產生多餘連線、數據時序混亂。

配置方式

保持原有長連線不中斷，單獨發送新增訂閱指令：

{  "cmd_id": 22004,  "action": "subscribe",  "code": ["NASDAQ:MSFT"]}

驗證方式

確認舊有行情持續推送，新標的數據正常接收，同時同步更新本機維護的訂閱清單。

場景三：服務執行中取消訂閱標的

常見問題

解除訂閱後仍持續收到資料，也就是「幽靈訂閱」，干擾後續因子運算。

配置方式

將 action 改為 unsubscribe，填入欲移除的標的代碼：

{  "cmd_id": 22004,  "action": "unsubscribe",  "code": ["NASDAQ:TSLA"]}

驗證方式

目標標的立即停止數據推送，並從本機訂閱集合中刪除對應代碼。

場景四：重複發送相同訂閱指令

常見問題

連續送出重複請求，造成客戶端重複運算、增加系統負載。

配置說明

伺服器會自動靜默處理重複請求，不會回傳錯誤。指令範例：

{  "cmd_id": 22004,  "action": "subscribe",  "code": ["NASDAQ:AAPL"]}

驗證方式

系統無錯誤日誌，建議在客戶端新增去重邏輯，避免無效請求。

場景五：發送空陣列執行訂閱 / 解除訂閱

常見問題

code 欄位傳入空陣列，屬於非法參數，會直接導致連線強制中斷。

配置說明

禁止使用以下格式，務必在客戶端增加前置參數檢查，提前攔截空請求：

{  "cmd_id": 22004,  "action": "subscribe",  "code": []}

驗證方式

客戶端攔截後不再向伺服器發送此類請求，確保數據採集服務不意外斷線。

四、動態訂閱 WebSocket 之核心價值

4.1 重用連線，杜絕重連風險

全域統一使用 cmd_id=22004 作為訂閱指令，增刪標的無須建立、銷毀 Socket。徹底杜絕重連風暴與數據空窗，保證 Tick 數據、訂單簿數據的時序連續。對於時間序列模型、高頻交易策略而言，連續、有序的原始數據，是回測有效、實盤可複現的基礎。

4.2 數據分層設計，優化傳輸與運算效率

介面將數據劃分為即時報價與訂單簿深度兩大模組：即時報價推送最新價、成交量、基礎買賣一檔數據；訂單簿採用「全量快照初始化 + 增量更新」模式。一方面降低網路傳輸負載，另一方面避免訂單簿欄位跳變、錯位，保證盤口掛單密度、買賣壓力等因子的運算精準度。

4.3 原生心跳機制，適配複雜網路

介面內建心跳偵測能力，搭配程式層心跳設定，可快速識別 Socket 假死、網路中斷等異常。同時介面相容 Python、Java、Go 等主流量化開發語言，可無縫嵌入數據採集、策略引擎、回測框架。

4.4 全品項相容，拓展策略邊界

介面除美股外，還支援港股、外匯、貴金屬、加密資產等品項。一套接入邏輯可複用至多類業務場景，大幅降低介面開發與維護成本。

五、Python 完整實作程式碼

下方為生產等級程式，嚴格遵循單連線動態訂閱邏輯，內建狀態管理、空值過濾、例外捕捉與心跳保活，可直接部署為獨立數據採集服務，對接回測框架與實盤策略引擎。

# 連線位址與規範請參考官方 API 文件
# 股票類 WSS 位址
# wss://quote.alltick.co/quote-stock-b-ws-api?token=YOUR_TOKEN
import websocket
import json

# 本機訂閱集合，用於狀態管理與資料去重
subscriptions = set()
# 替換為個人有效授權金鑰
TOKEN = "YOUR_TOKEN"
WSS_URL = f"wss://quote.alltick.co/quote-stock-b-ws-api?token={TOKEN}"

def send_subscribe(ws, action, code_list):
    """訂閱/解除訂閱共用函式，固定 cmd_id=22004"""
    if not code_list:
        return
    req_data = {
        "cmd_id": 22004,
        "action": action,
        "code": code_list
    }
    try:
        ws.send(json.dumps(req_data))
    except Exception:
        return

def on_open(ws):
    """連線建立後執行批次初始訂閱"""
    init_codes = ["NASDAQ:AAPL", "NASDAQ:TSLA"]
    global subscriptions
    subscriptions.update(init_codes)
    send_subscribe(ws, "subscribe", init_codes)
    print("WebSocket 連線建立，初始訂閱完成")

def on_message(ws, message):
    """數據回呼：空值過濾 + 基礎解析，可對接下游運算模組"""
    if not message:
        return
    try:
        data = json.loads(message)
        code = data.get("code", "")
        price = data.get("price", 0)
        open_24h = data.get("open_24h", 0)
        # 過濾無效數據，避免干擾模型運算
        if not code or price <= 0 or open_24h <= 0:
            return
        print(f"行情推送 | 標的：{code}，最新價格：{price}")
        # 此處可擴充：數據寫入資料庫、轉送至回測/策略引擎
    except json.JSONDecodeError:
        return

def on_error(ws, error):
    """捕捉連線異常，可對接告警機制"""
    print(f"連線異常：{str(error)}")

def on_close(ws, close_code, close_msg):
    """連線斷開，清空本機狀態，可擴充自動重連邏輯"""
    global subscriptions
    subscriptions.clear()
    print(f"連線已斷開，狀態碼：{close_code}")

# 初始化 WebSocket 實體
ws_app = websocket.WebSocketApp(
    WSS_URL,
    on_open=on_open,
    on_message=on_error,
    on_close=on_close
)

if __name__ == "__main__":
    # 動態增刪訂閱（可整合至策略調倉邏輯）
    # send_subscribe(ws_app, "subscribe", ["NASDAQ:MSFT"])  # 新增標的
    # send_subscribe(ws_app, "unsubscribe", ["NASDAQ:TSLA"]) # 移除標的
    # 10秒心跳保活，維持長連線穩定
    ws_app.run_forever(ping_interval=10)

六、線上異常排查與優化方案

結合數據採集服務長期運行經驗，整理四類高頻問題、排查方式與優化手段，避免數據異常影響回測、實盤交易。

6.1 高頻 Tick 數據造成訊息堆積

現象：交易熱絡時段，海量 Tick 數據持續推送，回呼處理不及，程式出現卡頓。

影響：數據時序偏移，盤口因子、短期趨勢模型運算失真。

排查：分析日誌時間戳，確認訊息連續堆積。

優化：拆分數據處理與業務邏輯，回呼層僅做過濾與轉發，複雜運算遷移至非同步佇列。

6.2 網路抖動導致 Socket 假死

現象：網路短暫中斷，未觸發 on_close，但數據推送停止。

影響：行情採集中斷，策略停擺、回測資料缺失。

排查：新增數據接收逾時監控。

優化：在原生心跳基礎上增加業務層逾時判斷，逾時後主動斷線並執行有序重連。

6.3 高頻操作引發訂閱狀態不一致

現象：短時間連續增刪標的，本機集合與伺服器狀態錯位，出現幽靈訂閱。

影響：多餘數據流入運算模組，增加系統負載。

排查：比對本機標的清單與實際推送數據。

優化：為訂閱操作新增循序鎖，操作完成後同步本機狀態。

6.4 標的編碼格式錯誤導致訂閱失敗

現象：使用 AAPL 簡寫編碼，指令送出正常，但無任何數據推送。

影響：目標標的資料缺失，回測與策略樣本不全。

排查：檢核請求內 code 欄位格式。

優化：統一採用「交易所：代碼」格式，程式層新增格式檢核。

七、功能邊界說明

✅ 支援：單條 WebSocket 連線內，動態增刪美股、港股等標的編碼，滿足多標的同步採集需求。

❌ 不支援：跨連線同步訂閱狀態、回溯歷史 Tick 數據、使用非 cmd_id=22004 的私有指令。

八、總結

該動態訂閱方案已長時間用於美股行情採集、盤口因子挖掘、量化策略回測與實盤。上線後，重連、數據錯位相關異常大幅減少。

從量化角度來看，穩定且連續的底層數據，是回測可信、實盤可複現的核心。整套架構邏輯清晰、可追溯性強，既可作獨立數據服務，也能嵌入各類量化框架，同時可移植至多個金融品項，具備良好擴展性，適合量化研究者與開發者使用。