传输层实现（客户端/服务端，链接管理和心跳机制，重连机制）

消息序列化（json序列化，消息压缩，消息ID和时间戳）网络服务器核心（networkserver/基础room/链接状态同步）网络客户端核心（networkclient/消息队列）
2025-08-14 23:59:00 +08:00
parent 32092f992d
commit 6730a5d625
29 changed files with 8100 additions and 236 deletions
--- a/packages/network-shared/src/transport/HeartbeatManager.ts
+++ b/packages/network-shared/src/transport/HeartbeatManager.ts
@@ -0,0 +1,381 @@
+/**
+ * 心跳管理器
+ * 负责管理网络连接的心跳检测，包括延迟测算和连接健康检测
+ */
+import { createLogger } from '@esengine/ecs-framework';
+import { MessageType } from '../types/NetworkTypes';
+
+/**
+ * 心跳配置
+ */
+export interface HeartbeatConfig {
+    interval: number;          // 心跳间隔（毫秒）
+    timeout: number;           // 心跳超时（毫秒）
+    maxMissedHeartbeats: number; // 最大丢失心跳数
+    enableLatencyMeasurement: boolean; // 是否启用延迟测量
+}
+
+/**
+ * 心跳状态
+ */
+export interface HeartbeatStatus {
+    isHealthy: boolean;
+    lastHeartbeat: number;
+    latency?: number;
+    missedHeartbeats: number;
+    averageLatency?: number;
+    packetLoss?: number;
+}
+
+/**
+ * 心跳事件接口
+ */
+export interface HeartbeatEvents {
+    heartbeatSent: (timestamp: number) => void;
+    heartbeatReceived: (latency: number) => void;
+    heartbeatTimeout: (missedCount: number) => void;
+    healthStatusChanged: (isHealthy: boolean) => void;
+}
+
+/**
+ * 心跳消息接口
+ */
+export interface HeartbeatMessage {
+    type: MessageType.HEARTBEAT;
+    clientTime: number;
+    serverTime?: number;
+    sequence?: number;
+}
+
+/**
+ * 心跳管理器
+ */
+export class HeartbeatManager {
+    private logger = createLogger('HeartbeatManager');
+    private config: HeartbeatConfig;
+    private status: HeartbeatStatus;
+    private eventHandlers: Partial<HeartbeatEvents> = {};
+    
+    // 定时器
+    private heartbeatTimer?: number;
+    private timeoutTimer?: number;
+    
+    // 延迟测量
+    private pendingPings: Map<number, number> = new Map();
+    private latencyHistory: number[] = [];
+    private sequence = 0;
+    
+    // 统计信息
+    private sentCount = 0;
+    private receivedCount = 0;
+
+    /**
+     * 发送心跳回调
+     */
+    private sendHeartbeat?: (message: HeartbeatMessage) => void;
+
+    /**
+     * 构造函数
+     */
+    constructor(config: Partial<HeartbeatConfig> = {}) {
+        this.config = {
+            interval: 30000,           // 30秒
+            timeout: 60000,            // 60秒
+            maxMissedHeartbeats: 3,    // 最大丢失3次
+            enableLatencyMeasurement: true,
+            ...config
+        };
+
+        this.status = {
+            isHealthy: true,
+            lastHeartbeat: Date.now(),
+            missedHeartbeats: 0
+        };
+    }
+
+    /**
+     * 启动心跳
+     */
+    start(sendCallback: (message: HeartbeatMessage) => void): void {
+        this.sendHeartbeat = sendCallback;
+        this.startHeartbeatTimer();
+        this.logger.info('心跳管理器已启动');
+    }
+
+    /**
+     * 停止心跳
+     */
+    stop(): void {
+        this.stopHeartbeatTimer();
+        this.stopTimeoutTimer();
+        this.pendingPings.clear();
+        this.logger.info('心跳管理器已停止');
+    }
+
+    /**
+     * 处理接收到的心跳响应
+     */
+    handleHeartbeatResponse(message: HeartbeatMessage): void {
+        const now = Date.now();
+        this.status.lastHeartbeat = now;
+        this.receivedCount++;
+        
+        // 重置丢失心跳计数
+        this.status.missedHeartbeats = 0;
+        
+        // 计算延迟
+        if (this.config.enableLatencyMeasurement && message.sequence !== undefined) {
+            const sentTime = this.pendingPings.get(message.sequence);
+            if (sentTime) {
+                const latency = now - sentTime;
+                this.updateLatency(latency);
+                this.pendingPings.delete(message.sequence);
+                
+                this.eventHandlers.heartbeatReceived?.(latency);
+            }
+        }
+        
+        // 更新健康状态
+        this.updateHealthStatus(true);
+        
+        // 停止超时定时器
+        this.stopTimeoutTimer();
+    }
+
+    /**
+     * 处理心跳超时
+     */
+    handleHeartbeatTimeout(): void {
+        this.status.missedHeartbeats++;
+        this.logger.warn(`心跳超时，丢失次数: ${this.status.missedHeartbeats}`);
+        
+        // 触发超时事件
+        this.eventHandlers.heartbeatTimeout?.(this.status.missedHeartbeats);
+        
+        // 检查是否达到最大丢失次数
+        if (this.status.missedHeartbeats >= this.config.maxMissedHeartbeats) {
+            this.updateHealthStatus(false);
+        }
+    }
+
+    /**
+     * 获取心跳状态
+     */
+    getStatus(): HeartbeatStatus {
+        return { ...this.status };
+    }
+
+    /**
+     * 获取统计信息
+     */
+    getStats() {
+        const packetLoss = this.sentCount > 0 ? 
+            ((this.sentCount - this.receivedCount) / this.sentCount) * 100 : 0;
+            
+        return {
+            sentCount: this.sentCount,
+            receivedCount: this.receivedCount,
+            packetLoss,
+            averageLatency: this.status.averageLatency,
+            currentLatency: this.status.latency,
+            isHealthy: this.status.isHealthy,
+            missedHeartbeats: this.status.missedHeartbeats,
+            latencyHistory: [...this.latencyHistory]
+        };
+    }
+
+    /**
+     * 设置事件处理器
+     */
+    on<K extends keyof HeartbeatEvents>(event: K, handler: HeartbeatEvents[K]): void {
+        this.eventHandlers[event] = handler;
+    }
+
+    /**
+     * 移除事件处理器
+     */
+    off<K extends keyof HeartbeatEvents>(event: K): void {
+        delete this.eventHandlers[event];
+    }
+
+    /**
+     * 手动发送心跳
+     */
+    sendHeartbeatNow(): void {
+        this.doSendHeartbeat();
+    }
+
+    /**
+     * 更新配置
+     */
+    updateConfig(newConfig: Partial<HeartbeatConfig>): void {
+        Object.assign(this.config, newConfig);
+        this.logger.info('心跳配置已更新:', newConfig);
+        
+        // 重启定时器以应用新配置
+        if (this.heartbeatTimer) {
+            this.stop();
+            if (this.sendHeartbeat) {
+                this.start(this.sendHeartbeat);
+            }
+        }
+    }
+
+    /**
+     * 启动心跳定时器
+     */
+    private startHeartbeatTimer(): void {
+        this.heartbeatTimer = window.setInterval(() => {
+            this.doSendHeartbeat();
+        }, this.config.interval);
+    }
+
+    /**
+     * 停止心跳定时器
+     */
+    private stopHeartbeatTimer(): void {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+    }
+
+    /**
+     * 启动超时定时器
+     */
+    private startTimeoutTimer(): void {
+        this.timeoutTimer = window.setTimeout(() => {
+            this.handleHeartbeatTimeout();
+        }, this.config.timeout);
+    }
+
+    /**
+     * 停止超时定时器
+     */
+    private stopTimeoutTimer(): void {
+        if (this.timeoutTimer) {
+            clearTimeout(this.timeoutTimer);
+            this.timeoutTimer = undefined;
+        }
+    }
+
+    /**
+     * 执行发送心跳
+     */
+    private doSendHeartbeat(): void {
+        if (!this.sendHeartbeat) {
+            this.logger.error('心跳发送回调未设置');
+            return;
+        }
+
+        const now = Date.now();
+        const sequence = this.config.enableLatencyMeasurement ? ++this.sequence : undefined;
+        
+        const message: HeartbeatMessage = {
+            type: MessageType.HEARTBEAT,
+            clientTime: now,
+            sequence
+        };
+
+        try {
+            this.sendHeartbeat(message);
+            this.sentCount++;
+            
+            // 记录发送时间用于延迟计算
+            if (sequence !== undefined) {
+                this.pendingPings.set(sequence, now);
+                
+                // 清理过期的pending pings
+                this.cleanupPendingPings();
+            }
+            
+            // 启动超时定时器
+            this.stopTimeoutTimer();
+            this.startTimeoutTimer();
+            
+            this.eventHandlers.heartbeatSent?.(now);
+            
+        } catch (error) {
+            this.logger.error('发送心跳失败:', error);
+        }
+    }
+
+    /**
+     * 更新延迟信息
+     */
+    private updateLatency(latency: number): void {
+        this.status.latency = latency;
+        
+        // 保存延迟历史（最多100个样本）
+        this.latencyHistory.push(latency);
+        if (this.latencyHistory.length > 100) {
+            this.latencyHistory.shift();
+        }
+        
+        // 计算平均延迟
+        this.status.averageLatency = this.latencyHistory.reduce((sum, lat) => sum + lat, 0) / this.latencyHistory.length;
+        
+        this.logger.debug(`延迟更新: ${latency}ms, 平均: ${this.status.averageLatency?.toFixed(1)}ms`);
+    }
+
+    /**
+     * 更新健康状态
+     */
+    private updateHealthStatus(isHealthy: boolean): void {
+        if (this.status.isHealthy !== isHealthy) {
+            this.status.isHealthy = isHealthy;
+            this.logger.info(`连接健康状态变更: ${isHealthy ? '健康' : '不健康'}`);
+            this.eventHandlers.healthStatusChanged?.(isHealthy);
+        }
+    }
+
+    /**
+     * 清理过期的pending pings
+     */
+    private cleanupPendingPings(): void {
+        const now = Date.now();
+        const timeout = this.config.timeout * 2; // 清理超过2倍超时时间的记录
+        
+        for (const [sequence, sentTime] of this.pendingPings) {
+            if (now - sentTime > timeout) {
+                this.pendingPings.delete(sequence);
+            }
+        }
+    }
+
+    /**
+     * 重置统计信息
+     */
+    resetStats(): void {
+        this.sentCount = 0;
+        this.receivedCount = 0;
+        this.latencyHistory.length = 0;
+        this.status.averageLatency = undefined;
+        this.status.latency = undefined;
+        this.status.missedHeartbeats = 0;
+        this.pendingPings.clear();
+        this.logger.info('心跳统计信息已重置');
+    }
+
+    /**
+     * 检查连接是否健康
+     */
+    isConnectionHealthy(): boolean {
+        const now = Date.now();
+        const timeSinceLastHeartbeat = now - this.status.lastHeartbeat;
+        
+        return this.status.isHealthy && 
+               timeSinceLastHeartbeat <= this.config.timeout &&
+               this.status.missedHeartbeats < this.config.maxMissedHeartbeats;
+    }
+
+    /**
+     * 获取建议的重连延迟
+     */
+    getReconnectDelay(): number {
+        // 基于丢失心跳次数计算重连延迟
+        const baseDelay = this.config.interval;
+        const multiplier = Math.min(Math.pow(2, this.status.missedHeartbeats), 8);
+        return baseDelay * multiplier;
+    }
+}