docs(gateApi): 更新代码注释和文档说明

Administrator

yesterday 31cc693c228f2f2feb23bbda6da43f0f8db5fbe4

 src/main/java/com/xcong/excoin/modules/gateApi/GateKlineWebSocketClient.java

@@ -1,90 +1,110 @@
package com.xcong.excoin.modules.gateApi;

import cn.hutool.core.collection.CollUtil;
import cn.hutool.json.JSONException;
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONArray;
import com.alibaba.fastjson.JSONObject;
import com.xcong.excoin.modules.blackchain.service.DateUtil;
import com.xcong.excoin.modules.okxNewPrice.celue.CaoZuoService;
import com.xcong.excoin.modules.okxNewPrice.indicator.macdAndMatrategy.MacdEmaStrategy;
import com.xcong.excoin.modules.okxNewPrice.indicator.macdAndMatrategy.MacdMaStrategy;
import com.xcong.excoin.modules.okxNewPrice.okxWs.InstrumentsWs;
import com.xcong.excoin.modules.okxNewPrice.okxWs.TradeOrderWs;
import com.xcong.excoin.modules.okxNewPrice.okxWs.enums.CoinEnums;
import com.xcong.excoin.modules.okxNewPrice.okxWs.param.Kline;
import com.xcong.excoin.modules.okxNewPrice.okxWs.param.TradeRequestParam;
import com.xcong.excoin.modules.okxNewPrice.okxWs.wanggeList.WangGeListService;
import com.xcong.excoin.modules.okxNewPrice.okxpi.config.ExchangeInfoEnum;
import com.xcong.excoin.modules.okxNewPrice.okxpi.config.ExchangeLoginService;
import com.xcong.excoin.modules.gateApi.wsHandler.GateChannelHandler;
import com.xcong.excoin.modules.okxNewPrice.utils.SSLConfig;
import com.xcong.excoin.modules.okxNewPrice.utils.WsParamBuild;
import lombok.extern.slf4j.Slf4j;
import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;

import java.math.BigDecimal;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.*;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicReference;
import java.util.stream.Collectors;

/**
 * Gate K线 WebSocket 客户端类，用于连接 Gate 的 WebSocket 接口，
 * 实时获取并处理 K线（candlestick）数据。
 * 同时支持心跳检测、自动重连以及异常恢复机制。
 * Gate WebSocket 连接管理器。
 *
 * <h3>职责</h3>
 * 负责 TCP 连接的建立、维持和恢复。频道逻辑（订阅/解析）全部委托给 {@link GateChannelHandler} 实现类。
 *
 * <h3>生命周期</h3>
 * <pre>
 *   init()        → connect() → startHeartbeat()
 *   destroy()     → unsubscribe 所有 handler → closeBlocking() → shutdown 线程池
 *   onClose()     → reconnectWithBackoff() (最多 3 次，指数退避)
 * </pre>
 *
 * <h3>消息路由</h3>
 * <pre>
 *   onMessage → handleMessage:
 *     1. futures.pong         → cancelPongTimeout
 *     2. subscribe/unsubscribe → 日志
 *     3. error                → 错误日志
 *     4. update/all           → 遍历 channelHandlers → handler.handleMessage(response)
 * </pre>
 *
 * <h3>心跳机制</h3>
 * 采用双重检测：TCP 层的 WebSocket ping/pong + 应用层 futures.ping/futures.pong。
 * 10 秒未收到任何消息 → 发送 futures.ping；25 秒周期检查。
 *
 * <h3>线程安全</h3>
 * 连接状态用 AtomicBoolean（isConnected, isConnecting, isInitialized）。
 * 消息时间戳用 AtomicReference。心跳任务用 synchronized 保护。
 *
 * @author Administrator
 */
@SuppressWarnings("ALL")
@Slf4j
public class GateKlineWebSocketClient {
    private final CaoZuoService caoZuoService;
    private final GateWebSocketClientManager clientManager;
    private final WangGeListService wangGeListService;

    private WebSocketClient webSocketClient;
    private ScheduledExecutorService heartbeatExecutor;
    private volatile ScheduledFuture<?> pongTimeoutFuture;
    private final AtomicReference<Long> lastMessageTime = new AtomicReference<>(System.currentTimeMillis());

    // 连接状态标志
    private final AtomicBoolean isConnected = new AtomicBoolean(false);
    private final AtomicBoolean isConnecting = new AtomicBoolean(false);
    private final AtomicBoolean isInitialized = new AtomicBoolean(false);

    private static final String CHANNEL = "futures.candlesticks";
    private static final String FUTURES_PING = "futures.ping";
    private static final String FUTURES_PONG = "futures.pong";
    private static final String GATE_INTERVAL = "1m";
    private static final String GATE_CONTRACT = "BTC_USDT";

    // 心跳超时时间(秒)，小于30秒
    private static final int HEARTBEAT_TIMEOUT = 10;

    // 共享线程池用于重连等异步任务
    /** WebSocket 地址，由 GateConfig 提供 */
    private final String wsUrl;

    /** Java-WebSocket 客户端实例 */
    private WebSocketClient webSocketClient;
    /** 心跳检测调度器 */
    private ScheduledExecutorService heartbeatExecutor;
    /** 心跳超时 Future */
    private volatile ScheduledFuture<?> pongTimeoutFuture;
    /** 最后收到消息的时间戳（毫秒） */
    private final AtomicReference<Long> lastMessageTime = new AtomicReference<>(System.currentTimeMillis());

    /** 连接状态 */
    private final AtomicBoolean isConnected = new AtomicBoolean(false);
    /** 连接中标记，防重入 */
    private final AtomicBoolean isConnecting = new AtomicBoolean(false);
    /** 初始化标记，防重复 init */
    private final AtomicBoolean isInitialized = new AtomicBoolean(false);

    /** 频道处理器列表，通过 addChannelHandler 注册 */
    private final List<GateChannelHandler> channelHandlers = new ArrayList<>();

    /** 重连等异步任务的缓存线程池（daemon 线程） */
    private final ExecutorService sharedExecutor = Executors.newCachedThreadPool(r -> {
        Thread t = new Thread(r, "gate-kline-worker");
        Thread t = new Thread(r, "gate-ws-worker");
        t.setDaemon(true);
        return t;
    });

    public GateKlineWebSocketClient(CaoZuoService caoZuoService,
                                    GateWebSocketClientManager clientManager,
                                    WangGeListService wangGeListService
    ) {
        this.caoZuoService = caoZuoService;
        this.clientManager = clientManager;
        this.wangGeListService = wangGeListService;
    public GateKlineWebSocketClient(String wsUrl) {
        this.wsUrl = wsUrl;
    }

    /**
     * 初始化方法，创建并初始化WebSocket客户端实例
     * 注册频道处理器。需在 init() 前调用。
     *
     * @param handler 实现了 {@link GateChannelHandler} 接口的频道处理器
     */
    public void addChannelHandler(GateChannelHandler handler) {
        channelHandlers.add(handler);
    }

    /**
     * 初始化：建立 WebSocket 连接 → 启动心跳检测。
     * 使用 {@code AtomicBoolean} 防重入，同一实例只允许初始化一次。
     */
    public void init() {
        if (!isInitialized.compareAndSet(false, true)) {
            log.warn("GateKlineWebSocketClient 已经初始化过，跳过重复初始化");
            log.warn("[WS] 已初始化过，跳过重复初始化");
            return;
        }
        connect();
@@ -92,23 +112,25 @@
    }

    /**
     * 销毁方法，关闭WebSocket连接和相关资源
     * 销毁：取消所有频道订阅 → 关闭 WebSocket 连接 → 关闭线程池。
     *
     * <h3>执行顺序</h3>
     * 先取消订阅（等待 500ms 确保发送完成），再 closeBlocking 关闭连接，
     * 最后 shutdown 线程池。先关连接再关线程池，避免 onClose 回调中的重连任务访问已关闭的线程池。
     */
    public void destroy() {
        log.info("开始销毁GateKlineWebSocketClient");
        log.info("[WS] 开始销毁...");

        if (webSocketClient != null && webSocketClient.isOpen()) {
            unsubscribeKlineChannels();
            for (GateChannelHandler handler : channelHandlers) {
                handler.unsubscribe(webSocketClient);
            }
            try {
                Thread.sleep(500);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                log.warn("取消订阅等待被中断");
                log.warn("[WS] 取消订阅等待被中断");
            }
        }

        if (sharedExecutor != null && !sharedExecutor.isShutdown()) {
            sharedExecutor.shutdown();
        }

        if (webSocketClient != null && webSocketClient.isOpen()) {
@@ -116,8 +138,12 @@
                webSocketClient.closeBlocking();
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                log.warn("关闭WebSocket连接时被中断");
                log.warn("[WS] 关闭连接时被中断");
            }
        }

        if (sharedExecutor != null && !sharedExecutor.isShutdown()) {
            sharedExecutor.shutdown();
        }

        shutdownExecutorGracefully(heartbeatExecutor);
@@ -126,394 +152,164 @@
        }
        shutdownExecutorGracefully(sharedExecutor);

        log.info("GateKlineWebSocketClient销毁完成");
        log.info("[WS] 销毁完成");
    }

    private static final String WS_URL_MONIPAN = "wss://ws-testnet.gate.com/v4/ws/futures/usdt";
    private static final String WS_URL_SHIPAN = "wss://fx-ws.gateio.ws/v4/ws/usdt";
    private static final boolean isAccountType = false;

    /**
     * 建立与 Gate WebSocket 服务器的连接。
     * 设置回调函数以监听连接打开、接收消息、关闭和错误事件。
     * 建立 WebSocket 连接。使用 SSLContext 配置 TLS 协议。
     *
     * <h3>连接成功回调</h3>
     * <ol>
     *   <li>设置 isConnected=true，isConnecting=false</li>
     *   <li>重置心跳计时器</li>
     *   <li>依次订阅所有已注册的频道处理器</li>
     *   <li>发送首次 ping</li>
     * </ol>
     *
     * <h3>连接关闭回调</h3>
     * 设置断连状态 → 取消心跳超时 → 异步触发指数退避重连（最多3次）。
     *
     * <h3>线程安全</h3>
     * 使用 {@code AtomicBoolean.isConnecting} 防止并发重连。
     */
    private void connect() {
        // 避免重复连接
        if (isConnecting.get()) {
            log.info("连接已在进行中，跳过重复连接请求");
        if (isConnecting.get() || !isConnecting.compareAndSet(false, true)) {
            log.info("[WS] 连接进行中，跳过重复请求");
            return;
        }
        
        if (!isConnecting.compareAndSet(false, true)) {
            log.info("连接已在进行中，跳过重复连接请求");
            return;
        }
        
        try {
            SSLConfig.configureSSL();
            System.setProperty("https.protocols", "TLSv1.2,TLSv1.3");
            String WS_URL = WS_URL_MONIPAN;
            if (isAccountType){
                WS_URL = WS_URL_SHIPAN;
            }
            URI uri = new URI(WS_URL);
            
            // 关闭之前的连接（如果存在）
            URI uri = new URI(wsUrl);
            if (webSocketClient != null) {
                try {
                    webSocketClient.closeBlocking();
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    log.warn("关闭之前连接时被中断");
                }
                try { webSocketClient.closeBlocking(); } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
            }
            
            webSocketClient = new WebSocketClient(uri) {
                @Override
                public void onOpen(ServerHandshake handshake) {
                    log.info("Gate Kline WebSocket连接成功");
                    log.info("[WS] 连接成功");
                    isConnected.set(true);
                    isConnecting.set(false);
                    
                    // 检查应用是否正在关闭
                    if (sharedExecutor != null && !sharedExecutor.isShutdown()) {
                        resetHeartbeatTimer();
                        subscribeKlineChannels();
                        subscribePingChannels();
                        for (GateChannelHandler handler : channelHandlers) {
                            handler.subscribe(webSocketClient);
                        }
                        sendPing();
                    } else {
                        log.warn("应用正在关闭，忽略WebSocket连接成功回调");
                        log.warn("[WS] 应用正在关闭，忽略连接成功回调");
                    }
                }

                @Override
                public void onMessage(String message) {
                    lastMessageTime.set(System.currentTimeMillis());
                    handleWebSocketMessage(message);
                    handleMessage(message);
                    resetHeartbeatTimer();
                }

                @Override
                public void onClose(int code, String reason, boolean remote) {
                    log.warn("Gate Kline WebSocket连接关闭: code={}, reason={}", code, reason);
                    log.warn("[WS] 连接关闭, code:{}, reason:{}", code, reason);
                    isConnected.set(false);
                    isConnecting.set(false);
                    cancelPongTimeout();

                    if (sharedExecutor != null && !sharedExecutor.isShutdown() && !sharedExecutor.isTerminated()) {
                        sharedExecutor.execute(() -> {
                            try {
                                reconnectWithBackoff();
                            } catch (InterruptedException e) {
                                Thread.currentThread().interrupt();
                                log.error("重连线程被中断", e);
                            } catch (Exception e) {
                                log.error("重连失败", e);
                            }
                            try { reconnectWithBackoff(); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } catch (Exception e) { log.error("[WS] 重连失败", e); }
                        });
                    } else {
                        log.warn("共享线程池已关闭，无法执行重连任务");
                        log.warn("[WS] 线程池已关闭，不执行重连");
                    }
                }

                @Override
                public void onError(Exception ex) {
                    log.error("Gate Kline WebSocket发生错误", ex);
                    log.error("[WS] 发生错误", ex);
                    isConnected.set(false);
                }
            };

            webSocketClient.connect();
        } catch (URISyntaxException e) {
            log.error("WebSocket URI格式错误", e);
            log.error("[WS] URI格式错误", e);
            isConnecting.set(false);
        }
    }

    /**
     * 订阅K线频道。
     * 构造 Gate 格式的订阅请求并发送给服务端。
     * payload: ["1m", "BTC_USDT"] (间隔, 合约名)
     * 消息分发：先处理系统事件（pong/subscribe/error），
     * 再把 update/all 事件路由到各 channelHandler。
     * <p>每个 handler 内部通过 channel 名称做二次匹配，匹配成功返回 true 则停止遍历。
     */
    private void subscribeKlineChannels() {
        JSONObject subscribeMsg = new JSONObject();
        subscribeMsg.put("time", System.currentTimeMillis() / 1000);
        subscribeMsg.put("channel", CHANNEL);
        subscribeMsg.put("event", "subscribe");

        JSONArray payload = new JSONArray();
        payload.add(GATE_INTERVAL);
        payload.add(GATE_CONTRACT);
        subscribeMsg.put("payload", payload);

        webSocketClient.send(subscribeMsg.toJSONString());
        log.info("已发送 K线频道订阅请求，合约: {}, 周期: {}", GATE_CONTRACT, GATE_INTERVAL);
    }
    private void subscribePingChannels() {
        JSONObject subscribeMsg = new JSONObject();
        subscribeMsg.put("time", System.currentTimeMillis() / 1000);
        subscribeMsg.put("channel", FUTURES_PING);
        webSocketClient.send(subscribeMsg.toJSONString());
        log.info("已发送 futures.ping");
    }

    private void unsubscribeKlineChannels() {
        JSONObject unsubscribeMsg = new JSONObject();
        unsubscribeMsg.put("time", System.currentTimeMillis() / 1000);
        unsubscribeMsg.put("channel", CHANNEL);
        unsubscribeMsg.put("event", "unsubscribe");
        JSONArray payload = new JSONArray();
        payload.add(GATE_INTERVAL);
        payload.add(GATE_CONTRACT);
        unsubscribeMsg.put("payload", payload);
        webSocketClient.send(unsubscribeMsg.toJSONString());
        log.info("已发送 K线频道取消订阅请求，合约: {}, 周期: {}", GATE_CONTRACT, GATE_INTERVAL);
    }

    /**
     * 处理从 WebSocket 收到的消息。
     * 包括订阅确认、错误响应、心跳响应以及实际的数据推送。
     *
     * @param message 来自 WebSocket 的原始字符串消息
     */
    private void handleWebSocketMessage(String message) {
    private void handleMessage(String message) {
        try {
            JSONObject response = JSON.parseObject(message);
            String channel = response.getString("channel");
            String event = response.getString("event");

            if (FUTURES_PONG.equals(channel)) {
                log.debug("收到futures.pong响应");
                log.debug("[WS] 收到 pong 响应");
                cancelPongTimeout();
            } else if ("subscribe".equals(event)) {
                log.info("{} 频道订阅成功: {}", channel, response.getJSONObject("result"));
            } else if ("unsubscribe".equals(event)) {
                log.info("{} 频道取消订阅成功", channel);
            } else if ("error".equals(event)) {
                return;
            }
            if ("subscribe".equals(event)) {
                log.info("[WS] {} 订阅成功: {}", channel, response.getJSONObject("result"));
                return;
            }
            if ("unsubscribe".equals(event)) {
                log.info("[WS] {} 取消订阅成功", channel);
                return;
            }
            if ("error".equals(event)) {
                JSONObject error = response.getJSONObject("error");
                log.error("{} 频道错误: code={}, msg={}",
                log.error("[WS] {} 错误, code:{}, msg:{}",
                        channel,
                        error != null ? error.getInteger("code") : "N/A",
                        error != null ? error.getString("message") : response.getString("msg"));
            } else if ("update".equals(event) || "all".equals(event)) {
                processPushDataV2(response);
            }
        } catch (Exception e) {
            log.error("处理WebSocket消息失败: {}", message, e);
        }
    }

    /**
     * 解析并处理K线推送数据。
     * 控制台输出K线数据，并在K线完结时触发策略和量化操作。
     *
     * @param response 包含K线数据的 JSON 对象
     */
    private void processPushDataV2(JSONObject response) {
        try {
            /**
             * Gate K线推送格式：
             * {
             *   "time": 1542162490,
             *   "time_ms": 1542162490123,
             *   "channel": "futures.candlesticks",
             *   "event": "update",
             *   "result": [
             *     {
             *       "t": 1545129300,
             *       "v": "27525555",
             *       "c": "95.4",
             *       "h": "96.9",
             *       "l": "89.5",
             *       "o": "94.3",
             *       "n": "1m_BTC_USD",
             *       "a": "314732.87412",
             *       "w": false
             *     }
             *   ]
             * }
             */
            String channel = response.getString("channel");
            if (!CHANNEL.equals(channel)) {
                return;
            }

            JSONArray resultArray = response.getJSONArray("result");
            if (resultArray == null || resultArray.isEmpty()) {
                log.warn("K线频道数据为空");
                return;
            }

            JSONObject data = resultArray.getJSONObject(0);
            BigDecimal openPx = new BigDecimal(data.getString("o"));
            BigDecimal highPx = new BigDecimal(data.getString("h"));
            BigDecimal lowPx = new BigDecimal(data.getString("l"));
            BigDecimal closePx = new BigDecimal(data.getString("c"));
            BigDecimal vol = new BigDecimal(data.getString("v"));
            BigDecimal baseVol = new BigDecimal(data.getString("a"));
            String name = data.getString("n");
            long tsSeconds = data.getLong("t");
            boolean windowClosed = data.getBooleanValue("w");
            String time = DateUtil.TimeStampToDateTime(tsSeconds * 1000);

            System.out.println("========== Gate K线数据 ==========");
            System.out.println("名称(n): " + name);
            System.out.println("时间  : " + time);
            System.out.println("开盘(o): " + openPx);
            System.out.println("最高(h): " + highPx);
            System.out.println("最低(l): " + lowPx);
            System.out.println("收盘(c): " + closePx);
            System.out.println("成交量(v): " + vol);
            System.out.println("成交额(a): " + baseVol);
            System.out.println("K线完结(w): " + windowClosed);
            System.out.println("==================================");

            if (windowClosed) {
                MacdEmaStrategy strategy = new MacdEmaStrategy();

                List<Kline> kline1MinuteData = getKlineDataByInstIdAndBar(CoinEnums.HE_YUE.getCode(), "1m");
                List<BigDecimal> historicalPrices1M = kline1MinuteData.stream()
                        .map(Kline::getC)
                        .collect(Collectors.toList());

                MacdEmaStrategy.TradingOrder tradingOrderOpenOpen = strategy.generateTradingOrder(historicalPrices1M, MacdMaStrategy.OperationType.open.name());
                if (tradingOrderOpenOpen == null) {
                    return;
            if ("update".equals(event) || "all".equals(event)) {
                for (GateChannelHandler handler : channelHandlers) {
                    if (handler.handleMessage(response)) return;
                }

            }
        } catch (Exception e) {
            log.error("处理 K线频道推送数据失败", e);
            log.error("[WS] 处理消息失败: {}", message, e);
        }
    }

    private void doOpen(WebSocketClient webSocketClient, String accountName, MacdEmaStrategy.TradingOrder tradingOrderOpenOpen, BigDecimal closePx) {
        // 根据信号执行交易操作
        TradeRequestParam tradeRequestParam = new TradeRequestParam();

        String posSide = tradingOrderOpenOpen.getPosSide();
        tradeRequestParam.setPosSide(posSide);
        String currentPrice = String.valueOf(closePx);
        tradeRequestParam = caoZuoService.caoZuoStrategy(accountName, currentPrice, posSide);

        String side = tradingOrderOpenOpen.getSide();
        tradeRequestParam.setSide(side);

        String clOrdId = WsParamBuild.getOrderNum(side);
        tradeRequestParam.setClOrdId(clOrdId);

        String sz = InstrumentsWs.getAccountMap(accountName).get(CoinEnums.BUY_CNT_INIT.name());
        tradeRequestParam.setSz(sz);
        TradeOrderWs.orderEvent(webSocketClient, tradeRequestParam);
    }

    private List<Kline> getKlineDataByInstIdAndBar(String instId, String bar) {
        List<Kline> klineList = new ArrayList<>();
        try {
            LinkedHashMap<String, Object> requestParam = new LinkedHashMap<>();
            requestParam.put("instId", instId);
            requestParam.put("bar", bar);
            requestParam.put("limit", "200");
            String result = ExchangeLoginService.getInstance(ExchangeInfoEnum.OKX_UAT.name()).lineHistory(requestParam);
            JSONObject json = JSON.parseObject(result);
            String data = json.getString("data");
            
            if (data != null) {
                List<String[]> klinesList = JSON.parseArray(data, String[].class);
                if (!CollUtil.isEmpty(klinesList)) {
                    for (String[] s : klinesList) {
                        // 确保数组有足够的元素
                        if (s != null && s.length >= 9) {
                            String s1 = s[8];
                            try {
                                if ("1".equals(s1)){
                                    Kline kline = new Kline();
                                    kline.setTs(s[0]);
                                    kline.setO(new BigDecimal(s[1]));
                                    kline.setH(new BigDecimal(s[2]));
                                    kline.setL(new BigDecimal(s[3]));
                                    kline.setC(new BigDecimal(s[4]));
                                    kline.setVol(new BigDecimal(s[5]));
                                    kline.setConfirm(s[8]);
                                    klineList.add(kline);
                                }
                            } catch (NumberFormatException e) {
                                log.error("K线数据转换为BigDecimal失败: {}", Arrays.toString(s), e);
                            }
                        } else {
                            log.warn("K线数据数组长度不足: {}", Arrays.toString(s));
                        }
                    }
                }
            } else {
                log.warn("K线数据为空");
            }
        } catch (JSONException e) {
            log.error("K线数据解析失败", e);
        } catch (Exception e) {
            log.error("获取K线数据异常", e);
        }
        return klineList;
    }
    // ---- heartbeat ----

    /**
     * 构建 Redis Key
     */
    private String buildRedisKey(String instId) {
        return "PRICE_" + instId.replace("-", "");
    }

    /**
     * 启动心跳检测任务。
     * 使用 ScheduledExecutorService 定期检查是否需要发送 ping 请求来维持连接。
     * 启动心跳检测器。
     * 使用单线程 ScheduledExecutor，每 25 秒检查一次心跳超时。
     */
    private void startHeartbeat() {
        if (heartbeatExecutor != null && !heartbeatExecutor.isTerminated()) {
            heartbeatExecutor.shutdownNow();
        }

        heartbeatExecutor = Executors.newSingleThreadScheduledExecutor(r -> {
            Thread t = new Thread(r, "gate-kline-heartbeat");
            t.setDaemon(true);
            return t;
        });

        if (heartbeatExecutor != null && !heartbeatExecutor.isTerminated()) heartbeatExecutor.shutdownNow();
        heartbeatExecutor = Executors.newSingleThreadScheduledExecutor(r -> { Thread t = new Thread(r, "gate-ws-heartbeat"); t.setDaemon(true); return t; });
        heartbeatExecutor.scheduleWithFixedDelay(this::checkHeartbeatTimeout, 25, 25, TimeUnit.SECONDS);
    }

    /**
     * 重置心跳计时器。
     * 当收到新消息或发送 ping 后取消当前超时任务并重新安排下一次超时检查。
     * 重置心跳计时器：取消旧超时任务，提交新的 10 秒超时检测。
     */
    private synchronized void resetHeartbeatTimer() {
        cancelPongTimeout();

        if (heartbeatExecutor != null && !heartbeatExecutor.isShutdown()) {
            pongTimeoutFuture = heartbeatExecutor.schedule(this::checkHeartbeatTimeout,
                    HEARTBEAT_TIMEOUT, TimeUnit.SECONDS);
            pongTimeoutFuture = heartbeatExecutor.schedule(this::checkHeartbeatTimeout, HEARTBEAT_TIMEOUT, TimeUnit.SECONDS);
        }
    }

    /**
     * 检查心跳超时情况。
     * 若长时间未收到任何消息则主动发送 ping 请求保持连接活跃。
     * 检查心跳超时：如果距离上次收到消息超过 10 秒，主动发送 futures.ping。
     */
    private void checkHeartbeatTimeout() {
        // 只有在连接状态下才检查心跳
        if (!isConnected.get()) {
            return;
        }
        
        long currentTime = System.currentTimeMillis();
        long lastTime = lastMessageTime.get();

        if (currentTime - lastTime >= HEARTBEAT_TIMEOUT * 1000L) {
            sendPing();
        }
        if (!isConnected.get()) return;
        if (System.currentTimeMillis() - lastMessageTime.get() >= HEARTBEAT_TIMEOUT * 1000L) sendPing();
    }

    /**
     * 发送 ping 请求至 WebSocket 服务端。
     * 用于维持长连接有效性。
     * 发送应用层 futures.ping 消息。
     */
    private void sendPing() {
        try {
@@ -522,62 +318,42 @@
                pingMsg.put("time", System.currentTimeMillis() / 1000);
                pingMsg.put("channel", FUTURES_PING);
                webSocketClient.send(pingMsg.toJSONString());
                log.debug("发送futures.ping请求");
                log.debug("[WS] 发送 ping 请求");
            }
        } catch (Exception e) {
            log.warn("发送ping失败", e);
        }
        } catch (Exception e) { log.warn("[WS] 发送 ping 失败", e); }
    }

    /**
     * 取消当前的心跳超时任务。
     * 在收到 pong 或其他有效消息时调用此方法避免不必要的断开重连。
     * 取消心跳超时检测任务。
     */
    private synchronized void cancelPongTimeout() {
        if (pongTimeoutFuture != null && !pongTimeoutFuture.isDone()) {
            pongTimeoutFuture.cancel(true);
        }
        if (pongTimeoutFuture != null && !pongTimeoutFuture.isDone()) pongTimeoutFuture.cancel(true);
    }

    // ---- reconnect ----

    /**
     * 执行 WebSocket 重连操作。
     * 在连接意外中断后尝试重新建立连接。
     * 指数退避重连。初始延迟 5 秒，每次翻倍，最多重试 3 次。
     *
     * @throws InterruptedException 线程被中断
     */
    private void reconnectWithBackoff() throws InterruptedException {
        int attempt = 0;
        int maxAttempts = 3;
        int attempt = 0, maxAttempts = 3;
        long delayMs = 5000;

        while (attempt < maxAttempts) {
            try {
                Thread.sleep(delayMs);
                connect();
                return;
            } catch (Exception e) {
                log.warn("第{}次重连失败", attempt + 1, e);
                delayMs *= 2;
                attempt++;
            }
            try { Thread.sleep(delayMs); connect(); return; } catch (Exception e) { log.warn("[WS] 第{}次重连失败", attempt + 1, e); delayMs *= 2; attempt++; }
        }

        log.error("超过最大重试次数({})仍未连接成功", maxAttempts);
        log.error("[WS] 超过最大重试次数({})，放弃重连", maxAttempts);
    }

    /**
     * 优雅关闭线程池
     * 优雅关闭线程池：先 shutdown，等待 5 秒，超时则 shutdownNow 强制中断。
     *
     * @param executor 需要关闭的线程池
     */
    private void shutdownExecutorGracefully(ExecutorService executor) {
        if (executor == null || executor.isTerminated()) {
            return;
        }
        try {
            executor.shutdown();
            if (!executor.awaitTermination(5, TimeUnit.SECONDS)) {
                executor.shutdownNow();
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            executor.shutdownNow();
        }
        if (executor == null || executor.isTerminated()) return;
        try { executor.shutdown(); if (!executor.awaitTermination(5, TimeUnit.SECONDS)) executor.shutdownNow(); }
        catch (InterruptedException e) { Thread.currentThread().interrupt(); executor.shutdownNow(); }
    }
}
}