Skip to content

Commit dccb214

Browse files
Copilotbinarywang
Copilot
and
binarywang
committed
增强文档：添加小程序审核额度管理说明和最佳实践
Co-authored-by: binarywang <[email protected]>
1 parent 65c9aa2 commit dccb214

File tree

6 files changed

+602
-5
lines changed

6 files changed

+602
-5
lines changed

‎weixin-java-open/README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,36 @@
3131

3232
---
3333

34+
## 重要提示：小程序审核额度限制
35+
36+
**在使用第三方平台代小程序提交审核时，请注意以下限制：**
37+
38+
### 审核额度说明
39+
40+
- **默认额度**: 每个第三方平台账号每月默认有 **20 个** 审核额度
41+
- **消耗规则**: 每次调用 `submitAudit()` 提交一个小程序审核，会消耗 **1 个** 审核额度
42+
- **重置周期**: 额度每月初自动重置
43+
- **额度查询**: 使用 `queryQuota()` 方法查询剩余额度
44+
45+
### 最佳实践
46+
47+
```java
48+
// 1. 先查询剩余额度
49+
WxOpenMaQueryQuotaResult quota = wxOpenMaService.queryQuota();
50+
if (quota.getRest() <= 0) {
51+
throw new RuntimeException("审核额度不足，剩余：" + quota.getRest());
52+
}
53+
54+
// 2. 提交审核
55+
WxOpenMaSubmitAuditMessage message = new WxOpenMaSubmitAuditMessage();
56+
message.setItemList(itemList);
57+
WxOpenMaSubmitAuditResult result = wxOpenMaService.submitAudit(message);
58+
```
59+
60+
**详细说明**: 请参考 [审核额度管理最佳实践.md](审核额度管理最佳实践.md)
61+
62+
---
63+
3464
## 代码示例
3565

3666
消息机制未实现，下面为通知回调中设置的代码部分

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

Lines changed: 62 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -539,10 +539,36 @@ WxOpenMaDomainResult modifyDomainDirectly(String action, List<String> requestDom
539539

540540
/**
541541
* 将第三方提交的代码包提交审核（仅供第三方开发者代小程序调用）
542+
* <p>
543+
* <b>重要提示：审核额度限制</b>
544+
* </p>
545+
* <ul>
546+
* <li>每个第三方平台账号每月有审核额度限制（默认20次，可通过 {@link #queryQuota()} 查询）</li>
547+
* <li>每次调用 submitAudit 提交一个小程序审核时，会消耗1个审核额度</li>
548+
* <li>建议在提交审核前，先调用 {@link #queryQuota()} 检查剩余额度</li>
549+
* <li>如需增加额度，请联系微信开放平台客服</li>
550+
* </ul>
551+
* <p>
552+
* <b>最佳实践：</b>
553+
* </p>
554+
* <pre>{@code
555+
* // 1. 先查询剩余额度
556+
* WxOpenMaQueryQuotaResult quota = wxOpenMaService.queryQuota();
557+
* if (quota.getRest() <= 0) {
558+
* throw new RuntimeException("审核额度不足，剩余：" + quota.getRest());
559+
* }
560+
*
561+
* // 2. 提交审核
562+
* WxOpenMaSubmitAuditMessage message = new WxOpenMaSubmitAuditMessage();
563+
* message.setItemList(itemList);
564+
* WxOpenMaSubmitAuditResult result = wxOpenMaService.submitAudit(message);
565+
* }</pre>
542566
*
543567
* @param submitAuditMessage the submit audit message
544568
* @return the wx open ma submit audit result
545569
* @throws WxErrorException the wx error exception
570+
* @see #queryQuota() 查询审核额度
571+
* @see #speedAudit(Long) 加急审核
546572
*/
547573
WxOpenMaSubmitAuditResult submitAudit(WxOpenMaSubmitAuditMessage submitAuditMessage) throws WxErrorException;
548574

@@ -691,10 +717,42 @@ WxOpenMaDomainResult modifyDomainDirectly(String action, List<String> requestDom
691717

692718
/**
693719
* 查询服务商的当月提审限额和加急次数（Quota）
694-
* https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/Mini_Programs/code/query_quota.html
695-
*
696-
* @return the wx open ma query quota result
697-
* @throws WxErrorException the wx error exception
720+
* <p>
721+
* 文档地址：
722+
* <a href="https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/Mini_Programs/code/query_quota.html">查询额度</a>
723+
* </p>
724+
* <p>
725+
* <b>返回字段说明：</b>
726+
* </p>
727+
* <ul>
728+
* <li>rest: 当月剩余提审次数</li>
729+
* <li>limit: 当月提审额度上限（默认20次）</li>
730+
* <li>speedup_rest: 剩余加急次数</li>
731+
* <li>speedup_limit: 加急额度上限</li>
732+
* </ul>
733+
* <p>
734+
* <b>重要说明：</b>
735+
* </p>
736+
* <ul>
737+
* <li>每个第三方平台账号每月初会重置审核额度</li>
738+
* <li>每次调用 {@link #submitAudit} 提交审核会消耗1个额度</li>
739+
* <li>审核撤回不会返还额度</li>
740+
* <li>建议在批量提交审核前，先调用此接口检查额度是否充足</li>
741+
* </ul>
742+
* <p>
743+
* <b>使用示例：</b>
744+
* </p>
745+
* <pre>{@code
746+
* WxOpenMaQueryQuotaResult quota = wxOpenMaService.queryQuota();
747+
* System.out.println("剩余审核次数：" + quota.getRest());
748+
* System.out.println("审核额度上限：" + quota.getLimit());
749+
* System.out.println("剩余加急次数：" + quota.getSpeedupRest());
750+
* }</pre>
751+
*
752+
* @return 审核额度信息
753+
* @throws WxErrorException 调用微信接口失败时抛出
754+
* @see #submitAudit(WxOpenMaSubmitAuditMessage) 提交审核
755+
* @see #speedAudit(Long) 加急审核
698756
*/
699757
WxOpenMaQueryQuotaResult queryQuota() throws WxErrorException;
700758

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,39 @@
1010

1111
/**
1212
* 微信小程序代码包提交审核(仅供第三方开发者代小程序调用)
13+
* <p>
14+
* <b>重要提示：审核额度限制</b>
15+
* </p>
16+
* <ul>
17+
* <li>每个第三方平台账号每月有审核额度限制（默认20次）</li>
18+
* <li>每次调用 submitAudit 提交审核会消耗1个额度，无论审核是否通过</li>
19+
* <li>建议在提交前先调用 queryQuota 检查剩余额度</li>
20+
* </ul>
21+
* <p>
22+
* <b>使用示例：</b>
23+
* </p>
24+
* <pre>{@code
25+
* // 1. 构建审核项
26+
* WxMaCodeSubmitAuditItem item = new WxMaCodeSubmitAuditItem();
27+
* item.setAddress("index");
28+
* item.setTag("游戏");
29+
* item.setFirstClass("游戏");
30+
* item.setSecondClass("休闲游戏");
31+
* item.setTitle("首页");
32+
*
33+
* // 2. 构建提审消息
34+
* WxOpenMaSubmitAuditMessage message = new WxOpenMaSubmitAuditMessage();
35+
* message.setItemList(Collections.singletonList(item));
36+
* message.setVersionDesc("版本描述");
37+
*
38+
* // 3. 提交审核
39+
* WxOpenMaSubmitAuditResult result = wxOpenMaService.submitAudit(message);
40+
* System.out.println("审核ID: " + result.getAuditId());
41+
* }</pre>
1342
*
1443
* @author yqx
44+
* @see me.chanjar.weixin.open.api.WxOpenMaService#submitAudit(WxOpenMaSubmitAuditMessage)
45+
* @see me.chanjar.weixin.open.api.WxOpenMaService#queryQuota()
1546
* created on 2018/9/13
1647
*/
1748
@Data

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

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,59 @@
66
import me.chanjar.weixin.open.util.json.WxOpenGsonBuilder;
77

88
/**
9-
* 微信开放平台小程序当前分阶段发布详情
9+
* 微信开放平台小程序提审额度查询结果
10+
* <p>
11+
* 用于查询第三方平台服务商的当月提审限额和加急次数
12+
* </p>
13+
* <p>
14+
* <b>字段说明：</b>
15+
* </p>
16+
* <ul>
17+
* <li>rest: 当月剩余提审次数</li>
18+
* <li>limit: 当月提审额度上限（默认20次，可联系微信开放平台增加）</li>
19+
* <li>speedupRest: 剩余加急次数</li>
20+
* <li>speedupLimit: 加急额度上限</li>
21+
* </ul>
22+
* <p>
23+
* <b>重要提示：</b>
24+
* </p>
25+
* <ul>
26+
* <li>每次调用 submitAudit 提交小程序审核，会消耗1个审核额度</li>
27+
* <li>额度每月初自动重置</li>
28+
* <li>审核撤回不会返还已消耗的额度</li>
29+
* <li>建议在批量提交审核前，先检查剩余额度是否充足</li>
30+
* </ul>
31+
*
32+
* @see me.chanjar.weixin.open.api.WxOpenMaService#queryQuota()
33+
* @see me.chanjar.weixin.open.api.WxOpenMaService#submitAudit(me.chanjar.weixin.open.bean.message.WxOpenMaSubmitAuditMessage)
1034
*/
1135
@Data
1236
@EqualsAndHashCode(callSuper = true)
1337
public class WxOpenMaQueryQuotaResult extends WxOpenResult {
1438

1539
private static final long serialVersionUID = 5915265985261653007L;
1640

41+
/**
42+
* 当月剩余提审次数
43+
*/
1744
@SerializedName("rest")
1845
private Integer rest;
1946

47+
/**
48+
* 当月提审额度上限
49+
*/
2050
@SerializedName("limit")
2151
private Integer limit;
2252

53+
/**
54+
* 剩余加急次数
55+
*/
2356
@SerializedName("speedup_rest")
2457
private Integer speedupRest;
2558

59+
/**
60+
* 加急额度上限
61+
*/
2662
@SerializedName("speedup_limit")
2763
private Integer speedupLimit;
2864

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

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -306,6 +306,136 @@ public void testGetGrayReleasePlan() {
306306

307307
@Test
308308
public void testQueryQuota() {
309+
// 此测试方法演示如何使用审核额度查询功能
310+
// 注意：实际运行需要真实的微信 API 凭据
311+
/*
312+
try {
313+
// 查询当前审核额度
314+
WxOpenMaQueryQuotaResult quota = wxOpenMaService.queryQuota();
315+
316+
System.out.println("审核额度信息：");
317+
System.out.println(" 当月剩余提审次数: " + quota.getRest());
318+
System.out.println(" 当月提审额度上限: " + quota.getLimit());
319+
System.out.println(" 剩余加急次数: " + quota.getSpeedupRest());
320+
System.out.println(" 加急额度上限: " + quota.getSpeedupLimit());
321+
322+
// 检查额度是否充足
323+
if (quota.getRest() <= 0) {
324+
System.err.println("警告：审核额度已用尽！");
325+
} else if (quota.getRest() <= 5) {
326+
System.out.println("提示：审核额度即将用尽，请注意！");
327+
}
328+
} catch (WxErrorException e) {
329+
e.printStackTrace();
330+
}
331+
*/
332+
}
333+
334+
/**
335+
* 演示提交审核前检查额度的最佳实践
336+
* <p>
337+
* 这是一个完整的示例，展示如何在提交审核前检查额度，避免额度不足导致的失败
338+
* </p>
339+
*/
340+
@Test
341+
public void testSubmitAuditWithQuotaCheck() {
342+
// 此测试方法演示提交审核前的额度检查最佳实践
343+
// 注意：实际运行需要真实的微信 API 凭据
344+
/*
345+
try {
346+
// 步骤1：检查审核额度
347+
WxOpenMaQueryQuotaResult quota = wxOpenMaService.queryQuota();
348+
System.out.println("当前剩余审核额度: " + quota.getRest());
349+
350+
if (quota.getRest() <= 0) {
351+
throw new RuntimeException("审核额度不足，无法提交审核。剩余额度: " + quota.getRest());
352+
}
353+
354+
// 步骤2：准备审核数据
355+
WxMaCodeSubmitAuditItem item = new WxMaCodeSubmitAuditItem();
356+
item.setAddress("index");
357+
item.setTag("工具");
358+
item.setFirstClass("工具");
359+
item.setSecondClass("效率");
360+
item.setTitle("首页");
361+
362+
WxOpenMaSubmitAuditMessage message = new WxOpenMaSubmitAuditMessage();
363+
message.setItemList(Collections.singletonList(item));
364+
message.setVersionDesc("修复若干已知问题，优化用户体验");
365+
366+
// 步骤3：提交审核
367+
WxOpenMaSubmitAuditResult result = wxOpenMaService.submitAudit(message);
368+
System.out.println("提交审核成功，审核ID: " + result.getAuditId());
369+
370+
// 步骤4：再次查询额度，确认已消耗
371+
quota = wxOpenMaService.queryQuota();
372+
System.out.println("提交后剩余审核额度: " + quota.getRest());
373+
374+
} catch (WxErrorException e) {
375+
System.err.println("提交审核失败: " + e.getMessage());
376+
e.printStackTrace();
377+
}
378+
*/
379+
}
380+
381+
/**
382+
* 演示批量提交审核时的额度管理策略
383+
* <p>
384+
* 当需要为多个小程序提交审核时，应该先统一检查额度是否充足
385+
* </p>
386+
*/
387+
@Test
388+
public void testBatchSubmitAuditWithQuotaManagement() {
389+
// 此测试方法演示批量提交审核时的额度管理策略
390+
// 注意：实际运行需要真实的微信 API 凭据
391+
/*
392+
try {
393+
// 假设需要为多个小程序提交审核
394+
List<String> appIds = Arrays.asList("appid1", "appid2", "appid3");
395+
396+
// 步骤1：检查总体额度是否充足
397+
WxOpenMaQueryQuotaResult quota = wxOpenComponentService.queryQuota();
398+
System.out.println("当前剩余审核额度: " + quota.getRest());
399+
400+
if (quota.getRest() < appIds.size()) {
401+
System.err.println("警告：审核额度不足！");
402+
System.err.println(" 需要提交: " + appIds.size() + " 个");
403+
System.err.println(" 剩余额度: " + quota.getRest());
404+
System.err.println(" 缺少额度: " + (appIds.size() - quota.getRest()));
405+
return;
406+
}
407+
408+
// 步骤2：依次提交审核
409+
int successCount = 0;
410+
for (String appId : appIds) {
411+
try {
412+
WxOpenMaService maService = wxOpenComponentService.getWxMaServiceByAppid(appId);
413+
414+
WxOpenMaSubmitAuditMessage message = new WxOpenMaSubmitAuditMessage();
415+
// ... 设置审核信息
416+
417+
WxOpenMaSubmitAuditResult result = maService.submitAudit(message);
418+
System.out.println("AppId: " + appId + " 提交成功，审核ID: " + result.getAuditId());
419+
successCount++;
420+
421+
} catch (WxErrorException e) {
422+
System.err.println("AppId: " + appId + " 提交失败: " + e.getMessage());
423+
}
424+
}
425+
426+
// 步骤3：输出统计信息
427+
System.out.println("批量提交完成：");
428+
System.out.println(" 成功: " + successCount);
429+
System.out.println(" 失败: " + (appIds.size() - successCount));
430+
431+
// 步骤4：查询剩余额度
432+
quota = wxOpenComponentService.queryQuota();
433+
System.out.println(" 剩余额度: " + quota.getRest());
434+
435+
} catch (Exception e) {
436+
e.printStackTrace();
437+
}
438+
*/
309439
}
310440

311441
@Test

0 commit comments

Comments
 (0)