WxJava 微信支付多商户配置实战:wx-java-pay-multi-spring-boot-starter 从入门到源码解析
WxJava 微信支付多商户配置实战:wx-java-pay-multi-spring-boot-starter 从入门到源码解析
本指南面向需要在单个 Spring Boot 应用中同时对接多个公众号/商户号微信支付能力的开发者,基于 WxJava 仓库中的 wx-java-pay-multi-spring-boot-starter 展开。你将掌握如何通过一份 application.yml 声明多个支付配置、按 appId 或自定义标识动态获取对应的 WxPayService、完成 V2/V3/服务商三种模式的统一下单、查单与退款,并理解其背后基于 ConcurrentHashMap 的线程安全懒加载实现原理。
一、这个 Starter 解决什么问题
在常规的 wx-java-pay-spring-boot-starter 中,一个应用通常只绑定一套微信支付配置。而多商户接入场景(一个服务商为多个公众号提供支付服务、一个系统承载多个公众号的支付业务、需要根据不同的 appId 动态切换支付配置)则要求系统能在运行时按需选择支付实例。
wx-java-pay-multi-spring-boot-starter 正是为此设计的:它把一组 WxPayService 实例集中管理起来,通过配置文件中定义的 key(可以是 appId,也可以是自定义标识)来区分并获取对应的服务实例,实现"一套代码、多商户共用"。
从源码结构看,该模块只包含 5 个核心类,职责非常清晰:
| 类 | 作用 | 路径 |
|---|---|---|
WxPayMultiAutoConfiguration |
Spring Boot 自动装配入口 | WxPayMultiAutoConfiguration.java |
WxPayMultiProperties |
顶层配置属性(前缀 wx.pay) |
WxPayMultiProperties.java |
WxPaySingleProperties |
单商户配置属性 | WxPaySingleProperties.java |
WxPayMultiServices |
多服务管理接口 | WxPayMultiServices.java |
WxPayMultiServicesImpl |
多服务管理实现(懒加载 + 缓存) | WxPayMultiServicesImpl.java |
二、快速开始:引入依赖
在 pom.xml 中添加依赖(该模块直接依赖 weixin-java-pay,版本由父 POM 统一管理):
<dependency>
<groupId>com.github.binarywang</groupId>
<artifactId>wx-java-pay-multi-spring-boot-starter</artifactId>
<version>${version}</version>
</dependency>
在实际项目中 version 应替换为当前 WxJava 发布版本号(例如仓库中父 POM 使用的 4.8.6.B),建议通过 BOM 或父 POM 的 dependencyManagement 统一管理,避免手工维护版本。
三、多商户配置:application.yml 三种写法
所有配置都挂在 wx.pay.configs 之下,其中每个子键(如 wx1234567890abcdef、config2)就是后续代码里使用的配置标识(configKey)。
3.1 V2 版本配置
wx:
pay:
configs:
# 配置1 - 可以使用appId作为key
wx1234567890abcdef:
appId: wx1234567890abcdef
mchId: 1234567890
mchKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
keyPath: classpath:cert/app1/apiclient_cert.p12
notifyUrl: https://example.com/pay/notify
# 配置2 - 也可以使用自定义标识作为key
config2:
appId: wx9876543210fedcba
mchId: 9876543210
mchKey: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
keyPath: classpath:cert/app2/apiclient_cert.p12
notifyUrl: https://example.com/pay/notify
3.2 V3 版本配置
wx:
pay:
configs:
# 公众号1配置
wx1234567890abcdef:
appId: wx1234567890abcdef
mchId: 1234567890
apiV3Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
certSerialNo: 62C6CEAA360BCxxxxxxxxxxxxxxx
privateKeyPath: classpath:cert/app1/apiclient_key.pem
privateCertPath: classpath:cert/app1/apiclient_cert.pem
notifyUrl: https://example.com/pay/notify
# 公众号2配置
wx9876543210fedcba:
appId: wx9876543210fedcba
mchId: 9876543210
apiV3Key: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
certSerialNo: 73D7DFBB471CDxxxxxxxxxxxxxxx
privateKeyPath: classpath:cert/app2/apiclient_key.pem
privateCertPath: classpath:cert/app2/apiclient_cert.pem
notifyUrl: https://example.com/pay/notify
3.3 V3 服务商版本配置
服务商模式的核心差异在于:appId / mchId 填写服务商自身的信息,subAppId / subMchId 填写子商户的信息。同一服务商可以为多个子商户提供服务,因此服务商的 appId、mchId、apiV3Key 在不同配置间可以相同,而子商户维度必须不同:
wx:
pay:
configs:
# 服务商为公众号1提供服务
config1:
appId: wxe97b2x9c2b3d # 服务商appId
mchId: 16486610 # 服务商商户号
subAppId: wx118cexxe3c07679 # 子商户公众号appId
subMchId: 16496705 # 子商户号
apiV3Key: Dc1DBwSc094jAKDGR5aqqb7PTHr
privateKeyPath: classpath:cert/apiclient_key.pem
privateCertPath: classpath:cert/apiclient_cert.pem
# 服务商为公众号2提供服务
config2:
appId: wxe97b2x9c2b3d # 服务商appId(可以相同)
mchId: 16486610 # 服务商商户号(可以相同)
subAppId: wx228dexxf4d18890 # 子商户公众号appId(不同)
subMchId: 16496706 # 子商户号(不同)
apiV3Key: Dc1DBwSc094jAKDGR5aqqb7PTHr
privateKeyPath: classpath:cert/apiclient_key.pem
privateCertPath: classpath:cert/apiclient_cert.pem
四、多商户配置:application.properties 写法
不习惯 YAML 时,properties 写法等价,注意配置键使用短横线命名法(如 app-id、mch-id、api-v3-key):
# 公众号1配置
wx.pay.configs.wx1234567890abcdef.app-id=wx1234567890abcdef
wx.pay.configs.wx1234567890abcdef.mch-id=1234567890
wx.pay.configs.wx1234567890abcdef.api-v3-key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
wx.pay.configs.wx1234567890abcdef.cert-serial-no=62C6CEAA360BCxxxxxxxxxxxxxxx
wx.pay.configs.wx1234567890abcdef.private-key-path=classpath:cert/app1/apiclient_key.pem
wx.pay.configs.wx1234567890abcdef.private-cert-path=classpath:cert/app1/apiclient_cert.pem
wx.pay.configs.wx1234567890abcdef.notify-url=https://example.com/pay/notify
# 公众号2配置
wx.pay.configs.wx9876543210fedcba.app-id=wx9876543210fedcba
wx.pay.configs.wx9876543210fedcba.mch-id=9876543210
wx.pay.configs.wx9876543210fedcba.api-v3-key=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
wx.pay.configs.wx9876543210fedcba.cert-serial-no=73D7DFBB471CDxxxxxxxxxxxxxxx
wx.pay.configs.wx9876543210fedcba.private-key-path=classpath:cert/app2/apiclient_key.pem
wx.pay.configs.wx9876543210fedcba.private-cert-path=classpath:cert/app2/apiclient_cert.pem
wx.pay.configs.wx9876543210fedcba.notify-url=https://example.com/pay/notify
配置绑定由 @ConfigurationProperties(WxPayMultiProperties.PREFIX) 完成,前缀常量定义在 WxPayMultiProperties.java 中,即 wx.pay;configs 是一个 Map<String, WxPaySingleProperties>,这正是"多个商户、按 key 区分"的模型基础。
五、代码使用:WxPayMultiServices 实战
5.1 核心 API
自动注入的类型是 WxPayMultiServices,接口定义了两个方法(见 WxPayMultiServices.java):
| 方法 | 说明 |
|---|---|
WxPayService getWxPayService(String configKey) |
按配置标识获取支付服务实例(懒加载) |
void removeWxPayService(String configKey) |
移除缓存的实例,下次获取时重新构建(可用于配置热更新) |
5.2 完整的业务示例
下面的 PayService 覆盖了按配置创建 JSAPI 订单、服务商下单、查询订单三个典型动作,仓库中的 WxPayMultiExample.java 还额外提供了退款与配置重载示例:
import com.binarywang.spring.starter.wxjava.pay.service.WxPayMultiServices;
import com.github.binarywang.wxpay.bean.request.WxPayUnifiedOrderV3Request;
import com.github.binarywang.wxpay.bean.result.WxPayOrderQueryV3Result;
import com.github.binarywang.wxpay.bean.result.WxPayUnifiedOrderV3Result;
import com.github.binarywang.wxpay.bean.result.enums.TradeTypeEnum;
import com.github.binarywang.wxpay.service.WxPayService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
@Service
public class PayService {
@Autowired
private WxPayMultiServices wxPayMultiServices;
/**
* 为不同的公众号创建支付订单
*
* @param configKey 配置标识(即 wx.pay.configs.<configKey> 中的 key,可以是 appId 或自定义标识)
*/
public void createOrder(String configKey, String openId, Integer totalFee, String body) throws Exception {
// 根据配置标识获取对应的WxPayService
WxPayService wxPayService = wxPayMultiServices.getWxPayService(configKey);
if (wxPayService == null) {
throw new IllegalArgumentException("未找到配置标识对应的微信支付配置: " + configKey);
}
// 使用WxPayService进行支付操作
WxPayUnifiedOrderV3Request request = new WxPayUnifiedOrderV3Request();
request.setOutTradeNo(generateOutTradeNo());
request.setDescription(body);
request.setAmount(new WxPayUnifiedOrderV3Request.Amount().setTotal(totalFee));
request.setPayer(new WxPayUnifiedOrderV3Request.Payer().setOpenid(openId));
request.setNotifyUrl(wxPayService.getConfig().getNotifyUrl());
// V3统一下单
WxPayUnifiedOrderV3Result.JsapiResult result =
wxPayService.createOrderV3(TradeTypeEnum.JSAPI, request);
// 返回给前端用于调起支付
// ...
}
/**
* 服务商模式示例
*/
public void serviceProviderExample(String configKey) throws Exception {
// 使用配置标识获取WxPayService
WxPayService wxPayService = wxPayMultiServices.getWxPayService(configKey);
if (wxPayService == null) {
throw new IllegalArgumentException("未找到配置: " + configKey);
}
// 获取子商户的配置信息
String subAppId = wxPayService.getConfig().getSubAppId();
String subMchId = wxPayService.getConfig().getSubMchId();
// 进行支付操作
// ...
}
/**
* 查询订单示例
*
* @param configKey 配置标识(即 wx.pay.configs.<configKey> 中的 key)
*/
public void queryOrder(String configKey, String outTradeNo) throws Exception {
WxPayService wxPayService = wxPayMultiServices.getWxPayService(configKey);
if (wxPayService == null) {
throw new IllegalArgumentException("未找到配置标识对应的微信支付配置: " + configKey);
}
// 查询订单
WxPayOrderQueryV3Result result = wxPayService.queryOrderV3(null, outTradeNo);
// 处理查询结果
// ...
}
private String generateOutTradeNo() {
// 生成商户订单号
return "ORDER_" + System.currentTimeMillis();
}
}
上述代码中用到的 createOrderV3、queryOrderV3、refundV3 等 V3 接口均定义在 WxPayService.java(分别位于该接口的第 729 行、第 486/509 行、第 933 行附近),获取到的 WxPayService 与单商户模式下用法完全一致,业务代码无需感知多商户的存在。
5.3 配置热更新(重载)
证书轮换或参数变更后,无需重启应用:先调用 removeWxPayService(configKey) 移除缓存实例,下一次 getWxPayService 会按最新配置重建:
public void reloadConfig(String configKey) {
// 移除缓存的WxPayService实例
wxPayMultiServices.removeWxPayService(configKey);
// 下次调用 getWxPayService 时会重新创建实例
WxPayService wxPayService = wxPayMultiServices.getWxPayService(configKey);
if (wxPayService != null) {
log.info("重新加载配置成功: {}", configKey);
}
}
六、配置项全解
6.1 必填配置项
| 配置项 | 说明 | 示例 |
|---|---|---|
| appId | 公众号或小程序的appId | wx1234567890abcdef |
| mchId | 商户号 | 1234567890 |
6.2 V2 版本配置项
| 配置项 | 说明 | 是否必填 |
|---|---|---|
| mchKey | 商户密钥 | 是(V2) |
| keyPath | p12证书文件路径 | 部分接口需要 |
6.3 V3 版本配置项
| 配置项 | 说明 | 是否必填 |
|---|---|---|
| apiV3Key | API V3密钥 | 是(V3) |
| certSerialNo | 证书序列号 | 是(V3) |
| privateKeyPath | apiclient_key.pem路径 | 是(V3) |
| privateCertPath | apiclient_cert.pem路径 | 是(V3) |
6.4 服务商模式配置项
| 配置项 | 说明 | 是否必填 |
|---|---|---|
| subAppId | 子商户公众号appId | 服务商模式必填 |
| subMchId | 子商户号 | 服务商模式必填 |
6.5 可选配置项
| 配置项 | 说明 | 默认值 |
|---|---|---|
| notifyUrl | 支付结果通知URL | 无 |
| refundNotifyUrl | 退款结果通知URL | 无 |
| serviceId | 微信支付分serviceId | 无 |
| payScoreNotifyUrl | 支付分回调地址 | 无 |
| payScorePermissionNotifyUrl | 支付分授权回调地址 | 无 |
| useSandboxEnv | 是否使用沙箱环境 | false |
| apiHostUrl | 自定义API主机地址 | https://api.mch.weixin.qq.com |
| apiHostUrlPath | 自定义API主机路径前缀(代理入口前缀) | 空 |
| strictlyNeedWechatPaySerial | 是否所有V3请求都添加序列号头 | true |
| fullPublicKeyModel | 是否完全使用公钥模式 | true |
| publicKeyId | 公钥ID | 无 |
| publicKeyPath | 公钥文件路径 | 无 |
说明:
WxPaySingleProperties中的所有字段定义与默认值可对照 WxPaySingleProperties.java 查看。其中几个布尔项与底层WxPayConfig(weixin-java-pay/src/main/java/com/github/binarywang/wxpay/config/WxPayConfig.java)完全对应:apiHostUrl默认值即常量DEFAULT_PAY_BASE_URL = "https://api.mch.weixin.qq.com"(该文件第 57 行);useSandboxEnv(第 259 行)、strictlyNeedWechatPaySerial(第 281 行)、fullPublicKeyModel(第 286 行)均默认开启。apiHostUrl/apiHostUrlPath常用于公司内网网关代理场景,例如配置http://proxy.company.com:8080加路径前缀/api-weixin,从 WxPayConfig.java 的 getter 可以看出,实现会对尾斜杠与路径前缀做规范化处理,并在使用自定义代理主机时将其加入 TLS 受信任列表。
七、源码级原理剖析
7.1 自动装配:何时生效、如何关闭
WxPayMultiAutoConfiguration.java 上声明了三个关键条件注解:
@EnableConfigurationProperties(WxPayMultiProperties.class):注册配置属性绑定;@ConditionalOnClass(WxPayService.class):仅当 classpath 中存在WxPayService(即已引入 weixin-java-pay)时装配;@ConditionalOnProperty(prefix = "wx.pay", value = "enabled", matchIfMissing = true):默认启用,可通过wx.pay.enabled=false显式关闭。
装配结果是一个 WxPayMultiServices Bean(仅当容器中尚无同类型 Bean 时注册,见 @ConditionalOnMissingBean),因此你也可以完全自定义实现并覆盖默认行为。
7.2 线程安全的懒加载与实例缓存
核心实现位于 WxPayMultiServicesImpl.java:
private final Map<String, WxPayService> services = new ConcurrentHashMap<>();
@Override
public WxPayService getWxPayService(String configKey) {
if (StringUtils.isBlank(configKey)) {
log.warn("配置标识为空,无法获取WxPayService");
return null;
}
// 使用 computeIfAbsent 实现线程安全的懒加载,避免使用 synchronized(this) 带来的性能问题
return services.computeIfAbsent(configKey, key -> {
WxPaySingleProperties properties = wxPayMultiProperties.getConfigs().get(key);
if (properties == null) {
log.warn("未找到配置标识为[{}]的微信支付配置", key);
return null;
}
return this.buildWxPayService(properties);
});
}
几个值得注意的设计点:
- 懒加载:
WxPayService只有在首次被getWxPayService调用时才构建,未使用的商户配置不会产生实例; - 线程安全:底层容器是
ConcurrentHashMap,computeIfAbsent保证同一 key 的构建只发生一次且对并发线程安全,注释中明确说明这是为了避免synchronized(this)的性能开销; - 空值语义:key 为空、或配置不存在时返回
null(并在日志中告警),调用方需要像上文示例那样判空; - 移除即重建:
removeWxPayService只是从 Map 中移除,不销毁实例,下一次获取会走buildWxPayService重建。
buildWxPayService(第 61~92 行)负责把 WxPaySingleProperties 逐字段拷贝到 WxPayConfig 并 new WxPayServiceImpl(),所有字符串字段都经过 StringUtils.trimToNull 清洗,避免空白字符串污染配置。
7.3 行为契约的测试佐证
仓库自带的集成测试 WxPayMultiServicesTest.java 通过 @TestPropertySource 注入了 app1 / app2 两组配置,并用断言固化了以下行为:
- 同 key 返回同一实例:
assertSame(app1Service, app1ServiceAgain),证明实例被缓存复用; - 无效 key 返回 null:
getWxPayService("nonexistent")返回assertNull; - 移除后重建新实例:
removeWxPayService("app1")后再次获取得到新实例,assertNotSame验证了热更新机制; - 配置绑定正确:验证
apiHostUrl=http://10.0.0.1:3128、apiHostUrlPath=/api-weixin等代理参数能正确透传到WxPayService.getConfig()。
这些测试既是该 Starter 的行为契约,也可以作为你理解 API 语义的最小可运行样例。
八、常见问题
8.1 如何选择配置的 key?
配置的 key(即 wx.pay.configs.<configKey> 中的 <configKey> 部分)可以自由选择:
- 使用 appId 作为 key(如
wx.pay.configs.wx1234567890abcdef),这样调用getWxPayService("wx1234567890abcdef")时就像直接用 appId 获取服务; - 使用自定义标识(如
wx.pay.configs.config1),调用时使用getWxPayService("config1")。
注意:getWxPayService(configKey) 方法的参数是配置文件中定义的 key,而不是 appId。只有当你使用 appId 作为配置 key 时,才能直接传入 appId。这是新手最容易踩的坑——接口注释与源码均明确强调了这一点(见 WxPayMultiServices.java)。
8.2 V2 和 V3 配置可以混用吗?
可以。不同的配置可以使用不同的版本,例如:
wx:
pay:
configs:
app1: # V2配置
appId: wx111
mchId: 111
mchKey: xxx
app2: # V3配置
appId: wx222
mchId: 222
apiV3Key: yyy
privateKeyPath: xxx
原因在于每个 configKey 都会独立构建一个 WxPayService,版本相关参数(mchKey/keyPath 与 apiV3Key/privateKeyPath 等)互不干扰。
8.3 证书文件如何放置?
- 放在
src/main/resources目录下,使用classpath:前缀(如classpath:cert/app1/apiclient_key.pem); - 放在服务器上,直接填写绝对路径;
- 建议为不同配置使用不同的目录组织证书,避免混淆。
8.4 服务商模式如何配置?
服务商模式需要同时配置服务商信息和子商户信息:appId 和 mchId 填写服务商的信息,subAppId 和 subMchId 填写子商户的信息。同一个服务商对接多个子商户时,重复声明多组配置即可,服务商字段可保持一致。
九、注意事项
- 配置安全:生产环境中的密钥、证书等敏感信息,建议使用配置中心或环境变量管理,避免硬编码进配置文件或仓库;
- 证书管理:不同公众号的证书文件要分开存放、按目录隔离,避免混淆导致签名失败;
- 懒加载:
WxPayService实例采用懒加载策略,只有在首次调用getWxPayService(configKey)时才会创建(对应源码中的computeIfAbsent逻辑); - 线程安全:
WxPayMultiServices的实现基于ConcurrentHashMap,是线程安全的,可放心在并发业务中共享; - 配置更新:如需动态更新配置,可调用
removeWxPayService(configKey)方法移除缓存的实例,下次获取时自动按最新配置重建; - 返回空值:当配置标识不存在或为空时
getWxPayService返回null并输出告警日志,业务侧务必判空后处理,避免空指针。
十、延伸阅读
- 本模块完整说明:spring-boot-starters/wx-java-pay-multi-spring-boot-starter/README.md
- 单商户版 Starter:spring-boot-starters/wx-java-pay-spring-boot-starter/README.md
- 多商户使用示例(含退款、重载):WxPayMultiExample.java
- 行为契约测试:WxPayMultiServicesTest.java
- 底层支付配置模型:WxPayConfig.java
- 多租户模式演进说明:spring-boot-starters/MULTI_TENANT_MODE_IMPROVEMENT.md