WxJava 微信支付多商户配置实战:wx-java-pay-multi-spring-boot-starter 从入门到源码解析

原创2026-10-13 13:47:481,357 阅读
文章标签:后端认证鉴权小程序API设计

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);
  });
}

几个值得注意的设计点:

  1. 懒加载:WxPayService 只有在首次被 getWxPayService 调用时才构建,未使用的商户配置不会产生实例;
  2. 线程安全:底层容器是 ConcurrentHashMap,computeIfAbsent 保证同一 key 的构建只发生一次且对并发线程安全,注释中明确说明这是为了避免 synchronized(this) 的性能开销;
  3. 空值语义:key 为空、或配置不存在时返回 null(并在日志中告警),调用方需要像上文示例那样判空;
  4. 移除即重建: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 填写子商户的信息。同一个服务商对接多个子商户时,重复声明多组配置即可,服务商字段可保持一致。

九、注意事项

  1. 配置安全:生产环境中的密钥、证书等敏感信息,建议使用配置中心或环境变量管理,避免硬编码进配置文件或仓库;
  2. 证书管理:不同公众号的证书文件要分开存放、按目录隔离,避免混淆导致签名失败;
  3. 懒加载:WxPayService 实例采用懒加载策略,只有在首次调用 getWxPayService(configKey) 时才会创建(对应源码中的 computeIfAbsent 逻辑);
  4. 线程安全:WxPayMultiServices 的实现基于 ConcurrentHashMap,是线程安全的,可放心在并发业务中共享;
  5. 配置更新:如需动态更新配置,可调用 removeWxPayService(configKey) 方法移除缓存的实例,下次获取时自动按最新配置重建;
  6. 返回空值:当配置标识不存在或为空时 getWxPayService 返回 null 并输出告警日志,业务侧务必判空后处理,避免空指针。

十、延伸阅读

登录后查看全文
WxJava