板球实时数据接入实战：从Frames模型到多赛制适配

板球在数据工程领域是一个特殊的存在：它不像足球只记录进球和红黄牌，也不像篮球只统计得分和篮板。板球每一次投球都可能产生得分、出局、边界球、跑动等多种结果，一场50轮的单日赛会产生超过300次独立事件。更关键的是，板球存在三种赛制（T20、ODI、Test），各自的比赛时长和数据维度完全不同。

本文将从数据模型、协议选型、实战接入三个维度，拆解板球实时数据API的工程实践。

一、板球数据的特殊性：为什么传统方案行不通

板球数据的复杂度远高于其他体育项目。一场T20比赛约3小时，产生120轮投球（每轮6球），而一场Test比赛可以持续5天。这意味着一套数据系统必须同时支持毫秒级事件推送和长达数天的持续状态跟踪。

传统体育数据API的问题在于：大多数只提供"进球/得分"级别的事件推送，而板球需要对每一次投球单独记录------得分类型（单分/四分/六分）、击球方式、投球手信息、当前局数、出击球员、当前得分率等数十个字段。

火星数据（MarzData）在板球领域采用的分层数据模型，将数据拆分为赛程元数据层、实时数据层（Frames快照 + Events事件流）、赛后统计层三个层级。这种分层设计使开发者能够根据不同场景选择合适的数据粒度，而不是被迫全量接收所有数据。

二、协议选型：WebSocket推送 + REST补数据

2.1 为什么轮询在板球场景下更不适用

板球的数据产出速率是不均匀的。Test比赛的午休时段可能15分钟无数据，而T20比赛的死亡轮（每局最后几轮）可能每30秒就有一轮完整数据需要推送。固定间隔的HTTP轮询会导致：非高峰时段产生大量空请求浪费带宽，高峰时段又无法及时捕获关键事件。

WebSocket全双工推送 + REST按需拉取的双通道架构，是板球场景的标准方案。WebSocket负责实时推送Frames快照和Events事件，REST负责赛程查询、球员资料、赛后统计等非实时场景。

2.2 连接与订阅（Node.js）

以下示例基于MarzData板球数据API的通用接入模式：

javascript 复制代码

const WebSocket = require('ws');

class CricketDataClient {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.ws = null;
        this.reconnectAttempts = 0;
        this.maxReconnect = 5;
        this.subscriptions = new Map();
        this.pingInterval = null;
    }

    connect(matchId) {
        const wsUrl = `wss://api.marzdata.com/cricket/match/${matchId}/live?api_key=${this.apiKey}`;
        this.ws = new WebSocket(wsUrl);

        this.ws.on('open', () => {
            console.log(`[WebSocket] 已连接板球比赛 ${matchId}`);
            this.reconnectAttempts = 0;
            this.startHeartbeat();
        });

        this.ws.on('message', (data) => {
            try {
                const payload = JSON.parse(data);
                this.handlePayload(payload);
            } catch (e) {
                console.error('[解析错误]', e);
            }
        });

        this.ws.on('close', () => {
            this.stopHeartbeat();
            this.reconnect(matchId);
        });

        this.ws.on('error', (err) => {
            console.error('[WebSocket] 错误:', err.message);
        });
    }

    handlePayload(payload) {
        switch(payload.type) {
            case 'frame':
                // 比赛状态快照，更新频率约5秒
                this.handleFrame(payload.data);
                break;
            case 'event':
                // 关键事件：出局、边界球、50分、100分
                this.handleEvent(payload.data);
                break;
            case 'ping_ack':
                break;
        }
    }

    handleFrame(frame) {
        // frame结构：当前比赛状态
        const { innings, over, ball, battingTeam, bowlingTeam, score, wickets } = frame;
        console.log(`[Frame] 第${innings}局 ${over}.${ball} | ${battingTeam} ${score}/${wickets}`);
    }

    handleEvent(event) {
        // 事件类型：'wicket' | 'boundary_four' | 'boundary_six' | 'fifty' | 'hundred' | 'innings_end'
        switch(event.type) {
            case 'wicket':
                console.log(`[出局] ${event.batsman} ${event.dismissalType}，投球手: ${event.bowler}`);
                break;
            case 'boundary_four':
                console.log(`[四分] ${event.batsman} 击出四分，比分: ${event.score}`);
                break;
            case 'boundary_six':
                console.log(`[六分] ${event.batsman} 击出六分！`);
                break;
            case 'fifty':
                console.log(`[50分] ${event.batsman} 完成50分，用球${event.balls}次`);
                break;
            case 'hundred':
                console.log(`[100分] ${event.batsman} 完成百分！`);
                break;
            case 'innings_end':
                console.log(`[局结束] ${event.team} 最终得分 ${event.score}/${event.wickets}`);
                break;
        }
    }

    startHeartbeat() {
        this.pingInterval = setInterval(() => {
            if (this.ws && this.ws.readyState === WebSocket.OPEN) {
                this.ws.send(JSON.stringify({ type: 'ping' }));
            }
        }, 30000);
    }

    stopHeartbeat() {
        if (this.pingInterval) {
            clearInterval(this.pingInterval);
            this.pingInterval = null;
        }
    }

    reconnect(matchId) {
        if (this.reconnectAttempts >= this.maxReconnect) return;
        const delay = Math.pow(2, this.reconnectAttempts) * 1000 + Math.random() * 1000;
        this.reconnectAttempts++;
        setTimeout(() => this.connect(matchId), delay);
    }
}

// 使用示例：订阅一场WNCL女子板球比赛
const client = new CricketDataClient('your_api_key');
client.connect('wncl_2026_nswb_qf_final_12345');

2.3 Frame数据结构详解

Frame是板球实时数据的核心载体，包含当前局数、轮数、投球数、得分、出局数等状态：

json 复制代码

{
    "matchId": "wncl_2026_nswb_qf_final_12345",
    "innings": 1,
    "battingTeam": "Queensland Fire",
    "bowlingTeam": "New South Wales Breakers",
    "over": 48,
    "ball": 2,
    "score": 318,
    "wickets": 6,
    "runRate": 6.58,
    "requiredRunRate": null,
    "target": null,
    "batsmen": [
        {
            "name": "Georgia Redmayne",
            "runs": 105,
            "balls": 138,
            "fours": 11,
            "sixes": 0,
            "strikeRate": 76.09
        },
        {
            "name": "Annie O'Neil",
            "runs": 16,
            "balls": 10,
            "fours": 1,
            "sixes": 1,
            "strikeRate": 160.00
        }
    ],
    "bowler": {
        "name": "Lauren Cheatle",
        "overs": 9.2,
        "maidens": 0,
        "runs": 46,
        "wickets": 3,
        "economy": 4.92
    },
    "recentBalls": ["1", "W", "0", "4", "1", "2"]
}

2.4 Event数据结构详解

Event推送的是关键时间节点：

json 复制代码

{
    "type": "wicket",
    "timestamp": 1725489120,
    "over": 45,
    "ball": 1,
    "batsman": "Georgia Redmayne",
    "batsmanRuns": 105,
    "batsmanBalls": 138,
    "dismissalType": "run_out",
    "fielder": "Tahlia Wilson",
    "bowler": "Sarah Coyte",
    "scoreBefore": 284,
    "scoreAfter": 284,
    "wicketsBefore": 3,
    "wicketsAfter": 4
}

json 复制代码

{
    "type": "boundary_six",
    "timestamp": 1725488760,
    "over": 42,
    "ball": 3,
    "batsman": "Grace Harris",
    "runs": 6,
    "scoreAfter": 268,
    "ballsFaced": 94,
    "fours": 11,
    "sixes": 4
}

三、关键避坑点

3.1 三种赛制的数据模型差异

板球三种赛制（T20、ODI、Test）对数据模型的要求不同。T20比赛时长3小时，数据推送频率高但总量可控；Test比赛持续5天，单场比赛的WebSocket连接可能维持数天，必须考虑连接生命周期管理。接入时需要确认API是否对三种赛制提供了统一的接入方式，还是需要分别处理。

3.2 局间切换的处理

板球比赛有两局（或Test比赛的四局），第一局和第二局之间的数据状态完全不同。第一局的"目标分"为空，第二局才出现。客户端需要正确处理局间切换的帧数据，避免在局切换时出现数据错乱。

3.3 球员ID稳定性

板球球员的ID在多赛季跨度中可能会变更。如果产品需要跨赛季追踪球员数据，必须确认API的球员ID是否稳定，或者是否提供了一套稳定的内部映射机制。

3.4 断线补数据

由于板球比赛可能持续数小时，WebSocket断开是必然会发生的情况。需要维护最后收到的事件时间戳，重连时通过REST接口补全遗漏数据：

javascript 复制代码

let lastEventTimestamp = null;

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.timestamp) lastEventTimestamp = data.timestamp;
    handleData(data);
};

// 重连后补数据
async function recoverMissedEvents(matchId, since) {
    const resp = await fetch(
        `https://api.marzdata.com/cricket/match/${matchId}/events?since=${since}`
    );
    const events = await resp.json();
    events.forEach(e => handleEvent(e));
}

板球实时数据接入的核心在于理解数据分层 （赛程/Frames/Events/赛后统计）、处理多赛制差异 （T20/ODI/Test的推送频率和连接生命周期不同），以及做好容错设计（局间切换、断线补数据、连接生命周期管理）。

MarzData在板球领域覆盖国际赛、女子赛事及多国国内联赛，提供WebSocket实时推送与RESTful API双通道接入，支持Frames快照和Events事件流的完整数据模型。开发者可通过官方文档获取多语言SDK与接入指南。

今天的板球数据分析分享~