2. 搭建可复现的行情流实验环境

上一节我们明确了行情流消费的基本模型：客户端通过 WebSocket 与服务端建立长连接，服务端持续推送增量行情，客户端负责解析、缓存与分发。要让这套模型真正跑起来，第一步不是写消费逻辑，而是把“可复现的实验环境”搭好。所谓可复现，指的是任何人拿到同一套项目骨架、依赖清单和连接参数，都能在本地或测试环境得到一致的连接行为与数据形态。本节围绕四个部分展开：本地 WebSocket 行情模拟服务、公共测试行情源接入、依赖管理与项目骨架、连接参数与鉴权配置。

一、两条数据来源：本地模拟与公共测试源

实验环境建议同时准备两条数据来源，各有分工。本地模拟服务用于可控实验：你可以精确决定推送频率、字段结构、断线时机和异常报文，便于验证重连、心跳、乱序处理等逻辑；公共测试行情源用于贴近真实：它的报文结构、订阅方式和鉴权流程更接近生产，能暴露本地模拟覆盖不到的兼容性问题。

本地模拟服务不必引入复杂框架，用 Node.js 的 ws 库几十行即可完成。核心是维护一个订阅表，按固定间隔向订阅者推送行情快照。下面是一个可直接运行的示例（示例参数为教学假设，非实测数据）：

// mock-server.js
const { WebSocketServer } = require('ws');
const wss = new WebSocketServer({ port: 8765 });

const symbols = ['BTC-USDT', 'ETH-USDT'];
const subs = new Map(); // ws -> Set<symbol>

wss.on('connection', (ws) => {
  subs.set(ws, new Set());
  ws.on('message', (raw) => {
    const msg = JSON.parse(raw.toString());
    if (msg.op === 'subscribe') {
      msg.args.forEach((s) => subs.get(ws).add(s));
      ws.send(JSON.stringify({ event: 'subscribed', args: msg.args }));
    }
  });
  ws.on('close', () => subs.delete(ws));
});

setInterval(() => {
  for (const [ws, set] of subs) {
    if (ws.readyState !== 1) continue;
    for (const s of set) {
      ws.send(JSON.stringify({
        type: 'ticker',
        symbol: s,
        price: (100 + Math.random() * 10).toFixed(2),
        ts: Date.now()
      }));
    }
  }
}, 200); // 每 200ms 推送一次

启动后监听 ws://127.0.0.1:8765，订阅协议采用 {"op":"subscribe","args":["BTC-USDT"]} 的简化形式。这个模拟服务刻意保留了“订阅—确认—推送”三段结构，与多数真实行情网关一致，后续切换到公共源时消费端代码改动很小。

公共测试行情源方面，可选择提供公开 WebSocket 接口的交易所测试环境或行情聚合服务。接入时重点关注三点：一是订阅报文格式（是否需要 op 字段、参数是数组还是对象）；二是心跳机制（是客户端定时发 ping，还是服务端下发心跳帧，超时阈值多少）；三是频率限制（单连接最大订阅数、每秒消息上限）。这些差异应记录在配置文件中，而不是散落在代码里。

二、依赖管理与项目骨架

项目骨架的目标是让“连接、订阅、解析、分发”四件事各归其位，避免所有逻辑堆在一个文件里。以 Node.js 为例，推荐如下目录结构：

market-stream/
├── package.json
├── .env.example
├── config/
│   └── default.json      # endpoint、订阅列表、心跳参数
├── src/
│   ├── index.js          # 入口：加载配置、启动连接
│   ├── connection.js     # 建连、重连、心跳
│   ├── protocol.js       # 订阅报文与解析适配
│   └── store.js          # 行情缓存与订阅分发
└── mock/
    └── mock-server.js    # 本地模拟服务

依赖保持精简：ws 负责 WebSocket 客户端与服务端，dotenv 读取环境变量，pino 或内置 console 做结构化日志即可。不建议在实验阶段引入重量级框架，否则排查连接问题时会被抽象层干扰。依赖版本应锁定在 package.json 中，并提交 package-lock.json，这是“可复现”的关键一环——不同人安装出不同小版本，往往就是连接行为不一致的根源。

配置与代码分离同样重要。把 endpoint、订阅标的、心跳间隔、重连退避上限写入 config/default.json，密钥类信息只放环境变量，.env.example 提供字段模板但不含真实值。这样本地模拟与公共源之间切换，只需改配置，不动代码。

三、连接参数与鉴权配置

连接参数直接决定连接能否稳定存活，建议显式设置以下几项：

• 心跳间隔：示例取 15 秒发送一次 ping，30 秒未收到任何帧判定超时。真实源若由服务端下发心跳，则改为监听心跳帧并刷新计时器。
• 重连退避：首次 1 秒，之后按 2 倍递增，上限 30 秒，并加入 ±20% 随机抖动，避免多客户端同时重连造成雪崩。
• 订阅上限：单连接订阅数不超过服务端限制，超出时拆分连接或分批订阅。
• 消息大小与解析超时：对超大报文设置上限，解析失败计入异常计数而非直接崩溃。

鉴权方面，公共测试源常见两种方式：一是在连接 URL 上携带 ?token=xxx；二是在建连后发送登录报文，例如 {"op":"login","args":[{"apiKey":"...","timestamp":...,"sign":"..."}]}，其中 sign 通常由密钥、时间戳和请求参数按约定算法计算。无论哪种，密钥都必须从环境变量读取，禁止硬编码进仓库。下面是一个读取配置并建连的片段：

// src/connection.js（节选）
const WebSocket = require('ws');
const cfg = require('../config/default.json');

function connect(onMessage) {
  const ws = new WebSocket(cfg.endpoint, {
    headers: cfg.apiKey ? { 'X-API-KEY': process.env.MARKET_API_KEY } : {}
  });
  let heartbeat = null;

  ws.on('open', () => {
    ws.send(JSON.stringify({ op: 'subscribe', args: cfg.symbols }));
    heartbeat = setInterval(() => ws.ping(), cfg.heartbeatMs);
  });
  ws.on('message', (data) => onMessage(JSON.parse(data.toString())));
  ws.on('close', () => {
    clearInterval(heartbeat);
    setTimeout(() => connect(onMessage), cfg.reconnectBaseMs);
  });
  return ws;
}

四、如何判断环境搭好了

环境是否可复现，不看代码写得多漂亮，而看几个可观察的信号：启动模拟服务后，消费端日志能在 1 秒内出现 subscribed 确认；随后按设定频率持续收到 ticker 报文，字段完整、时间戳递增；手动杀掉模拟服务进程，消费端在退避时间内发起重连，重启服务后自动恢复订阅且不重复累积订阅；切换到公共测试源时，仅修改配置即可连通，鉴权失败时能明确打印错误码而非静默重试。把这四个信号写成一份简短的验收清单，每次改动骨架或依赖后跑一遍，实验环境才算真正“可复现”。