From 01da1f754426a1285fc20b9cf1b80672b16d8814 Mon Sep 17 00:00:00 2001
From: Administrator <15274802129@163.com>
Date: Fri, 08 May 2026 15:04:28 +0800
Subject: [PATCH] refactor(gateApi): 重构网格交易服务添加补仓重试机制
---
src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md | 125 ++++++++++++++++++++++++++++-------------
1 files changed, 86 insertions(+), 39 deletions(-)
diff --git a/src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md b/src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md
index d2555eb..a4dd080 100644
--- a/src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md
+++ b/src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md
@@ -7,8 +7,8 @@
| [GateWebSocketClientManager](#gatewebsocketclientmanager) | `@Component` | Spring 启动入口，组装组件 + 生命周期 |
| [GateConfig](#gateconfig) | 配置 | Builder 模式：API 密钥、合约、策略参数、环境切换 |
| [GateKlineWebSocketClient](#gateklinewebsocketclient) | WS 连接管理 | 连接/心跳/重连/消息路由 |
-| [GateGridTradeService](#gategridtradeservice) | 交易服务 | 网格策略状态机 + 盈亏管理 |
-| [GateTradeExecutor](#gatetradeexecutor) | 异步执行器 | 独立线程池执行 REST 下单，不阻塞 WS 回调线程 |
+| [GateGridTradeService](#gategridtradeservice) | 交易服务 | 网格策略状态机 + 盈亏管理 + 补仓重试 |
+| [GateTradeExecutor](#gatetradeexecutor) | 异步执行器 | 独立线程池执行 REST 下单，成功/失败双回调 |
| [GateWebSocketClientMain](#gatewebsocketclientmain) | main 入口 | 独立测试启动 |
| [Example.java](#examplejava) | 示例 | Gate SDK 用法参考 |
@@ -19,7 +19,7 @@
| `wsHandler/GateChannelHandler.java` | **接口** | subscribe / unsubscribe / handleMessage / getChannelName |
| `wsHandler/AbstractPrivateChannelHandler.java` | **抽象类** | 私有频道基类：HMAC-SHA512 签名 + 认证请求 |
| `wsHandler/handler/CandlestickChannelHandler.java` | 公开频道 | K 线解析 → `onKline()` |
-| `wsHandler/handler/PositionsChannelHandler.java` | 私有频道 | 仓位推送 → `onPositionUpdate()` |
+| `wsHandler/handler/PositionsChannelHandler.java` | 私有频道 | 仓位推送 → `onPositionUpdate()`（传 `Position.ModeEnum`） |
| `wsHandler/handler/PositionClosesChannelHandler.java` | 私有频道 | 平仓推送 → `onPositionClose()` |
---
@@ -36,7 +36,7 @@
│ │ REST BasePath │ GateTradeExecutor │ WS URL │
│ ▼ ▼ ▼ │
│ Gate API (REST) 独立线程池 (async) Gate WebSocket │
-│ ┌──────────────┐ │
+│ onSuccess/onFailure双回调 ┌──────────────┐ │
│ │Candlestick H │ │
│ │Positions H │ │
│ │PosCloses H │ │
@@ -62,9 +62,10 @@
│
├─ futures.positions (私有, HMAC-SHA512)
│ └─ PositionsChannelHandler
+│ ├─ 解析 mode → Position.ModeEnum（DUAL_LONG / DUAL_SHORT）
│ └─ gridTradeService.onPositionUpdate(mode, size, entryPrice)
-│ ├─ size=0 && longActive → tryReopenLong()
-│ └─ size=0 && shortActive → tryReopenShort()
+│ ├─ DUAL_LONG, size=0 && longActive → tryReopenLong()
+│ └─ DUAL_SHORT, size=0 && shortActive → tryReopenShort()
│
├─ futures.position_closes (私有, HMAC-SHA512)
│ └─ PositionClosesChannelHandler
@@ -73,7 +74,8 @@
│
└─ 所有下单操作
└─ GateTradeExecutor (单线程 + 64队列 + CallerRunsPolicy)
- ├─ openLong/openShort → 市价单 (REST)
+ ├─ openLong/Short(qty, onSuccess, onFailure)
+ │ └─ 失败回调 → tryReopenXxx() 递归重试
└─ placeTakeProfit → 条件单 (REST)
```
@@ -85,7 +87,7 @@
GateChannelHandler (接口)
├── CandlestickChannelHandler (公开频道)
└── AbstractPrivateChannelHandler (私有频道基类: HMAC-SHA512)
- ├── PositionsChannelHandler
+ ├── PositionsChannelHandler (解析 mode → Position.ModeEnum)
└── PositionClosesChannelHandler
```
@@ -93,6 +95,7 @@
- **unsubscribe**: 发送取消订阅请求（私有频道也带签名认证）
- **handleMessage**: 解析推送数据并回调GateGridTradeService，返回true表示已处理
- 消息路由: update/all事件 → 遍历channelHandlers → handler内部二次匹配channel名 → 匹配成功回调并停止遍历
+- **PositionsChannelHandler 特殊处理**: 推送的 mode 字符串（"dual_long"）通过 `Position.ModeEnum.fromValue()` 转为枚举，避免调用方用字符串匹配
---
@@ -101,9 +104,11 @@
```
WAITING_KLINE ──onKline──→ OPENING ──双开成功──→ ACTIVE
│ │ │
- │ 双开失败 ├─ size=0 → REOPENING_L/S → ACTIVE
- │ ├─ 补仓失败 retry → 仍失败 → STOPPED
- │ └─ cumulativePnl≥TP 或 ≤-maxLoss → STOPPED
+ │ 双开失败 ├─ size=0 → REOPENING_L/S
+ │ │ ├─ 补仓成功 → ACTIVE
+ │ │ └─ 补仓失败 → 递归重试
+ │ │ └─ 超 reopenMaxRetries → STOPPED
+ │ └─ cumPnl≥TP 或 ≤-maxLoss → STOPPED
▼
STOPPED ←─────────────────────────────────────────┘
```
@@ -115,19 +120,26 @@
| `ACTIVE` | 网格运行中，等待止盈触发 |
| `REOPENING_LONG` | 正在补开多头 |
| `REOPENING_SHORT` | 正在补开空头 |
-| `STOPPED` | 停止（盈利达标 / 亏损超限 / 异常退出） |
+| `STOPPED` | 停止（盈利达标 / 亏损超限 / 补仓重试耗尽 / 异常退出） |
---
## 策略时序
-### 阶段 1：启动
+### 阶段 1：启动与初始化
```
Spring @PostConstruct
→ GateConfig.builder()...build()
→ GateGridTradeService(config)
- → init(): 查ID → 查账户切持仓 → 清旧条件单 → 平已有仓位 → 设杠杆
+ → init():
+ 1. 查用户ID
+ 2. 查账户 → 如需要切持仓模式
+ 3. 清除旧止盈止损条件单
+ 4. 查当前合约所有仓位 → 逐个市价平仓（reduce_only, IOC）
+ - 单向持仓: size=相反数平仓
+ - 双向持仓: size=0, close=false, autoSize=LONG/SHORT
+ 5. 设杠杆
→ GateKlineWebSocketClient(config.getWsUrl())
→ addChannelHandler x3 → init() → connect()
→ onOpen: handlers依次subscribe → sendPing
@@ -138,28 +150,35 @@
```
K线推送 → onKline(closePrice) → state=OPENING
- → GateTradeExecutor.openLong → 市价开多 → onSuccess: longActive=true, 下TP单
- → GateTradeExecutor.openShort → 市价开空 → onSuccess: shortActive=true, 下TP单
+ → GateTradeExecutor.openLong(qty, onSuccess, null)
+ → 市价开多 → onSuccess: longActive=true, placeTakeProfit(多头TP)
+ → GateTradeExecutor.openShort(-qty, onSuccess, null)
+ → 市价开空 → onSuccess: shortActive=true, placeTakeProfit(空头TP)
→ 双开均完成 → state=ACTIVE
```
-### 阶段 3：止盈触发 → 补仓
+### 阶段 3：止盈触发 → 补仓（含重试）
```
-仓位推送: dual_long, size=0 → longActive且无仓位 → tryReopenLong
- → GateTradeExecutor.openLong → 市价补多 → onSuccess: 下新TP单
+仓位推送: mode=DUAL_LONG, size=0 → longActive且无仓位 → tryReopenLong()
+ ┌─ longReopenFails++ → 超 reopenMaxRetries → STOPPED
+ └─ GateTradeExecutor.openLong(qty,
+ onSuccess: failCount=0, ACTIVE, 下新TP单,
+ onFailure: → 递归调用 tryReopenLong() 再试
+ )
-仓位推送: dual_short, size=0 → shortActive且无仓位 → tryReopenShort
- → GateTradeExecutor.openShort → 市价补空 → onSuccess: 下新TP单
+仓位推送: mode=DUAL_SHORT, size=0 → 同理 tryReopenShort()
```
> 止盈由 Gate 服务端条件单自动执行。只补被平掉的单方向，另一方不受影响。
+> 补仓失败通过 onFailure 回调递归重试，连续失败超过 `reopenMaxRetries`（默认3次）则停止策略。
### 阶段 4：停止
```
平仓推送: pnl=+0.6 → cumulativePnl=0.6 ≥ overallTp → state=STOPPED
平仓推送: pnl=-8.0 → cumulativePnl=-8.0 ≤ -maxLoss → state=STOPPED
+补仓连续失败 4 次 → 超过 reopenMaxRetries=3 → state=STOPPED
```
---
@@ -184,22 +203,27 @@
| overallTp | 0.5 USDT | 整体止盈 |
| maxLoss | 7.5 USDT | 最大亏损 |
| quantity | 1 | 下单张数 |
-| reopenMaxRetries | 3 | 补仓重试次数 |
+| reopenMaxRetries | 3 | 补仓最大重试次数 |
---
## GateTradeExecutor
-**角色**: 独立线程池执行 REST API 下单，解决 WebSocket 回调线程阻塞问题。
+**角色**: 独立线程池执行 REST API 下单。采用成功/失败双回调模式支持补仓重试。
**线程模型**:
- `ThreadPoolExecutor(1, 1, 60s, LinkedBlockingQueue(64), CallerRunsPolicy)`
- 单线程保序 + 有界队列防堆积 + CallerRuns背压
+**回调设计**:
+- 每个下单方法接受 `onSuccess` 和 `onFailure` 两个 `Runnable`
+- REST 调用成功 → 执行 `onSuccess`（更新状态、下止盈单、重置失败计数）
+- REST 调用失败 → 执行 `onFailure`（递归重试入口）
+
| 方法 | 说明 |
|------|------|
-| `openLong(qty, onSuccess)` | 异步 IOC 市价开多，成功回调 |
-| `openShort(qty, onSuccess)` | 异步 IOC 市价开空 |
+| `openLong(qty, onSuccess, onFailure)` | 异步 IOC 市价开多，双回调 |
+| `openShort(qty, onSuccess, onFailure)` | 异步 IOC 市价开空，双回调 |
| `placeTakeProfit(trigger, rule, type, auto)` | 异步条件单。已存在则清除旧单重试 |
| `cancelAllPriceTriggeredOrders()` | 清除所有条件单 |
| `shutdown()` | 等待10秒，超时强制关闭 |
@@ -210,12 +234,31 @@
**角色**: 策略核心，使用 Gate SDK 管理状态和执行下单。
-**状态**: StrategyState enum + longActive/shortActive boolean
+**状态**: `StrategyState` enum + `longActive`/`shortActive` boolean
+
+**关键常量**（替代字面字符串）:
+```java
+private static final String AUTO_SIZE_LONG = "close_long";
+private static final String AUTO_SIZE_SHORT = "close_short";
+private static final String ORDER_TYPE_CLOSE_LONG = "close-long-position";
+private static final String ORDER_TYPE_CLOSE_SHORT = "close-short-position";
+```
**回调方法**:
- `onKline(closePrice)`: 缓存价格，WAITING_KLINE状态下首次触发双开
-- `onPositionUpdate(mode, size, entryPrice)`: size=0且方向活跃 → 补仓
+- `onPositionUpdate(Position.ModeEnum mode, size, entryPrice)`: `== DUAL_LONG/DUAL_SHORT` 枚举比较，size=0且方向活跃 → 补仓重试
- `onPositionClose(side, pnl)`: 累加盈亏，检查停止条件
+
+**补仓重试逻辑**:
+```
+tryReopenLong():
+ 1. longReopenFails++（失败计数递增）
+ 2. 超过 reopenMaxRetries → STOPPED
+ 3. openLong(qty,
+ onSuccess → failCount=0, ACTIVE, 下新TP单,
+ onFailure → 递归 tryReopenLong() 重试
+ )
+```
**止盈计算**:
@@ -226,30 +269,34 @@
**REST API 调用**:
-| 操作 | API | 方法 |
-|------|-----|------|
-| 获取用户ID | `GET /account/detail` | `AccountApi.getAccountDetail()` |
-| 切持仓模式 | `POST /futures/usdt/set_position_mode` | `FuturesApi.setPositionMode()` |
-| 查仓位 | `GET /futures/usdt/positions` | `FuturesApi.listPositions()` |
-| 市价平仓 | `POST /futures/usdt/orders` (reduce_only, IOC) | `FuturesApi.createFuturesOrder()` |
-| 设杠杆 | `POST /futures/usdt/positions/{contract}/leverage` | `FuturesApi.updateContractPositionLeverageCall()` |
-| 查账户 | `GET /futures/usdt/accounts` | `FuturesApi.listFuturesAccounts()` |
-| 清除条件单 | `DELETE /futures/usdt/price_orders` | `FuturesApi.cancelPriceTriggeredOrderList()` |
-| 市价单 | `POST /futures/usdt/orders` (price=0, IOC) | `FuturesApi.createFuturesOrder()` |
-| 条件单 | `POST /futures/usdt/price_orders` | `FuturesApi.createPriceTriggeredOrder()` |
+| 操作 | API | 方法 | 说明 |
+|------|-----|------|------|
+| 获取用户ID | `GET /account/detail` | `AccountApi.getAccountDetail()` | |
+| 切持仓模式 | `POST /futures/usdt/set_position_mode` | `FuturesApi.setPositionMode()` | |
+| 查仓位 | `GET /futures/usdt/positions` | `FuturesApi.listPositions()` | 遍历所有仓位，按合约过滤 |
+| 市价平仓 | `POST /futures/usdt/orders` | `FuturesApi.createFuturesOrder()` | reduce_only, IOC。双向: size=0+close=false+autoSize |
+| 设杠杆 | `POST /futures/usdt/positions/{contract}/leverage` | `FuturesApi.updateContractPositionLeverageCall()` | |
+| 查账户 | `GET /futures/usdt/accounts` | `FuturesApi.listFuturesAccounts()` | |
+| 清除条件单 | `DELETE /futures/usdt/price_orders` | `FuturesApi.cancelPriceTriggeredOrderList()` | |
+| 市价单 | `POST /futures/usdt/orders` | `FuturesApi.createFuturesOrder()` | price=0, tif=IOC |
+| 条件单 | `POST /futures/usdt/price_orders` | `FuturesApi.createPriceTriggeredOrder()` | strategy=0, price_type=0, expiration=0 |
**初始化顺序** (`init()`):
```
1. 获取用户 ID
2. 查账户 → 如需要切持仓模式
3. 清除旧的止盈止损条件单
-4. 市价平掉当前合约所有已有仓位（确保从零持仓开始）
+4. 查当前合约所有仓位 → 逐个市价平仓
+ - 单向持仓(single): size=相反数, reduce_only=true
+ - 双向持仓(dual): size=0, close=false, autoSize=LONG/SHORT, reduce_only=true
5. 设杠杆
6. 打印账户余额
```
---
+## GateWebSocketClientMain
+
独立 `main()` 方法入口，通过 Spring XML 上下文启动，运行后手动关闭。
---
--
Gitblit v1.9.1