WxJava 微信支付 Spring Boot Starter 集成指南V2/V3/服务商模式配置与自动装配原理【免费下载链接】WxJava微信开发 Java SDK 支持包括微信支付开放平台小程序企业微信视频号公众号等的后端开发项目地址: https://gitcode.com/gh_mirrors/wx/WxJava导读wx-java-pay-spring-boot-starter是 WxJava微信开发 Java SDK官方提供的微信支付 Spring Boot 自动装配模块它把微信支付 SDK 中繁琐的WxPayConfig构建过程封装为纯配置驱动只要在application.yml中声明wx.pay前缀的属性Spring Boot 启动时便会自动创建可直接注入使用的WxPayService对象。本文将以该 Starter 的官方 README 为核心结合仓库源码完整讲解依赖引入、V2/V3/服务商三种模式的配置写法、全部可配置项语义以及自动装配的底层实现原理帮助读者在 Spring Boot 项目中开箱即用地接入微信支付。一、Starter 是什么一个依赖即开即用wx-java-pay-spring-boot-starter本质上是一个轻量封装层其 pom.xml 中只有唯一一个核心依赖weixin-java-pay即 WxJava 的微信支付核心模块SDK 版本与 Starter 版本保持一致。Starter 自身并不重复实现支付逻辑而是承担配置属性 →WxPayConfig→WxPayService的装配职责。整个模块只有两个源文件结构非常清晰WxPayProperties.java声明wx.pay前缀下所有可配置属性WxPayAutoConfiguration.java自动配置类负责把属性转换为WxPayConfig并装配出WxPayServiceBean。这也决定了它的使用方式极简引依赖 写配置然后直接注入WxPayService即可调用支付能力。二、引入 Maven 依赖在自己的 Spring Boot 项目中向pom.xml添加如下依赖${version}替换为你需要的版本号建议与 WxJava 主版本一致如4.8.6.Bdependency groupIdcom.github.binarywang/groupId artifactIdwx-java-pay-spring-boot-starter/artifactId version${version}/version /dependency引入后无需任何额外配置类Starter 会通过spring.factories/AutoConfiguration.imports机制被 Spring Boot 自动加载详见本文第五节。三、application.yml 三种配置模式微信支付接口按签名协议分为 V2mchKey p12 证书兼容老接口与 V3apiV3Key 商户私钥证书官方主推按业务关系又分为普通商户与服务商服务商代子商户收款。README 中给出了三种典型配置模板下面逐一完整说明。3.1 V2 版本配置V2 是微信支付传统签名方案使用商户密钥mchKey与 p12 证书文件wx: pay: appId: # 微信公众号/小程序/App 的 appId mchId: # 微信支付商户号 mchKey: # 商户密钥V2 签名使用 keyPath: # apiclient_cert.p12 证书文件路径字段含义配置项必填说明appId是关联的公众号/小程序等主体的 AppIDmchId是微信支付商户号mchKey是V2商户 API 密钥V2 接口签名使用keyPath视接口apiclient_cert.p12证书的绝对路径或放在项目中以classpath:开头指定如classpath:cert/apiclient_cert.p123.2 V3 版本配置V3 使用 APIv3 密钥 商户 API 证书pem 格式README 中的完整模板如下wx: pay: appId: xxxxxxxxxxx mchId: 15xxxxxxxxx #商户id apiHostUrl: http://10.0.0.1:3128 # 可选代理主机 apiHostUrlPath: /api-weixin # 可选代理入口前缀 apiV3Key: Dc1DBwSc094jACxxxxxxxxxxxxxxx #V3密钥 certSerialNo: 62C6CEAA360BCxxxxxxxxxxxxxxx privateKeyPath: classpath:cert/apiclient_key.pem #apiclient_key.pem证书文件的绝对路径或者以classpath:开头的类路径 privateCertPath: classpath:cert/apiclient_cert.pem #apiclient_cert.pem证书文件的绝对路径或者以classpath:开头的类路径字段含义配置项必填说明appId是商户关联的 AppIDmchId是商户号apiV3Key是V3APIv3 密钥用于回调报文解密与敏感信息加密certSerialNo是V3商户 API 证书序列号privateKeyPath是V3apiclient_key.pem商户私钥文件绝对路径或classpath:开头的类路径privateCertPath是V3apiclient_cert.pem商户证书文件绝对路径或classpath:开头的类路径apiHostUrl可选自定义 API 主机地址替换默认的https://api.mch.weixin.qq.com典型场景是经内网代理/网关转发示例中http://10.0.0.1:3128即代理主机apiHostUrlPath可选自定义 API 主机路径前缀代理入口前缀如/api-weixin3.3 V3 服务商版本配置服务商模式在 V3 基础上追加subAppId、subMchId描述子商户注意此时配置使用configs列表结构wx: pay: #微信服务商支付 configs: - appId: wxe97b2x9c2b3d #spAppId mchId: 16486610 #服务商商户 subAppId: wx118cexxe3c07679 #子appId subMchId: 16496705 #子商户 apiV3Key: Dc1DBwSc094jAKDGR5aqqb7PTHr #apiV3密钥 privateKeyPath: classpath:cert/apiclient_key.pem #服务商证书文件apiclient_key.pem证书文件的绝对路径或者以classpath:开头的类路径可以配置绝对路径 privateCertPath: classpath:cert/apiclient_cert.pem #apiclient_cert.pem证书文件的绝对路径或者以classpath:开头的类路径字段说明配置项必填说明configs是服务商模式下的配置列表每项代表一组完整的服务商子商户配置appId是服务商 AppIDspAppIdmchId是服务商商户号subAppId服务商模式必填子商户的公众号/小程序 AppIDsubMchId服务商模式必填子商户号其余字段同 V3apiV3Key、privateKeyPath、privateCertPath等含义与 3.2 节一致注意README 中configs为 YAML 列表-开头。这对应多配置场景若需要以配置标识 Map方式管理多个独立商户包括同商户多子商户建议使用仓库中配套的wx-java-pay-multi-spring-boot-starter见第七节。四、完整配置项总览来自源码wx.pay前缀下 Starter 实际支持的全部属性定义在 WxPayProperties.javaConfigurationProperties(prefix wx.pay)除 README 中示例外还包含支付分、公钥模式等增强项配置项类型默认值说明appIdString无公众号/小程序等主体 AppIDmchIdString无商户号mchKeyString无商户密钥V2subAppIdString无服务商模式子商户 AppID普通模式请删除该配置subMchIdString无服务商模式子商户号普通模式请删除该配置keyPathString无apiclient_cert.p12路径V2 证书绝对路径或classpath:开头serviceIdString无微信支付分 serviceIdcertSerialNoString无证书序列号V3apiV3KeyString无APIv3 密钥notifyUrlString无支付结果异步回调地址必须为可直接访问的 URL不能携带参数refundNotifyUrlString无退款结果异步回调地址必须为可直接访问的 URL不能携带参数payScoreNotifyUrlString无微信支付分回调地址payScorePermissionNotifyUrlString无微信支付分授权回调地址privateKeyPathString无V3 商户apiclient_key.pem路径privateCertPathString无V3 商户apiclient_cert.pem路径publicKeyIdString无公钥 ID平台公钥模式publicKeyPathString无pub_key.pem公钥文件路径绝对路径或classpath:开头useSandboxEnvbooleanfalse是否使用微信支付仿真测试沙箱环境默认不使用apiHostUrlString无自定义 API 主机地址替换默认https://api.mch.weixin.qq.comapiHostUrlPathString无自定义 API 主机路径前缀代理入口前缀strictlyNeedWechatPaySerialbooleantrue是否给全部 V3 接口请求都添加Wechatpay-Serial请求头默认添加fullPublicKeyModelbooleantrue是否完全使用公钥模式配合微信从平台证书向平台公钥的灰度切换默认使用这些属性在装配阶段会被逐一映射到weixin-java-pay核心模块的WxPayConfig见 WxPayConfig.java对应字段例如appId→setAppId、apiV3Key→setApiV3Key、useSandboxEnv→setUseSandboxEnv等一一对应、无额外魔法。五、自动装配原理属性如何变成 WxPayServiceStarter 的核心逻辑集中在 WxPayAutoConfiguration.java整个装配流程如下激活属性类EnableConfigurationProperties(WxPayProperties.class)注册wx.pay配置绑定条件装配ConditionalOnClass(WxPayService.class)保证类路径存在微信支付 SDK 时才生效ConditionalOnProperty(prefix wx.pay, value enabled, matchIfMissing true)表示默认启用也可以通过设置wx.pay.enabledfalse显式关闭构建配置wxPayService()方法内新建WxPayServiceImpl将WxPayProperties的各属性经StringUtils.trimToNull去空白后逐一set进WxPayConfig注入服务wxPayService.setConfig(payConfig)后返回 BeanConditionalOnMissingBean(WxPayService.class)允许用户自定义覆盖。对应地在业务代码中直接注入即可使用import com.github.binarywang.wxpay.service.WxPayService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; Service public class PayOrderService { Autowired private WxPayService wxPayService; // 直接调用 weixin-java-pay 提供的支付能力 // 如 V3 统一下单 createOrderV3、订单查询 queryOrderV3、申请退款 refundV3 等 }从源码结构可以推断Starter 提供的是单商户、单WxPayServiceBean的开箱即用方案所有wx.pay属性会聚合到同一个WxPayConfig。如果你的应用需要同时管理多个互不相同的商户/子商户配置则应采用第七节的多商户 Starter 或按配置标识构建多个实例。六、证书与敏感配置的放置建议证书文件位置V2 的keyPath、V3 的privateKeyPath/privateCertPath、公钥的publicKeyPath均支持两种写法绝对路径如/data/cert/apiclient_key.pem类路径把证书放入src/main/resources/cert/下写classpath:cert/apiclient_key.pem。敏感信息管理mchKey、apiV3Key、证书私钥等属于高危敏感数据生产环境建议通过环境变量、配置中心或密钥管理服务注入避免明文入库。回调地址约束notifyUrl、refundNotifyUrl等必须是公网可直连的 URL且不能携带查询参数。沙箱与灰度联调阶段可设置useSandboxEnv: true使用仿真环境微信平台证书向平台公钥切换期间保持fullPublicKeyModel: true默认值并配置publicKeyId/publicKeyPath即可平滑兼容。七、多商户/多配置场景的扩展参考当业务需要一个系统对接多个公众号的支付或一个服务商为多个子商户服务时仓库还提供了配套的 wx-java-pay-multi-spring-boot-starter其配置结构将wx.pay.configs定义为MapString, WxPaySingleProperties见 WxPayMultiProperties.javakey 可用 appId 或自定义标识wx: pay: configs: wx1234567890abcdef: # 配置标识key 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使用时注入WxPayMultiServices通过getWxPayService(configKey)按标识获取对应实例。其实现类 WxPayMultiServicesImpl.java 使用ConcurrentHashMapcomputeIfAbsent实现线程安全的懒加载——首次调用时才构建WxPayService并缓存调用removeWxPayService(configKey)可清除缓存实现动态更新。多配置下每个条目的字段与单商户 Starter 完全一致V2/V3/服务商参数可混用可参考其 README 中的完整配置与代码示例。八、常见问题小结三种配置模板怎么选新接口优先 V3历史老接口如部分 V2 退款/企业付款接口保留mchKeykeyPath代理收款场景使用服务商模式并补充subAppId/subMchId。配置了却不生效检查是否在依赖中排除了weixin-java-pay、属性前缀是否拼写为wx.pay以及wx.pay.enabledfalse是否被误设置。V3 报平台证书/公钥相关错误确认certSerialNo、apiV3Key、privateKeyPath、privateCertPath四件套齐全且与商户后台一致并留意fullPublicKeyModel与publicKeyId/publicKeyPath的配套使用。证书路径问题classpath:前缀的证书须位于打包后的 classpath 内通常放src/main/resources下否则请使用服务器上的绝对路径。至此从依赖引入、三种配置模板到属性全量说明与自动装配源码原理wx-java-pay-spring-boot-starter的完整使用链路已经打通。开发者只需维护一份wx.pay配置即可获得一个可直接注入、功能完整的WxPayService将精力聚焦在具体的支付业务实现上。【免费下载链接】WxJava微信开发 Java SDK 支持包括微信支付开放平台小程序企业微信视频号公众号等的后端开发项目地址: https://gitcode.com/gh_mirrors/wx/WxJava创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考