From be6ebe0f51aacef4435ee3d81a913bf8e8b48505 Mon Sep 17 00:00:00 2001
From: Administrator <15274802129@163.com>
Date: Mon, 11 May 2026 16:22:56 +0800
Subject: [PATCH] docs(gateApi): 更新代码注释和文档说明
---
src/main/java/com/xcong/excoin/modules/gateApi/GateKlineWebSocketClient.java | 99 ++++++++++++++++++++++++++++++++++++-------------
1 files changed, 72 insertions(+), 27 deletions(-)
diff --git a/src/main/java/com/xcong/excoin/modules/gateApi/GateKlineWebSocketClient.java b/src/main/java/com/xcong/excoin/modules/gateApi/GateKlineWebSocketClient.java
index 14a46ba..d4cec97 100644
--- a/src/main/java/com/xcong/excoin/modules/gateApi/GateKlineWebSocketClient.java
+++ b/src/main/java/com/xcong/excoin/modules/gateApi/GateKlineWebSocketClient.java
@@ -48,6 +48,7 @@
*
* @author Administrator
*/
+@SuppressWarnings("ALL")
@Slf4j
public class GateKlineWebSocketClient {
@@ -90,17 +91,20 @@
/**
* 注册频道处理器。需在 init() 前调用。
+ *
+ * @param handler 实现了 {@link GateChannelHandler} 接口的频道处理器
*/
public void addChannelHandler(GateChannelHandler handler) {
channelHandlers.add(handler);
}
/**
- * 初始化：建立 WebSocket 连接 → 启动心跳。
+ * 初始化：建立 WebSocket 连接 → 启动心跳检测。
+ * 使用 {@code AtomicBoolean} 防重入，同一实例只允许初始化一次。
*/
public void init() {
if (!isInitialized.compareAndSet(false, true)) {
- log.warn("[WS] already init, skip");
+ log.warn("[WS] 已初始化过，跳过重复初始化");
return;
}
connect();
@@ -108,12 +112,14 @@
}
/**
- * 销毁：取消订阅 → 关闭连接 → 关闭线程池。
- * <p>注意：先 closeBlocking 再 shutdown sharedExecutor，
- * 避免 onClose 回调中的 reconnectWithBackoff 访问已关闭的线程池。
+ * 销毁：取消所有频道订阅 → 关闭 WebSocket 连接 → 关闭线程池。
+ *
+ * <h3>执行顺序</h3>
+ * 先取消订阅（等待 500ms 确保发送完成），再 closeBlocking 关闭连接，
+ * 最后 shutdown 线程池。先关连接再关线程池，避免 onClose 回调中的重连任务访问已关闭的线程池。
*/
public void destroy() {
- log.info("[WS] destroy...");
+ log.info("[WS] 开始销毁...");
if (webSocketClient != null && webSocketClient.isOpen()) {
for (GateChannelHandler handler : channelHandlers) {
@@ -123,7 +129,7 @@
Thread.sleep(500);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
- log.warn("[WS] unsubscribe wait interrupted");
+ log.warn("[WS] 取消订阅等待被中断");
}
}
@@ -132,7 +138,7 @@
webSocketClient.closeBlocking();
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
- log.warn("[WS] close interrupted");
+ log.warn("[WS] 关闭连接时被中断");
}
}
@@ -146,16 +152,29 @@
}
shutdownExecutorGracefully(sharedExecutor);
- log.info("[WS] destroyed");
+ log.info("[WS] 销毁完成");
}
/**
* 建立 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() || !isConnecting.compareAndSet(false, true)) {
- log.info("[WS] already connecting");
+ log.info("[WS] 连接进行中，跳过重复请求");
return;
}
try {
@@ -168,7 +187,7 @@
webSocketClient = new WebSocketClient(uri) {
@Override
public void onOpen(ServerHandshake handshake) {
- log.info("[WS] connected");
+ log.info("[WS] 连接成功");
isConnected.set(true);
isConnecting.set(false);
if (sharedExecutor != null && !sharedExecutor.isShutdown()) {
@@ -178,7 +197,7 @@
}
sendPing();
} else {
- log.warn("[WS] shutting down, ignore onOpen");
+ log.warn("[WS] 应用正在关闭，忽略连接成功回调");
}
}
@@ -191,28 +210,28 @@
@Override
public void onClose(int code, String reason, boolean remote) {
- log.warn("[WS] closed, 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(); } catch (Exception e) { log.error("[WS] reconnect fail", e); }
+ try { reconnectWithBackoff(); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } catch (Exception e) { log.error("[WS] 重连失败", e); }
});
} else {
- log.warn("[WS] executor closed, no reconnect");
+ log.warn("[WS] 线程池已关闭，不执行重连");
}
}
@Override
public void onError(Exception ex) {
- log.error("[WS] error", ex);
+ log.error("[WS] 发生错误", ex);
isConnected.set(false);
}
};
webSocketClient.connect();
} catch (URISyntaxException e) {
- log.error("[WS] bad uri", e);
+ log.error("[WS] URI格式错误", e);
isConnecting.set(false);
}
}
@@ -229,21 +248,21 @@
String event = response.getString("event");
if (FUTURES_PONG.equals(channel)) {
- log.debug("[WS] pong received");
+ log.debug("[WS] 收到 pong 响应");
cancelPongTimeout();
return;
}
if ("subscribe".equals(event)) {
- log.info("[WS] {} subscribed: {}", channel, response.getJSONObject("result"));
+ log.info("[WS] {} 订阅成功: {}", channel, response.getJSONObject("result"));
return;
}
if ("unsubscribe".equals(event)) {
- log.info("[WS] {} unsubscribed", channel);
+ log.info("[WS] {} 取消订阅成功", channel);
return;
}
if ("error".equals(event)) {
JSONObject error = response.getJSONObject("error");
- log.error("[WS] {} error, code:{}, msg:{}",
+ log.error("[WS] {} 错误, code:{}, msg:{}",
channel,
error != null ? error.getInteger("code") : "N/A",
error != null ? error.getString("message") : response.getString("msg"));
@@ -255,18 +274,25 @@
}
}
} catch (Exception e) {
- log.error("[WS] handle msg fail: {}", message, e);
+ log.error("[WS] 处理消息失败: {}", message, e);
}
}
// ---- heartbeat ----
+ /**
+ * 启动心跳检测器。
+ * 使用单线程 ScheduledExecutor，每 25 秒检查一次心跳超时。
+ */
private void startHeartbeat() {
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);
}
+ /**
+ * 重置心跳计时器：取消旧超时任务，提交新的 10 秒超时检测。
+ */
private synchronized void resetHeartbeatTimer() {
cancelPongTimeout();
if (heartbeatExecutor != null && !heartbeatExecutor.isShutdown()) {
@@ -274,11 +300,17 @@
}
}
+ /**
+ * 检查心跳超时：如果距离上次收到消息超过 10 秒，主动发送 futures.ping。
+ */
private void checkHeartbeatTimeout() {
if (!isConnected.get()) return;
if (System.currentTimeMillis() - lastMessageTime.get() >= HEARTBEAT_TIMEOUT * 1000L) sendPing();
}
+ /**
+ * 发送应用层 futures.ping 消息。
+ */
private void sendPing() {
try {
if (webSocketClient != null && webSocketClient.isOpen()) {
@@ -286,26 +318,39 @@
pingMsg.put("time", System.currentTimeMillis() / 1000);
pingMsg.put("channel", FUTURES_PING);
webSocketClient.send(pingMsg.toJSONString());
- log.debug("[WS] ping sent");
+ log.debug("[WS] 发送 ping 请求");
}
- } catch (Exception e) { log.warn("[WS] ping fail", e); }
+ } catch (Exception e) { log.warn("[WS] 发送 ping 失败", e); }
}
+ /**
+ * 取消心跳超时检测任务。
+ */
private synchronized void cancelPongTimeout() {
if (pongTimeoutFuture != null && !pongTimeoutFuture.isDone()) pongTimeoutFuture.cancel(true);
}
// ---- reconnect ----
+ /**
+ * 指数退避重连。初始延迟 5 秒，每次翻倍，最多重试 3 次。
+ *
+ * @throws InterruptedException 线程被中断
+ */
private void reconnectWithBackoff() throws InterruptedException {
int attempt = 0, maxAttempts = 3;
long delayMs = 5000;
while (attempt < maxAttempts) {
- try { Thread.sleep(delayMs); connect(); return; } catch (Exception e) { log.warn("[WS] reconnect attempt {} fail", 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("[WS] reconnect exhausted after {} attempts", 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(); }
--
Gitblit v1.9.1