From e9a397babbbfa9cff8a5ed026447d585e739c37f Mon Sep 17 00:00:00 2001
From: Administrator <15274802129@163.com>
Date: Tue, 12 May 2026 21:47:21 +0800
Subject: [PATCH] refactor(gateApi): 将网格交易策略从限价单改为条件单
---
src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java | 144 +++++++++++++++++++++++++++++++++++++++++++++--
1 files changed, 137 insertions(+), 7 deletions(-)
diff --git a/src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java b/src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java
index 2a5317a..094eaab 100644
--- a/src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java
+++ b/src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java
@@ -8,31 +8,55 @@
* <p>通过 Builder 模式集中管理所有运行参数，避免参数散落在多个文件中。
* 提供 REST API 和 WebSocket 地址的自动环境切换（测试网/生产网）。
*
+ * <h3>关键参数</h3>
+ * <ul>
+ * <li><b>网格参数</b>：gridRate（比例间距）、step（绝对步长 = shortBaseEntryPrice × gridRate，运行时计算）、
+ * gridQueueSize（队列容量）</li>
+ * <li><b>止盈止损</b>：overallTp（整体止盈 USDT）、maxLoss（最大亏损 USDT）</li>
+ * <li><b>风险控制</b>：marginRatioLimit（保证金占比上限，超限跳过开仓）、leverage（杠杆）、
+ * marginMode（全仓/逐仓）、positionMode（单向/双向）</li>
+ * <li><b>盈亏计算</b>：contractMultiplier（合约乘数）、unrealizedPnlPriceMode（计价模式：最新价/标记价）</li>
+ * </ul>
+ *
* <h3>使用示例</h3>
* <pre>
* GateConfig config = GateConfig.builder()
* .apiKey("...")
* .apiSecret("...")
- * .contract("XAU_USDT")
+ * .contract("ETH_USDT")
* .leverage("100")
* .gridRate(new BigDecimal("0.0035"))
+ * .contractMultiplier("0.01")
* .isProduction(false)
* .build();
- *
- * String restUrl = config.getRestBasePath(); // 自动返回测试网或生产网地址
- * String wsUrl = config.getWsUrl();
* </pre>
*
* <h3>默认值</h3>
* <ul>
* <li>合约: BTC_USDT, 杠杆: 10x, 全仓, 双向持仓</li>
- * <li>网格: 0.35%, 止盈: 0.5 USDT, 亏损: 7.5 USDT</li>
- * <li>数量: 1 张, 环境: 测试网, 重试: 3 次</li>
+ * <li>网格间距: 0.35%, 队列容量: 50, 保证金比例上限: 20%</li>
+ * <li>止盈: 0.5 USDT, 亏损上限: 7.5 USDT</li>
+ * <li>数量: 1 张, 合约乘数: 0.001, 环境: 测试网</li>
* </ul>
*
* @author Administrator
*/
public class GateConfig {
+
+ /**
+ * 未实现盈亏（unrealizedPnl）计价模式。
+ *
+ * <ul>
+ * <li>{@link #LAST_PRICE} — 按最新成交价计算，变动快、更贴近实际平仓价</li>
+ * <li>{@link #MARK_PRICE} — 按标记价格计算，变动平稳、过滤市场噪音</li>
+ * </ul>
+ */
+ public enum PnLPriceMode {
+ /** 按最新成交价计算未实现盈亏 */
+ LAST_PRICE,
+ /** 按标记价格计算未实现盈亏，需通过 {@link GateGridTradeService#setMarkPrice(BigDecimal)} 注入 */
+ MARK_PRICE
+ }
/** Gate API v4 密钥 */
private final String apiKey;
@@ -58,6 +82,16 @@
private final boolean isProduction;
/** 补仓最大重试次数 */
private final int reopenMaxRetries;
+ /** 网格队列容量 */
+ private final int gridQueueSize;
+ /** 保证金占初始本金比例上限 */
+ private final BigDecimal marginRatioLimit;
+ /** 合约乘数（单张合约代表的基础资产数量，如 BTC_USDT=0.001, ETH_USDT=0.01） */
+ private final BigDecimal contractMultiplier;
+ /** 未实现盈亏计价模式：最新价 / 标记价格 */
+ private final PnLPriceMode unrealizedPnlPriceMode;
+ /** 网格绝对步长（shortBaseEntryPrice × gridRate），运行时由队列生成逻辑设置 */
+ private BigDecimal step;
private GateConfig(Builder builder) {
this.apiKey = builder.apiKey;
@@ -72,7 +106,13 @@
this.quantity = builder.quantity;
this.isProduction = builder.isProduction;
this.reopenMaxRetries = builder.reopenMaxRetries;
+ this.gridQueueSize = builder.gridQueueSize;
+ this.marginRatioLimit = builder.marginRatioLimit;
+ this.contractMultiplier = builder.contractMultiplier;
+ this.unrealizedPnlPriceMode = builder.unrealizedPnlPriceMode;
}
+
+ // ==================== REST/WS 地址 ====================
/**
* 根据环境返回 REST API 基础路径。
@@ -100,18 +140,65 @@
: "wss://ws-testnet.gate.com/v4/ws/futures/usdt";
}
+ // ==================== 认证信息 ====================
+
+ /** @return Gate API v4 密钥 */
public String getApiKey() { return apiKey; }
+ /** @return Gate API v4 签名密钥，用于 HMAC-SHA512 签名 */
public String getApiSecret() { return apiSecret; }
+
+ // ==================== 交易标的 ====================
+
+ /** @return 合约名称（如 ETH_USDT、XAU_USDT） */
public String getContract() { return contract; }
+ /** @return 杠杆倍数（如 "100" 表示 100x） */
public String getLeverage() { return leverage; }
+
+ // ==================== 持仓配置 ====================
+
+ /** @return 保证金模式（cross=全仓 / isolated=逐仓） */
public String getMarginMode() { return marginMode; }
+ /** @return 持仓模式（single=单向 / dual=双向 / dual_plus） */
public String getPositionMode() { return positionMode; }
+
+ // ==================== 策略参数 ====================
+
+ /** @return 网格间距比例（如 0.0015 表示 0.15%），用于生成价格队列和计算止盈价 */
public BigDecimal getGridRate() { return gridRate; }
+ /** @return 整体止盈阈值（USDT），累计已实现盈亏 ≥ 此值时策略停止 */
public BigDecimal getOverallTp() { return overallTp; }
+ /** @return 最大亏损阈值（USDT），累计已实现盈亏 ≤ -此值时策略停止 */
public BigDecimal getMaxLoss() { return maxLoss; }
+ /** @return 每次下单的张数（如 "1" 表示 1 张合约） */
public String getQuantity() { return quantity; }
- public boolean isProduction() { return isProduction; }
+ /** @return 网格价格队列的容量上限（超出时截断尾部） */
+ public int getGridQueueSize() { return gridQueueSize; }
+
+ // ==================== 风险控制 ====================
+
+ /** @return 保证金占初始本金比例上限（默认 0.2 即 20%），超限跳过开仓 */
+ public BigDecimal getMarginRatioLimit() { return marginRatioLimit; }
+ /** @return 补仓最大重试次数（当前版本未使用） */
public int getReopenMaxRetries() { return reopenMaxRetries; }
+
+ // ==================== 盈亏计算 ====================
+
+ /** @return 合约乘数（单张合约代表的基础资产数量，如 ETH_USDT=0.01） */
+ public BigDecimal getContractMultiplier() { return contractMultiplier; }
+ /** @return 未实现盈亏计价模式：LAST_PRICE（最新成交价）/ MARK_PRICE（标记价格） */
+ public PnLPriceMode getUnrealizedPnlPriceMode() { return unrealizedPnlPriceMode; }
+
+ // ==================== 运行时参数 ====================
+
+ /** @return 网格绝对步长（shortBaseEntryPrice × gridRate），运行时设置 */
+ public BigDecimal getStep() { return step; }
+ /** 设置网格绝对步长（由 generateShortQueue 在运行时计算并注入） */
+ public void setStep(BigDecimal step) { this.step = step; }
+
+ // ==================== 环境 ====================
+
+ /** @return 是否为生产环境（true=实盘生产网 / false=模拟盘测试网） */
+ public boolean isProduction() { return isProduction; }
public static Builder builder() {
return new Builder();
@@ -119,33 +206,76 @@
/**
* GateConfig 的流式构造器，提供合理的默认值。
+ *
+ * <h3>必填项</h3>
+ * {@code apiKey} 和 {@code apiSecret} 必须设置，其余参数均有默认值。
+ *
+ * <h3>默认值</h3>
+ * BTC_USDT / 10x / cross(全仓) / dual(双向) / gridRate=0.35% /
+ * overallTp=0.5 / maxLoss=7.5 / quantity=1 / isProduction=false
*/
public static class Builder {
+ /** Gate API v4 密钥（必填） */
private String apiKey;
+ /** Gate API v4 签名密钥（必填） */
private String apiSecret;
+ /** 合约名称，默认 BTC_USDT */
private String contract = "BTC_USDT";
+ /** 杠杆倍数，默认 "10" */
private String leverage = "10";
+ /** 保证金模式，默认 "cross"（全仓） */
private String marginMode = "cross";
+ /** 持仓模式，默认 "dual"（双向） */
private String positionMode = "dual";
+ /** 网格间距比例，默认 0.0035（0.35%） */
private BigDecimal gridRate = new BigDecimal("0.0035");
+ /** 整体止盈阈值（USDT），默认 0.5 */
private BigDecimal overallTp = new BigDecimal("0.5");
+ /** 最大亏损阈值（USDT），默认 7.5 */
private BigDecimal maxLoss = new BigDecimal("7.5");
+ /** 每次下单张数，默认 "1" */
private String quantity = "1";
+ /** 是否为生产环境，默认 false（测试网） */
private boolean isProduction = false;
+ /** 补仓最大重试次数，默认 3 */
private int reopenMaxRetries = 3;
+ /** 网格队列容量，默认 50 */
+ private int gridQueueSize = 50;
+ /** 保证金占初始本金比例上限，默认 0.2（20%） */
+ private BigDecimal marginRatioLimit = new BigDecimal("0.2");
+ /** 合约乘数，默认 0.001 */
+ private BigDecimal contractMultiplier = new BigDecimal("0.001");
+ /** 未实现盈亏计价模式，默认 LAST_PRICE（最新成交价） */
+ private PnLPriceMode unrealizedPnlPriceMode = PnLPriceMode.LAST_PRICE;
+ /** 设置 API Key */
public Builder apiKey(String apiKey) { this.apiKey = apiKey; return this; }
+ /** 设置 API Secret */
public Builder apiSecret(String apiSecret) { this.apiSecret = apiSecret; return this; }
+ /** 设置合约名称 */
public Builder contract(String contract) { this.contract = contract; return this; }
+ /** 设置杠杆倍数 */
public Builder leverage(String leverage) { this.leverage = leverage; return this; }
+ /** 设置保证金模式（cross=全仓 / isolated=逐仓） */
public Builder marginMode(String marginMode) { this.marginMode = marginMode; return this; }
+ /** 设置持仓模式（single=单向 / dual=双向） */
public Builder positionMode(String positionMode) { this.positionMode = positionMode; return this; }
+ /** 设置网格间距比例 */
public Builder gridRate(BigDecimal gridRate) { this.gridRate = gridRate; return this; }
+ /** 设置整体止盈阈值（USDT） */
public Builder overallTp(BigDecimal overallTp) { this.overallTp = overallTp; return this; }
+ /** 设置最大亏损阈值（USDT） */
public Builder maxLoss(BigDecimal maxLoss) { this.maxLoss = maxLoss; return this; }
+ /** 设置每次下单张数 */
public Builder quantity(String quantity) { this.quantity = quantity; return this; }
+ /** 设置环境（true=实盘生产网 / false=模拟盘测试网） */
public Builder isProduction(boolean isProduction) { this.isProduction = isProduction; return this; }
+ /** 设置补仓最大重试次数 */
public Builder reopenMaxRetries(int reopenMaxRetries) { this.reopenMaxRetries = reopenMaxRetries; return this; }
+ /** 设置合约乘数（单张合约代表的基础资产数量） */
+ public Builder contractMultiplier(BigDecimal contractMultiplier) { this.contractMultiplier = contractMultiplier; return this; }
+ /** 设置未实现盈亏计价模式 */
+ public Builder unrealizedPnlPriceMode(PnLPriceMode mode) { this.unrealizedPnlPriceMode = mode; return this; }
public GateConfig build() {
return new GateConfig(this);
--
Gitblit v1.9.1