WxJava 微信小店 Solon 插件接入指南：wx-java-store-solon-plugin 配置详解与源码解析
【免费下载链接】WxJava微信开发 Java SDK ，支持包括微信支付，开放平台，小程序，企业微信，视频号，公众号等的后端开发项目地址: https://gitcode.com/gh_mirrors/wx/WxJava
本篇指南以 WxJava 仓库中wx-java-store-solon-plugin（Solon 框架下的微信小店开发插件）为核心，讲解如何在 Solon 应用中通过一条依赖、一份app.properties配置快速接入微信小店 API，并配合源码剖析其自动装配、ConfigStorage 存储策略与 HTTP 客户端选择机制。读完本文，你将掌握该插件的依赖引入、完整配置项语义、Bean 自动注入方式、典型调用代码，以及底层条件装配与默认值逻辑，能够在实际项目中直接落地使用。
插件定位：Solon 生态中的微信小店接入层
wx-java-store-solon-plugin位于仓库 solon-plugins/wx-java-store-solon-plugin 目录下，是 WxJava 针对 Solon（国产轻量级 Java 应用开发框架）提供的一站式接入插件。它本身不重复实现微信小店协议，而是对核心模块weixin-java-store做框架层封装：把WxStoreService、WxStoreConfig两个核心 Bean 以自动装配方式注入 Solon 容器，并把配置项以wx.store.*前缀绑定到属性类上，开发者只需写配置即可完成初始化，无需手写任何装配代码。
从 pom.xml 可以看到，插件直接依赖com.github.binarywang:weixin-java-store（版本与父工程一致，当前父工程版本为4.8.6.B），同时将jedis、redisson声明为provided作用域——也就是说 Redis 存储依赖是否生效，完全由使用方按需引入决定，这与下方配置章节的"按存储类型选依赖"是配套设计。
一、快速开始：引入依赖
在 Solon 应用的pom.xml中引入插件坐标，并按需添加 Redis 客户端依赖：
<dependencies> <dependency> <groupId>com.github.binarywang</groupId> <artifactId>wx-java-store-solon-plugin</artifactId> <version>${version}</version> </dependency> <!-- 配置存储方式为 jedis 则引入 jedis --> <dependency> <groupId>redis.clients</groupId> <artifactId>jedis</artifactId> <version>${jedis.version}</version> </dependency> <!-- 配置存储方式为 redisson 则引入 redisson --> <dependency> <groupId>org.redisson</groupId> <artifactId>redisson</artifactId> <version>${redisson.version}</version> </dependency> </dependencies>三个依赖的职责边界非常清晰：
wx-java-store-solon-plugin：必选，提供属性绑定、自动装配与条件化配置类；jedis：仅在config-storage.type=jedis时必需，插件侧已用provided声明，故不会传递引入；redisson：仅在config-storage.type=redisson时必需，引入时机与 jedis 同理。
如果你的应用容器中已经自行管理了JedisPool或RedissonClient实例，可以连这两个依赖都不引（详见下文"从容器复用连接"小节）。
二、添加配置：app.properties 全量字段说明
插件使用 Solon 的@Inject("${wx.store}")将wx.store.*前缀下的属性整体绑定到 WxStoreProperties.java，一份完整的配置文件如下（可直接复制到app.properties）：
# 微信小店配置(必填) ## 微信小店的appId和secret wx.store.app-id=@appId wx.store.secret=@secret # 微信小店配置 选填 ## 设置微信小店消息服务器配置的token wx.store.token=@token ## 设置微信小店消息服务器配置的EncodingAESKey wx.store.aes-key= ## 支持JSON或者XML格式，默认JSON wx.store.msg-data-format=JSON ## 是否使用稳定版 Access Token wx.store.use-stable-access-token=false # ConfigStorage 配置（选填） ## 配置类型: memory(默认), jedis, redisson, redis_template wx.store.config-storage.type=memory ## 相关redis前缀配置 wx.store.config-storage.key-prefix=wx:store wx.store.config-storage.redis.host=127.0.0.1 wx.store.config-storage.redis.port=6379 wx.store.config-storage.redis.password=123456 # http 客户端配置（选填） ## http客户端类型: http_client / http_components wx.store.config-storage.http-client-type=http_client wx.store.config-storage.http-proxy-host= wx.store.config-storage.http-proxy-port= wx.store.config-storage.http-proxy-username= wx.store.config-storage.http-proxy-password= ## 最大重试次数，默认：5 次，如果小于 0，则为 0 wx.store.config-storage.max-retry-times=5 ## 重试时间间隔步进，默认：1000 毫秒，如果小于 0，则为 1000 wx.store.config-storage.retry-sleep-millis=1000下表汇总了所有配置项的含义、默认值与取值范围，供快速查阅：
| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
wx.store.app-id | 是 | 无 | 微信小店 AppId |
wx.store.secret | 是 | 无 | 微信小店 Secret |
wx.store.token | 否 | 无 | 消息服务器配置 Token（用于消息验签） |
wx.store.aes-key | 否 | 空 | 消息服务器配置 EncodingAESKey |
wx.store.msg-data-format | 否 | JSON | 消息数据格式，JSON或XML |
wx.store.use-stable-access-token | 否 | false | 是否使用稳定版 Access Token |
wx.store.config-storage.type | 否 | memory | 存储类型：memory、jedis、redisson、redis_template |
wx.store.config-storage.key-prefix | 否 | wh | Access Token 等数据的 Redis key 前缀 |
wx.store.config-storage.redis.host | 否 | 空 | Redis 主机，不填则从 Solon 容器取连接 |
wx.store.config-storage.redis.port | 否 | 6379 | Redis 端口 |
wx.store.config-storage.redis.password | 否 | 空 | Redis 密码 |
wx.store.config-storage.redis.timeout | 否 | 2000 | Redis 连接超时（毫秒） |
wx.store.config-storage.redis.database | 否 | 0 | Redis 数据库编号 |
wx.store.config-storage.http-client-type | 否 | http_components | HTTP 客户端实现类型 |
wx.store.config-storage.http-proxy-host | 否 | 空 | HTTP 代理主机 |
wx.store.config-storage.http-proxy-port | 否 | 空 | HTTP 代理端口 |
wx.store.config-storage.http-proxy-username | 否 | 空 | HTTP 代理用户名 |
wx.store.config-storage.http-proxy-password | 否 | 空 | HTTP 代理密码 |
wx.store.config-storage.max-retry-times | 否 | 5 | 最大重试次数，小于 0 时强制为 0 |
wx.store.config-storage.retry-sleep-millis | 否 | 1000 | 重试间隔步进（毫秒），小于 0 时强制为 1000 |
几点需要特别注意：
- key-prefix 默认值以源码为准：README 示例中写的是
wx:store，但 WxStoreProperties.java 中keyPrefix的字段默认值是wh。如果你的 Redis 中已存在历史前缀数据，请显式配置wx.store.config-storage.key-prefix保持一致，避免 Token 缓存失效。 - redis 端口与超时默认值：
port默认6379、timeout默认2000（毫秒）、database默认0，见 RedisProperties.java。 - 重试参数的兜底校验：
maxRetryTimes小于 0 时被强制置 0，retrySleepMillis小于 0 时被强制置 1000，该逻辑在 AbstractWxStoreConfigStorageConfiguration.java 中实现，对应BaseWxStoreService#setRetrySleepMillis/#setMaxRetryTimes的能力。 - 消息格式：
msg-data-format默认JSON，源码通过StringUtils.trimToNull处理后写入配置，传入空值会被归一为空。
三、自动注入的 Bean 类型
插件装配完成后，Solon 容器中会自动注册以下两个核心 Bean，可直接通过@Inject使用：
| Bean 类型 | 职责 | 说明 |
|---|---|---|
com.binarywang.wxjava.store.api.WxStoreService | 微信小店门面服务 | 聚合店铺、商品、订单、售后等各类子服务，是业务调用的入口 |
com.binarywang.wxjava.store.config.WxStoreConfig | 微信小店配置存储 | 承载 AppId、Secret、Token、AESKey、消息格式、代理、重试等全部配置，同时也是 Access Token 的存取器 |
其中WxStoreService的注册带有双重条件：仅当容器中不存在用户自定义的WxStoreService且存在WxStoreConfig时才自动创建（见 WxStoreServiceAutoConfiguration.java）。这意味着：如果你需要深度定制（例如自研 Token 存储），完全可以自行声明同类型 Bean 覆盖默认装配，插件不会产生冲突。
四、使用样例：获取店铺基本信息
插件自带的 README 给出了最小可用示例，这里展开为一个可直接编译的完整版本：
import com.binarywang.wxjava.store.api.WxStoreService; import com.binarywang.wxjava.store.bean.shop.ShopInfoResponse; import com.binarywang.wxjava.store.util.JsonUtils; import me.chanjar.weixin.common.error.WxErrorException; import org.noear.solon.annotation.Component; import org.noear.solon.annotation.Inject; @Component public class DemoService { @Inject private WxStoreService wxStoreService; public String getShopInfo() throws WxErrorException { // 获取店铺基本信息 ShopInfoResponse response = wxStoreService.getBasicService().getShopInfo(); // 此处为演示，如果要返回response的结果，建议自己封装一个VO，避免直接返回response return JsonUtils.encode(response); } }要点说明：
WxStoreService按领域拆分出多个子服务（getBasicService()即基础信息服务），业务上按需取用，符合单一职责；- 接口方法统一抛出
WxErrorException，调用方需要捕获并处理微信侧的全局错误码； - 直接返回 SDK 的 Response 对象会把内部字段暴露给上层，生产环境建议自行封装 VO/DTO；
JsonUtils来自weixin-java-store模块的 util 包，负责序列化，仅用于演示输出。
该插件的测试工程 LoadTest.java 演示了在 Solon 测试环境下加载插件并校验容器装配是否完整，可作为集成自测的参考起点。
五、源码解析：自动装配与条件化存储策略
1. 插件装配入口：WxStorePluginImpl
Solon 的Plugin机制会在应用启动阶段执行start()，WxStorePluginImpl.java 依次注册了属性类、服务自动配置类以及三种存储配置类：
context.beanMake(WxStoreProperties.class); context.beanMake(WxStoreServiceAutoConfiguration.class); context.beanMake(WxStoreInMemoryConfigStorageConfiguration.class); context.beanMake(WxStoreInJedisConfigStorageConfiguration.class); context.beanMake(WxStoreInRedissonConfigStorageConfiguration.class);值得留意的是：StorageType枚举虽然声明了Memory / Jedis / Redisson / RedisTemplate四种类型（见 StorageType.java），但当前 Solon 插件内置的存储配置实现只有 memory、jedis、redisson 三种。README 中提到的redis_template需要使用者自行按同模式扩展（Spring Boot Starter 版本中有对应实现可参考）。
2. 条件装配：按配置选择存储实现
三种存储配置类全部使用 Solon 的@Condition注解做"按配置项 + 按类路径"双重判断：
- memory：
onProperty = "${wx.store.configStorage.type:memory} = memory"，未配置时默认走内存实现（见 WxStoreInMemoryConfigStorageConfiguration.java）； - jedis：
onProperty = "...type = jedis"且onClass = JedisPool.class（见 WxStoreInJedisConfigStorageConfiguration.java），没有引入 jedis 依赖时该配置类不会生效； - redisson：
onProperty = "...type = redisson"且onClass = Redisson.class，同理受类路径控制（见 WxStoreInRedissonConfigStorageConfiguration.java）。
三个配置类都通过@Condition(onMissingBean = WxStoreConfig.class)允许用户自定义配置覆盖，且wxStoreConfig()方法统一调用父类 AbstractWxStoreConfigStorageConfiguration.java 的config(...)完成属性落库（AppId/Secret/Token/AESKey/消息格式/稳定版 Token/代理/重试参数）。
3. 从容器复用 Redis 连接
WxStoreInJedisConfigStorageConfiguration与WxStoreInRedissonConfigStorageConfiguration的构造逻辑遵循同一约定：若配置了redis.host，则由插件自行创建连接池/客户端；否则从 Solon 容器中获取已存在的JedisPool/RedissonClientBean。因此：
- 单实例、无密码的简单场景，直接配置
redis.host即可； - 多租户、集群或已统一管理 Redis 连接的项目，可省略 host 配置，改为在容器中注册
JedisPool或RedissonClient，插件会自动复用。
Jedis 分支还会把maxActive、maxIdle、maxWaitMillis、minIdle等连接池参数映射到JedisPoolConfig，并默认开启testOnBorrow与testWhileIdle探活（见 WxStoreInJedisConfigStorageConfiguration.java）；Redisson 分支则使用单机模式（useSingleServer）并指定 NIO 传输模式。
4. HTTP 客户端实现的选择
WxStoreServiceAutoConfiguration根据config-storage.http-client-type决定服务实现类：
HttpClientType.HttpClient→WxStoreServiceHttpClientImpl（基于 Apache HttpClient）；- 其余（默认
HttpComponents）→WxStoreServiceHttpComponentsImpl（基于 HttpComponents，也是 HttpClientType.java 枚举与属性类中的默认值）。
两个实现类都位于weixin-java-store模块的api.impl包下，接口行为一致，仅底层 HTTP 传输实现不同，可按项目既有依赖选择。README 注释中写"默认 http_client"，但以当前源码为准，默认值是HttpComponents——如需 HttpClient 实现请显式配置。
六、常见问题与注意事项
- Token 缓存失效或数据串前缀：更换 Redis 前缀后旧 Token 缓存不再命中，属正常现象；多环境共用 Redis 时务必为每个环境配置独立
key-prefix。 - Redis 存储不生效：请检查是否已引入对应客户端依赖（jedis/redisson）——插件的
provided设计意味着不引依赖时条件装配静默失效，且不会报错提示。 - 想覆盖 Bean 但被默认装配抢先：插件所有关键 Bean（
WxStoreConfig、WxStoreService）均带onMissingBean条件，在 Solon 启动早期自行注册同名 Bean 即可接管。 - 消息接收场景：微信小店消息服务器的 Token/AESKey 即
wx.store.token与wx.store.aes-key，配合msg-data-format指定消息体格式；若同时使用稳定版 Access Token，将use-stable-access-token置为true。 - 代理与重试：内网受限环境需配置
http-proxy-*系列参数；max-retry-times与retry-sleep-millis用于提升弱网下的请求成功率，取值异常（负数）会被源码自动兜底。
总结
wx-java-store-solon-plugin把 Solon 的轻量装配能力与 WxJava 的微信小店 SDK 结合，做到了"引依赖 + 写配置"两步接入：属性绑定统一在wx.store.*前缀下，存储层与 HTTP 层均通过条件装配实现可插拔，核心 Bean 支持用户自定义覆盖。无论你的应用是单机内存存储还是 Redis 集群，都能在本文配置表与源码路径的指引下快速完成接入并定位问题。
【免费下载链接】WxJava微信开发 Java SDK ，支持包括微信支付，开放平台，小程序，企业微信，视频号，公众号等的后端开发项目地址: https://gitcode.com/gh_mirrors/wx/WxJava
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
