📝 添加微信开放平台小程序审核额度管理指南

weixin-java-open/src/main/java/me/chanjar/weixin/open/api/WxOpenMaService.java

@@ -539,10 +539,36 @@ public interface WxOpenMaService extends WxMaService {
 
   /**
    * 将第三方提交的代码包提交审核（仅供第三方开发者代小程序调用）
+   * <p>
+   * <b>重要提示：审核额度限制</b>
+   * </p>
+   * <ul>
+   *   <li>每个第三方平台账号每月有审核额度限制（默认20次，可通过 {@link #queryQuota()} 查询）</li>
+   *   <li>每次调用 submitAudit 提交一个小程序审核时，会消耗1个审核额度</li>
+   *   <li>建议在提交审核前，先调用 {@link #queryQuota()} 检查剩余额度</li>
+   *   <li>如需增加额度，请联系微信开放平台客服</li>
+   * </ul>
+   * <p>
+   * <b>最佳实践：</b>
+   * </p>
+   * <pre>{@code
+   * // 1. 先查询剩余额度
+   * WxOpenMaQueryQuotaResult quota = wxOpenMaService.queryQuota();
+   * if (quota.getRest() <= 0) {
+   *   throw new RuntimeException("审核额度不足，剩余：" + quota.getRest());
+   * }
+   *
+   * // 2. 提交审核
+   * WxOpenMaSubmitAuditMessage message = new WxOpenMaSubmitAuditMessage();
+   * message.setItemList(itemList);
+   * WxOpenMaSubmitAuditResult result = wxOpenMaService.submitAudit(message);
+   * }</pre>
    *
    * @param submitAuditMessage the submit audit message
    * @return the wx open ma submit audit result
    * @throws WxErrorException the wx error exception
+   * @see #queryQuota() 查询审核额度
+   * @see #speedAudit(Long) 加急审核
    */
   WxOpenMaSubmitAuditResult submitAudit(WxOpenMaSubmitAuditMessage submitAuditMessage) throws WxErrorException;
 
@@ -690,11 +716,43 @@ public interface WxOpenMaService extends WxMaService {
   WxOpenMaGetCodePrivacyInfoResult getCodePrivacyInfo() throws WxErrorException;
 
   /**
-   * 查询服务商的当月提审限额和加急次数（Quota）
-   * https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/Mini_Programs/code/query_quota.html
+   * 查询服务商的当月提交审核限额和加急次数（Quota）
+   * <p>
+   * 文档地址：
+   * <a href="https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/Mini_Programs/code/query_quota.html">查询额度</a>
+   * </p>
+   * <p>
+   * <b>返回字段说明：</b>
+   * </p>
+   * <ul>
+   *   <li>rest: 当月剩余提交审核次数</li>
+   *   <li>limit: 当月提交审核额度上限（默认20次）</li>
+   *   <li>speedup_rest: 剩余加急次数</li>
+   *   <li>speedup_limit: 加急额度上限</li>
+   * </ul>
+   * <p>
+   * <b>重要说明：</b>
+   * </p>
+   * <ul>
+   *   <li>每个第三方平台账号每月初会重置审核额度</li>
+   *   <li>每次调用 {@link #submitAudit} 提交审核会消耗1个额度</li>
+   *   <li>审核撤回不会返还额度</li>
+   *   <li>建议在批量提交审核前，先调用此接口检查额度是否充足</li>
+   * </ul>
+   * <p>
+   * <b>使用示例：</b>
+   * </p>
+   * <pre>{@code
+   * WxOpenMaQueryQuotaResult quota = wxOpenMaService.queryQuota();
+   * System.out.println("剩余审核次数：" + quota.getRest());
+   * System.out.println("审核额度上限：" + quota.getLimit());
+   * System.out.println("剩余加急次数：" + quota.getSpeedupRest());
+   * }</pre>
    *
-   * @return the wx open ma query quota result
-   * @throws WxErrorException the wx error exception
+   * @return 审核额度信息
+   * @throws WxErrorException 调用微信接口失败时抛出
+   * @see #submitAudit(WxOpenMaSubmitAuditMessage) 提交审核
+   * @see #speedAudit(Long) 加急审核
    */
   WxOpenMaQueryQuotaResult queryQuota() throws WxErrorException;
 

weixin-java-open/src/main/java/me/chanjar/weixin/open/bean/message/WxOpenMaSubmitAuditMessage.java

@@ -10,8 +10,39 @@ import java.util.List;
 
 /**
  * 微信小程序代码包提交审核(仅供第三方开发者代小程序调用)
+ * <p>
+ * <b>重要提示：审核额度限制</b>
+ * </p>
+ * <ul>
+ *   <li>每个第三方平台账号每月有审核额度限制（默认20次）</li>
+ *   <li>每次调用 submitAudit 提交审核会消耗1个额度，无论审核是否通过</li>
+ *   <li>建议在提交前先调用 queryQuota 检查剩余额度</li>
+ * </ul>
+ * <p>
+ * <b>使用示例：</b>
+ * </p>
+ * <pre>{@code
+ * // 1. 构建审核项
+ * WxMaCodeSubmitAuditItem item = new WxMaCodeSubmitAuditItem();
+ * item.setAddress("index");
+ * item.setTag("游戏");
+ * item.setFirstClass("游戏");
+ * item.setSecondClass("休闲游戏");
+ * item.setTitle("首页");
+ *
+ * // 2. 构建提交审核消息
+ * WxOpenMaSubmitAuditMessage message = new WxOpenMaSubmitAuditMessage();
+ * message.setItemList(Collections.singletonList(item));
+ * message.setVersionDesc("版本描述");
+ *
+ * // 3. 提交审核
+ * WxOpenMaSubmitAuditResult result = wxOpenMaService.submitAudit(message);
+ * System.out.println("审核ID: " + result.getAuditId());
+ * }</pre>
  *
  * @author yqx
+ * @see me.chanjar.weixin.open.api.WxOpenMaService#submitAudit(WxOpenMaSubmitAuditMessage)
+ * @see me.chanjar.weixin.open.api.WxOpenMaService#queryQuota()
  * created on  2018/9/13
  */
 @Data

weixin-java-open/src/main/java/me/chanjar/weixin/open/bean/result/WxOpenMaQueryQuotaResult.java

@@ -6,7 +6,31 @@ import lombok.EqualsAndHashCode;
 import me.chanjar.weixin.open.util.json.WxOpenGsonBuilder;
 
 /**
- * 微信开放平台小程序当前分阶段发布详情
+ * 微信开放平台小程序提交审核额度查询结果
+ * <p>
+ * 用于查询第三方平台服务商的当月提交审核限额和加急次数
+ * </p>
+ * <p>
+ * <b>字段说明：</b>
+ * </p>
+ * <ul>
+ *   <li>rest: 当月剩余提交审核次数</li>
+ *   <li>limit: 当月提交审核额度上限（默认20次，可联系微信开放平台增加）</li>
+ *   <li>speedupRest: 剩余加急次数</li>
+ *   <li>speedupLimit: 加急额度上限</li>
+ * </ul>
+ * <p>
+ * <b>重要提示：</b>
+ * </p>
+ * <ul>
+ *   <li>每次调用 submitAudit 提交小程序审核，会消耗1个审核额度</li>
+ *   <li>额度每月初自动重置</li>
+ *   <li>审核撤回不会返还已消耗的额度</li>
+ *   <li>建议在批量提交审核前，先检查剩余额度是否充足</li>
+ * </ul>
+ *
+ * @see me.chanjar.weixin.open.api.WxOpenMaService#queryQuota()
+ * @see me.chanjar.weixin.open.api.WxOpenMaService#submitAudit(me.chanjar.weixin.open.bean.message.WxOpenMaSubmitAuditMessage)
  */
 @Data
 @EqualsAndHashCode(callSuper = true)
@@ -14,15 +38,27 @@ public class WxOpenMaQueryQuotaResult extends WxOpenResult {
 
   private static final long serialVersionUID = 5915265985261653007L;
 
+  /**
+   * 当月剩余提交审核次数
+   */
   @SerializedName("rest")
   private Integer rest;
 
+  /**
+   * 当月提交审核额度上限
+   */
   @SerializedName("limit")
   private Integer limit;
 
+  /**
+   * 剩余加急次数
+   */
   @SerializedName("speedup_rest")
   private Integer speedupRest;
 
+  /**
+   * 加急额度上限
+   */
   @SerializedName("speedup_limit")
   private Integer speedupLimit;
 

weixin-java-open/src/test/java/me/chanjar/weixin/open/api/impl/WxOpenMaServiceImplTest.java

@@ -306,6 +306,141 @@ public class WxOpenMaServiceImplTest {
 
   @Test
   public void testQueryQuota() {
+    // 此测试方法演示如何使用审核额度查询功能
+    // 注意：实际运行需要真实的微信 API 凭据
+    /*
+    try {
+      // 查询当前审核额度
+      WxOpenMaQueryQuotaResult quota = wxOpenMaService.queryQuota();
+
+      System.out.println("审核额度信息：");
+      System.out.println("  当月剩余提交审核次数: " + quota.getRest());
+      System.out.println("  当月提交审核额度上限: " + quota.getLimit());
+      System.out.println("  剩余加急次数: " + quota.getSpeedupRest());
+      System.out.println("  加急额度上限: " + quota.getSpeedupLimit());
+
+      // 检查额度是否充足
+      if (quota.getRest() <= 0) {
+        System.err.println("警告：审核额度已用尽！");
+      } else if (quota.getRest() <= 5) {
+        System.out.println("提示：审核额度即将用尽，请注意！");
+      }
+    } catch (WxErrorException e) {
+      e.printStackTrace();
+    }
+    */
+  }
+
+  /**
+   * 演示提交审核前检查额度的最佳实践
+   * <p>
+   * 这是一个完整的示例，展示如何在提交审核前检查额度，避免额度不足导致的失败
+   * </p>
+   */
+  @Test
+  public void testSubmitAuditWithQuotaCheck() {
+    // 此测试方法演示提交审核前的额度检查最佳实践
+    // 注意：实际运行需要真实的微信 API 凭据
+    /*
+    try {
+      // 步骤1：检查审核额度
+      WxOpenMaQueryQuotaResult quota = wxOpenMaService.queryQuota();
+      System.out.println("当前剩余审核额度: " + quota.getRest());
+
+      if (quota.getRest() <= 0) {
+        throw new RuntimeException("审核额度不足，无法提交审核。剩余额度: " + quota.getRest());
+      }
+
+      // 步骤2：准备审核数据
+      WxMaCodeSubmitAuditItem item = new WxMaCodeSubmitAuditItem();
+      item.setAddress("index");
+      item.setTag("工具");
+      item.setFirstClass("工具");
+      item.setSecondClass("效率");
+      item.setTitle("首页");
+
+      WxOpenMaSubmitAuditMessage message = new WxOpenMaSubmitAuditMessage();
+      message.setItemList(Collections.singletonList(item));
+      message.setVersionDesc("修复若干已知问题，优化用户体验");
+
+      // 步骤3：提交审核
+      WxOpenMaSubmitAuditResult result = wxOpenMaService.submitAudit(message);
+      System.out.println("提交审核成功，审核ID: " + result.getAuditId());
+
+      // 步骤4：再次查询额度，确认已消耗
+      quota = wxOpenMaService.queryQuota();
+      System.out.println("提交后剩余审核额度: " + quota.getRest());
+
+    } catch (WxErrorException e) {
+      System.err.println("提交审核失败: " + e.getMessage());
+      e.printStackTrace();
+    }
+    */
+  }
+
+  /**
+   * 演示批量提交审核时的额度管理策略
+   * <p>
+   * 当需要为多个小程序提交审核时，应该先统一检查额度是否充足
+   * </p>
+   */
+  @Test
+  public void testBatchSubmitAuditWithQuotaManagement() {
+    // 此测试方法演示批量提交审核时的额度管理策略
+    // 注意：实际运行需要真实的微信 API 凭据，以及 WxOpenComponentService 实例
+    /*
+    // 假设已经初始化了 wxOpenComponentService
+    // WxOpenComponentService wxOpenComponentService = ...;
+
+    try {
+      // 假设需要为多个小程序提交审核
+      List<String> appIds = Arrays.asList("appid1", "appid2", "appid3");
+
+      // 步骤1：通过任意一个小程序服务查询总体额度
+      // 注意：审核额度是第三方平台级别的，所有授权小程序共享
+      WxOpenMaService firstMaService = wxOpenComponentService.getWxMaServiceByAppid(appIds.get(0));
+      WxOpenMaQueryQuotaResult quota = firstMaService.queryQuota();
+      System.out.println("当前剩余审核额度: " + quota.getRest());
+
+      if (quota.getRest() < appIds.size()) {
+        System.err.println("警告：审核额度不足！");
+        System.err.println("  需要提交: " + appIds.size() + " 个");
+        System.err.println("  剩余额度: " + quota.getRest());
+        System.err.println("  缺少额度: " + (appIds.size() - quota.getRest()));
+        return;
+      }
+
+      // 步骤2：依次提交审核
+      int successCount = 0;
+      for (String appId : appIds) {
+        try {
+          WxOpenMaService maService = wxOpenComponentService.getWxMaServiceByAppid(appId);
+
+          WxOpenMaSubmitAuditMessage message = new WxOpenMaSubmitAuditMessage();
+          // ... 设置审核信息
+
+          WxOpenMaSubmitAuditResult result = maService.submitAudit(message);
+          System.out.println("AppId: " + appId + " 提交成功，审核ID: " + result.getAuditId());
+          successCount++;
+
+        } catch (WxErrorException e) {
+          System.err.println("AppId: " + appId + " 提交失败: " + e.getMessage());
+        }
+      }
+
+      // 步骤3：输出统计信息
+      System.out.println("批量提交完成：");
+      System.out.println("  成功: " + successCount);
+      System.out.println("  失败: " + (appIds.size() - successCount));
+
+      // 步骤4：查询剩余额度
+      quota = firstMaService.queryQuota();
+      System.out.println("  剩余额度: " + quota.getRest());
+
+    } catch (Exception e) {
+      e.printStackTrace();
+    }
+    */
   }
 
   @Test