weixin-java-tools/QUARKUS_SUPPORT.md

WxJava Quarkus/GraalVM Native Image Support

概述

从 4.7.8.B 版本开始，WxJava 提供了对 Quarkus 和 GraalVM Native Image 的支持。这允许您将使用 WxJava 的应用程序编译为原生可执行文件，从而获得更快的启动速度和更低的内存占用。

问题背景

在之前的版本中，使用 Quarkus 构建 Native Image 时会遇到以下错误：

Error: Unsupported features in 3 methods
Detailed message:
Error: Detected an instance of Random/SplittableRandom class in the image heap. 
Instances created during image generation have cached seed values and don't behave as expected.
The culprit object has been instantiated by the 'org.apache.http.impl.auth.NTLMEngineImpl' class initializer

解决方案

为了解决这个问题，WxJava 进行了以下改进：

1. Random 实例的延迟初始化

所有 java.util.Random 实例都已改为延迟初始化，避免在类加载时创建：

• RandomUtils - 使用双重检查锁定模式延迟初始化
• SignUtils - 使用双重检查锁定模式延迟初始化
• WxCryptUtil - 使用双重检查锁定模式延迟初始化

2. Native Image 配置

在 weixin-java-common 模块中添加了 GraalVM Native Image 配置文件：

• META-INF/native-image/com.github.binarywang/weixin-java-common/native-image.properties

  • 配置 Apache HttpClient 相关类在运行时初始化，避免在构建时创建 SecureRandom 实例

• META-INF/native-image/com.github.binarywang/weixin-java-common/reflect-config.json

  • 配置反射访问的类和方法

使用方式

Quarkus 项目配置

在您的 Quarkus 项目中使用 WxJava，只需正常引入依赖即可：

<dependency>
  <groupId>com.github.binarywang</groupId>
  <artifactId>weixin-java-miniapp</artifactId>  <!-- 或其他模块 -->
  <version>4.7.8.B</version>
</dependency>

构建 Native Image

使用 Quarkus 构建原生可执行文件：

./mvnw package -Pnative

或使用容器构建：

./mvnw package -Pnative -Dquarkus.native.container-build=true

GraalVM Native Image

如果直接使用 GraalVM Native Image 工具：

native-image --no-fallback \
  -H:+ReportExceptionStackTraces \
  -jar your-application.jar

WxJava 的配置文件会自动被 Native Image 工具识别和应用。

测试验证

建议在构建 Native Image 后进行以下测试：

1. 验证应用程序可以正常启动
2. 验证微信 API 调用功能正常
3. 验证随机字符串生成功能正常
4. 验证加密/解密功能正常

已知限制

• 本配置主要针对 Quarkus 3.x 和 GraalVM 22.x+ 版本进行测试
• 如果使用其他 Native Image 构建工具（如 Spring Native），可能需要额外配置
• 部分反射使用可能需要根据实际使用的 WxJava 功能进行调整

问题反馈

如果在使用 Quarkus/GraalVM Native Image 时遇到问题，请通过以下方式反馈：

1. 在 GitHub Issues 提交问题
2. 提供详细的错误信息和 Native Image 构建日志
3. 说明使用的 Quarkus 版本和 GraalVM 版本

参考资料

• Quarkus 官方文档
• GraalVM Native Image 文档
• Quarkus Tips for Writing Native Applications

贡献

欢迎提交 PR 完善 Quarkus/GraalVM 支持！如果您发现了新的兼容性问题或有改进建议，请参考 代码贡献指南。