WebSocket动态订阅增量控流手记：港股实时行情序列号断档自动修复方案

一、课程实操场景

这段时间在金融行情开发实训中，我们搭建港股量化行情可视化服务，实训需求是支持学员自选股频繁切换、量化策略轮换标的。最开始图省事，标的增减就直接断开WebSocket重连，实操跑通后上线测试才发现一堆数据稳定性问题。

批量切换标的会触发大量重连请求，形成重连风暴；每次重建连接都会清空本地序列号缓存，加上网络轻微波动，实时推送的Tick序列号经常出现断层。如果不做自动补缺，K线成交额、分时均价、盘口深度全部失真，手动修复数据耗时极长，实训复盘效率很低。

对比REST轮询、全量重连两种基础方案后，我们基于长连接动态订阅能力完成改造，搭配序列号校验、区间补缺、消息缓冲整套逻辑，解决序列跳变带来的数据错乱，下面记录完整实操流程与踩坑经验。

二、实训核心需求

1. 单条WebSocket长连接承载多只港股标的，增减自选股无需断开链路，实时行情不间断；
2. 每条实时Tick携带自增序列号，消费端实时校验连续性，出现缺口自动拉取历史数据补缺；
3. 本地维护订阅标的集合，过滤重复订阅、无效指令，避免多余实时推送占用资源；
4. 自带心跳保活、异常重连、缓冲区兜底，保证行情指标持续正常计算。

三、实操中遇到的数据问题

1. 全量重连重置序列号，大片实时行情缺失
   增减标的就重建Socket，本地序列号缓存清空，新连接序列号从头计数，新旧数据流无法衔接，批量丢失Tick数据。
2. 网络抖动、消费阻塞造成序列号小幅跳跃
   网络短时丢包、本地代码处理速度跟不上推送，序列号直接跳号，缺失的Tick会直接影响成交量、均价计算结果。
3. 快速增删标的引发指令竞态，订阅状态错乱
   连续下发多条订阅指令，本地标的集合和服务端订阅列表不一致，出现重复推送、标的漏推送。
4. 无消息缓冲兜底，补缺数据与实时推送乱序覆盖
   检测到数据缺口后等待历史数据，新的实时Tick持续涌入，新旧数据混杂，行情曲线出现明显毛刺。

四、核心概念定义

动态增减订阅：依靠单条持续在线的WebSocket长连接，通过专属订阅指令添加/删除标的编码，实时更新服务端订阅列表，全程不关闭、重建Socket，保障实时行情持续接收；区别于定时轮询，也不用每次改标的都重连链路。

五、实操对照表格

六、完整实操代码（Python）

import websocket
import json
import threading
import time

# 港股行情WebSocket接入地址
WS_STOCK_URL = "wss://quote.alltick.co/quote-stock-b-ws-api?token=YOUR_TOKEN"

# 本地状态变量
subscriptions = set()  # 存储当前订阅标的，自动去重
last_seq = None        # 记录上一条Tick序列号，用于连续性校验
msg_buffer = []        # 缺口缓冲队列，补齐数据后统一消费
ws_app = None

def send_subscribe_action(action: str, code_list: list):
    """下发动态订阅指令，add新增/del取消，固定指令ID 22004"""
    global ws_app
    if not ws_app or not ws_app.sock or not ws_app.sock.connected:
        return
    if len(code_list) == 0:
        return
    unique_codes = list(set(code_list))
    sub_frame = {
        "cmd_id": 22004,
        "action": action,
        "code": unique_codes
    }
    ws_app.send(json.dumps(sub_frame))
    # 同步更新本地订阅集合
    if action == "add":
        for c in unique_codes:
            subscriptions.add(c)
    elif action == "del":
        for c in unique_codes:
            if c in subscriptions:
                subscriptions.remove(c)

def request_missing_tick(start_seq: int, end_seq: int):
    """序列号出现缺口，调用历史接口拉取缺失Tick"""
    print(f"检测序列缺口，拉取缺失区间 seq:{start_seq+1} ~ {end_seq-1}")
    # 此处可补充HTTP历史Tick查询逻辑，有序插入缓冲区

def check_seq_continuity(current_seq: int) -> bool:
    """实时校验序列号是否连续，断档自动触发补缺"""
    global last_seq
    if last_seq is None:
        last_seq = current_seq
        return True
    if current_seq != last_seq + 1:
        request_missing_tick(last_seq, current_seq)
        return False
    last_seq = current_seq
    return True

def on_open(ws):
    """连接建立完成，初始化批量订阅标的"""
    init_codes = ["00700.HK", "9988.HK", "09992.HK"]
    send_subscribe_action("add", init_codes)
    print("WebSocket连接成功，完成初始标的订阅，开始接收实时行情")

def on_message(ws, message):
    """消息回调：序列校验、缓存、过滤无效报文"""
    global last_seq, msg_buffer
    if not message or len(message.strip()) == 0:
        return
    try:
        msg = json.loads(message)
    except Exception:
        return
    if "seq" not in msg or "code" not in msg:
        return
    tick_seq = msg["seq"]
    tick_code = msg["code"]
    # 过滤空行情无效数据
    if msg.get("price") in (0, None) and msg.get("open") in (0, None):
        return
    check_seq_continuity(tick_seq)
    msg_buffer.append(msg)
    last_seq = tick_seq

def on_error(ws, error):
    print(f"WebSocket链路异常：{error}")

def on_close(ws, close_code, close_msg):
    global last_seq, msg_buffer, subscriptions
    print(f"连接断开，关闭码：{close_code}，信息：{close_msg}")
    # 断开重置所有本地状态，重连后重新订阅
    last_seq = None
    msg_buffer.clear()
    subscriptions.clear()

def ws_runner():
    global ws_app
    ws_app = websocket.WebSocketApp(
        WS_STOCK_URL,
        on_open=on_open,
        on_message=on_message,
        on_error=on_error,
        on_close=on_close
    )
    # 10秒心跳保活，防止Socket假活断流
    ws_app.run_forever(ping_interval=10, ping_timeout=5)

if __name__ == "__main__":
    # 异步启动长连接
    ws_thread = threading.Thread(target=ws_runner, daemon=True)
    ws_thread.start()
    time.sleep(2)
    # 模拟新增自选标的
    send_subscribe_action("add", ["01299.HK"])
    time.sleep(10)
    # 模拟取消订阅标的
    send_subscribe_action("del", ["01299.HK"])
    while True:
        time.sleep(1)

七、实训踩坑记录

1. 现象：高频Tick推送，消息缓冲区持续堆积
   排查方式：监控队列长度、消费线程CPU占用；
   解决办法：单独开启异步消费线程批量读取缓冲，设置队列上限，超限拉取行情快照对齐数据。
2. 现象：网络假活，心跳无响应但连接不关闭，序列号持续断档
   排查方式：连续多次心跳无应答、多条报文序列号不连续；
   解决办法：增加序列号超时检测，连续5次断档主动重连，重连后拉取最新快照同步数据。
3. 现象：快速增减标的，订阅指令并发，本地与服务端订阅不一致
   排查方式：已取消标的仍持续推送行情；
   解决办法：订阅指令加线程锁串行执行，下发指令后延时校验推送标的，异常同步修正本地集合。
4. 现象：标的编码缺失.HK后缀，订阅静默失效无报错
   排查方式：下发指令后长期无对应标的Tick；
   解决办法：本地维护港股编码规范校验，非法编码直接拦截不发送。

八、边界说明

本套动态订阅方案支持：单条WebSocket长连接内，通过指定指令ID增删港股标的，无需重建链路，稳定接收实时行情；
不支持：多连接之间同步订阅状态、一次性完整回溯全量历史Tick、非指定指令ID的私有行情交互。

九、实训小结

本次实训依托AllTick API的WebSocket动态订阅能力，搭建了序列号校验+自动补缺完整流程，解决港股实时行情序列号跳变问题。文中附带可直接运行的Python代码与实操踩坑方案，适合金融开发实训快速上手，开发时遵守接口边界约束就能保证数据流稳定。