robot_webFenli/robots/majiang/robot_mj_cs/AUTO_RECONNECT_DOC.md

# Robot MJ CS 自动重连功能说明（连接监视器版）

## 功能概述

为robot_mj_cs客户端实现了**基于连接监视器的自动重连机制**，通过为每个TCP连接启动独立的定时监视器，当检测到与game_mj_cs服务端的连接断开时，会**立即**自动尝试重新连接，无需发送心跳包来维持连接。

## 核心特性

### 1. 自动重连机制
- **连接监视器模式**：为每个连接创建独立的8秒间隔定时监视器
- **双重检测机制**：结合连接状态检查和活动时间超时检测
- **智能重连策略**：精确区分主动断开和被动断开
- **快速响应重连**：失败后1秒延迟快速重连，最小化断连时间
- **重试次数控制**：最大10次重连尝试，防止资源耗尽

### 2. 连接状态管理
- **活跃连接跟踪**：实时维护连接状态
- **重连次数统计**：记录每个连接的重连尝试次数
- **主动断开识别**：用户主动断开时不触发重连

### 3. 监控与日志
- **独立监视器**：每个TCP连接拥有专属的定时状态检测线程
- **实时活动追踪**：精确记录每次网络交互的活动时间戳
- **智能超时验证**：20秒无通信时主动发送验证消息确认连接状态
- **全程日志监控**：详细记录监视器生命周期、连接状态变迁等关键事件
- **健壮异常处理**：全面的异常捕获和优雅降级处理机制

## 技术实现

### 核心组件

#### RobotConnectionManager (连接管理器)
```java
// 核心组件
private final ScheduledExecutorService reconnectScheduler;     // 统一调度器
private final Map<String, Boolean> activeConnections;          // 连接活跃状态
private final Map<String, Integer> reconnectAttempts;          // 重连尝试计数
private final Map<String, Long> lastActivityTime;             // 最后活动时间戳
private final Map<String, ScheduledFuture<?>> connectionWatchers; // 连接监视器映射

// 配置参数
private final int MAX_RECONNECT_ATTEMPTS = 10;                // 最大重连次数
private final int RECONNECT_DELAY_SECONDS = 1;                // 重连延迟（秒）
private final int CONNECTION_WATCH_INTERVAL = 8;              // 监视间隔（秒）
private final int CONNECTION_TIMEOUT_SECONDS = 20;            // 超时阈值（秒）
```

#### 关键方法

1. **connectToGameServer()** - 建立新连接
   - 创建TaurusClient实例
   - 设置事件监听器
   - 标记为活跃连接

2. **handleConnectionFailure()** - 处理连接失败
   - 区分主动/被动断开
   - 触发重连流程

3. **startConnectionWatcher()** - 启动连接监视器
   - 为指定连接创建专属的定时检测任务
   - 8秒固定间隔持续监控连接健康状态
   - 自动管理监视器的生命周期

4. **monitorConnection()** - 执行连接状态检测
   - 实时检查底层TCP连接是否存活
   - 基于最后活动时间判断连接活性
   - 超时时主动发送验证消息确认状态

5. **scheduleReconnect()** - 安排重连任务
   - 智能判断是否需要重连（排除主动断开）
   - 控制重连尝试次数防止无限循环
   - 1秒快速延迟确保及时响应

4. **reconnectToGameServer()** - 执行重连
   - 清理旧连接
   - 建立新连接
   - 复用事件监听器

### 重连流程

```mermaid
graph TD
    A[连接建立成功] --> B[启动专属监视器]
    B --> C[8秒周期性状态检测]
    C --> D{TCP连接存活?}
    D -->|否| E[立即触发重连流程]
    D -->|是| F[检查通信活性]
    F --> G{超过20秒无通信?}
    G -->|是| H[发送PING验证]
    G -->|否| C
    H --> I{验证响应正常?}
    I -->|否| E
    I -->|是| J[刷新活动时间]
    J --> C
    E --> K{用户主动断开?}
    K -->|是| L[清理监视器资源]
    K -->|否| M[检查重试次数]
    M --> N{重试次数<10?}
    N -->|否| O[终止重连尝试]
    N -->|是| P[1秒后执行重连]
    P --> Q[重建TCP连接]
    Q --> R{连接重建成功?}
    R -->|是| S[重启监视器]
    R -->|否| M
    
    T[用户主动断开] --> U[停止监视器]
    U --> L
```

## 配置参数

### 可调整参数

```java
private final int MAX_RECONNECT_ATTEMPTS = 10;      // 最大重连尝试次数
private final int RECONNECT_DELAY_SECONDS = 5;      // 重连间隔秒数
private final int CONNECTION_MONITOR_INTERVAL = 30; // 连接监控间隔秒数
```

### 参数调优建议

- **MAX_RECONNECT_ATTEMPTS**: 根据网络稳定性调整
  - 网络稳定环境：5-10次
  - 网络不稳定环境：15-20次

- **RECONNECT_DELAY_SECONDS**: 重连响应速度
  - 默认：1秒（快速响应）
  - 可根据需要调整至0-3秒

- **CONNECTION_WATCH_INTERVAL**: 监视器检测频率
  - 默认：8秒（平衡性能与响应速度）
  - 高频场景：可调至5秒
  - 低频场景：可调至10-15秒

- **CONNECTION_TIMEOUT_SECONDS**: 连接活性超时阈值
  - 默认：20秒（适应大多数网络环境）
  - 敏感业务：可调至15秒
  - 宽松环境：可调至25-30秒

- **CONNECTION_MONITOR_INTERVAL**: 根据实时性要求调整
  - 高实时性：15-30秒
  - 一般应用：30-60秒

## 使用示例

### 基本使用

```java
// 创建连接管理器
RobotConnectionManager connectionManager = new RobotConnectionManager();

// 连接到游戏服务器
TaurusClient client = connectionManager.connectToGameServer("robot_123_room_456");

// 正常使用连接...
client.send("protocol", params, callback);

// 主动断开连接（不会触发重连）
connectionManager.disconnectFromGameServer("robot_123_room_456");

// 关闭连接管理器
connectionManager.shutdown();
```

### 在EXGameController中的集成

```java
// 获取或创建连接
public static TaurusClient getCsMjGameServerConnection(String connecId) {
    TaurusClient taurusClient = connectionManager.getGameClient(connecId);
    if (taurusClient != null) {
        return taurusClient;
    }
    // 自动创建新连接
    return connectionManager.connectToGameServer(connecId);
}
```

## 日志输出示例

```
INFO  连接成功: robot_123_room_456
WARN  连接断开: robot_123_room_456, 原因: TimeoutDisconnect
INFO  安排重连任务: robot_123_room_456, 第1次尝试
INFO  开始重连: robot_123_room_456
INFO  重连成功: robot_123_room_456
```

## 注意事项

### 1. 资源管理
- 确保在应用关闭时调用`shutdown()`方法
- 避免连接泄露和线程泄露

### 2. 性能考虑
- 重连调度器使用固定线程池
- 避免同时大量重连造成系统压力

### 3. 异常处理
- 网络异常会被捕获并记录
- 重连失败会继续尝试直到达到最大次数

### 4. 与现有代码兼容性
- 保持原有API不变
- 无缝集成到现有业务逻辑中

## 故障排除

### 常见问题

1. **重连过于频繁**
   - 调整`RECONNECT_DELAY_SECONDS`参数
   - 检查网络连接质量

2. **达到最大重连次数后不再重连**
   - 检查服务端是否正常运行
   - 考虑增加`MAX_RECONNECT_ATTEMPTS`

3. **内存泄漏**
   - 确保正确调用`shutdown()`方法
   - 检查是否有未清理的连接引用

### 监控指标

建议监控以下指标：
- 当前活跃连接数
- 重连尝试次数分布
- 连接成功率
- 平均重连耗时

## 版本历史

- **v1.0.0** (2026-02-03)
  - 实现基础自动重连功能
  - 支持连接状态监控
  - 提供详细的日志记录