功能说明

解决了 wx-pay 无法灵活支持一个商户号对应多个小程序 appId 的问题。

问题分析

当前限制:

• wx-pay 使用 mchId + "_" + appId 作为配置的唯一标识
• 一个商户号绑定多个小程序时,需要为每个小程序单独配置完整信息(冗余)
• 必须通过 switchover(mchId, appId) 精确切换,不够灵活

业务场景:

• 一个商家有多个小程序(主店、分店、活动小程序等)
• 所有小程序共用同一个支付商户号
• 支付配置(商户号、密钥、证书等)完全相同,只有 appId 不同

解决方案

采用向后兼容的增强方案,支持仅通过商户号(mchId)进行配置切换。

主要改动

1. 新增 API 方法(WxPayService.java)

• boolean switchover(String mchId) - 仅使用商户号切换配置
• WxPayService switchoverTo(String mchId) - 仅使用商户号切换(支持链式调用)

2. 实现配置查找逻辑(BaseWxPayServiceImpl.java)

• 添加参数校验:null 或空字符串会返回 false 或抛出异常
• 先尝试精确匹配商户号
• 再尝试前缀匹配 mchId_*
• 返回找到的第一个配置(注意:HashMap 迭代顺序不确定)

3. 改进文档注释

• 明确说明找不到配置时的返回行为
• 说明由于 HashMap 迭代顺序不确定,多个匹配项时返回结果不可预测
• 添加 @throws 标签说明异常情况
• 建议使用精确匹配以获得确定性行为

4. 增强测试用例

• 添加 null/空字符串参数的测试
• 添加商户号包含关系的场景测试(如 "123" 和 "1234")
• 验证前缀匹配不会错误匹配

5. 保持向后兼容

• ✅ 原有的 switchover(mchId, appId) 方法保持不变
• ✅ 原有的配置方式继续有效
• ✅ 所有现有代码无需修改

代码审查反馈已处理

• 添加参数校验(null/空字符串检查)
• 改进 Javadoc 注释,说明不确定性行为
• 添加 @throws 标签
• 增加边界测试用例
• 测试商户号包含关系场景

使用示例

配置多个 appId:

WxPayService payService = new WxPayServiceImpl();
String mchId = "1234567890";
// 配置3个不同的小程序
Map<String, WxPayConfig> configMap = new HashMap<>();
configMap.put(mchId + "_wx111111", config1);
configMap.put(mchId + "_wx222222", config2);
configMap.put(mchId + "_wx333333", config3);
payService.setMultiConfig(configMap);

方式1:精确切换(推荐,确定性行为)

payService.switchover("1234567890", "wx111111");

方式2:仅商户号切换(新功能,注意不确定性)

payService.switchover("1234567890"); // 自动匹配该商户号的某个配置

方式3:链式调用

WxPayUnifiedOrderResult result = payService
 .switchoverTo("1234567890")
 .unifiedOrder(request);

测试验证

• ✅ 创建了完整的单元测试(MultiAppIdSwitchoverTest.java)
• ✅ 新增边界测试用例:null/空参数、商户号包含关系
• ✅ 通过 checkstyle 代码风格检查
• ✅ 完整编译验证通过
• ✅ 测试场景覆盖:
  • 精确匹配切换(原有功能)
  • 仅使用 mchId 切换(新功能)
  • switchoverTo 链式调用
  • 切换到不存在的配置
  • 动态添加/移除配置
  • 单配置场景兼容性
  • null/空字符串参数处理
  • 商户号包含关系场景

文档

详细使用文档:weixin-java-pay/MULTI_APPID_USAGE.md

包含:

• 功能背景说明
• 配置方式示例
• 三种切换方式的使用说明
• 实际应用场景代码示例
• 注意事项和最佳实践(包括不确定性说明)
• API 参考表格

检查清单

• 代码实现完成
• 添加了单元测试
• 通过 checkstyle 检查
• 通过完整编译
• 保持向后兼容
• 添加了使用文档
• 代码注释清晰
• 处理代码审查反馈
• 添加参数校验
• 增加边界测试用例

补充说明

1. 向后兼容性:所有原有的使用方式继续有效,不需要修改现有代码
2. 线程安全:配置切换使用 WxPayConfigHolder(基于 ThreadLocal),是线程安全的
3. 推荐实践:
   • 建议使用精确切换方式(同时指定商户号和 appId),以获得确定性行为
   • 仅商户号切换时,由于 HashMap 迭代顺序不确定,返回的配置可能不稳定
   • 如果使用仅商户号切换,确保该商户号下至少有一个可用的配置

Custom agent used: 全部用中文
需要用中文,包括PR标题和分析总结过程

• Fixes wx-pay 只能配置一个appid,无法应对绑定多个小程序的场景 #3556

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.