WxJava Documentation

git clone https://github.com/binarywang/WxJava.git
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R WxJava/skills/wxjava-* "${CODEX_HOME:-$HOME/.codex}/skills/"

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/wxjava-* "${CODEX_HOME:-$HOME/.codex}/skills/"

<wx-java.version>4.8.3.B</wx-java.version>


<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.github.binarywang</groupId>
      <artifactId>wx-java-bom</artifactId>
      <version>${wx-java.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependency>
  <groupId>com.github.binarywang</groupId>
  <artifactId>weixin-java-mp</artifactId>
</dependency>
<dependency>
  <groupId>com.github.binarywang</groupId>
  <artifactId>weixin-java-pay</artifactId>
</dependency>

<dependency>
  <groupId>com.github.binarywang</groupId>
  <artifactId>（不同模块参考下文）</artifactId>
  <version>4.8.0</version>
</dependency>

WxMpDefaultConfigImpl config = new WxMpDefaultConfigImpl();
config.setAppId("your-app-id");
config.setSecret("your-secret");

WxMpService wxMpService = new WxMpServiceImpl();
wxMpService.setWxMpConfigStorage(config);

String accessToken = wxMpService.getAccessToken();
System.out.println(accessToken);

WxMaDefaultConfigImpl config = new WxMaDefaultConfigImpl();
config.setAppid("your-app-id");
config.setSecret("your-secret");

WxMaService wxMaService = new WxMaServiceImpl();
wxMaService.setWxMaConfig(config);

WxMaJscode2SessionResult result = wxMaService.getUserService().getSessionInfo("js-code");
System.out.println(result.getOpenid());

SIGSEGV (0xb) at pc=0x00007fcd50460d93
Problematic frame:
C  [libWeWorkFinanceSdk_Java.so+0x260d93]  WeWorkFinanceSdk::TryRefresh(std::string const&, std::string const&, int)+0x23

// ❌ 不推荐：容易导致JVM崩溃
WxCpMsgAuditService msgAuditService = wxCpService.getMsgAuditService();

// 拉取聊天记录
WxCpChatDatas chatDatas = msgAuditService.getChatDatas(seq, 1000L, null, null, 1000L);

for (WxCpChatDatas.WxCpChatData chatData : chatDatas.getChatData()) {
    // 解密数据
    WxCpChatModel model = msgAuditService.getDecryptData(chatDatas.getSdk(), chatData, 2);
    
    // 下载媒体文件
    if ("image".equals(model.getMsgType())) {
        String sdkFileId = model.getImage().getSdkFileId();
        msgAuditService.getMediaFile(chatDatas.getSdk(), sdkFileId, null, null, 1000L, targetPath);
    }
}

// ❌ 危险操作：手动销毁SDK可能导致后续调用崩溃
Finance.DestroySdk(chatDatas.getSdk());

// ✅ 推荐：SDK生命周期由框架自动管理，安全可靠
WxCpMsgAuditService msgAuditService = wxCpService.getMsgAuditService();

// 拉取聊天记录（不返回SDK）
List<WxCpChatDatas.WxCpChatData> chatRecords = 
    msgAuditService.getChatRecords(seq, 1000L, null, null, 1000L);

for (WxCpChatDatas.WxCpChatData chatData : chatRecords) {
    // 解密数据（无需传入SDK）
    WxCpChatModel model = msgAuditService.getDecryptChatData(chatData, 2);
    
    // 下载媒体文件（无需传入SDK）
    if ("image".equals(model.getMsgType())) {
        String sdkFileId = model.getImage().getSdkFileId();
        msgAuditService.downloadMediaFile(sdkFileId, null, null, 1000L, targetPath);
    }
}

// ✅ 无需手动销毁SDK，框架会自动管理

/* Detailed source-code truncated for AI context efficiency. */

msgAuditService.downloadMediaFile(sdkFileId, null, null, 1000L, data -> {
    try {
        // 处理每个数据分片（大文件会分片传输）
        // 例如：上传到云存储、写入数据库等
        uploadToCloud(data);
    } catch (Exception e) {
        e.printStackTrace();
    }
});

// 框架内部实现（简化版）
public void downloadMediaFile(String sdkFileId, ...) {
    long sdk = initSdk();  // 获取或初始化SDK（有效期内直接复用缓存）
    configStorage.incrementMsgAuditSdkRefCount(sdk);  // 引用计数 +1

    try {
        // 执行实际操作
        getMediaFile(sdk, sdkFileId, ...);
    } finally {
        // 确保引用计数一定会减少；仅在归零且过期时销毁
        configStorage.decrementMsgAuditSdkRefCount(sdk);  // 引用计数 -1
    }
}

// 查找模式
getChatDatas(
getDecryptData(.*sdk
getChatPlainText(.*sdk
getMediaFile(.*sdk
Finance.DestroySdk(

<dependency>
  <groupId>com.github.binarywang</groupId>
  <artifactId>weixin-java-mp</artifactId>
  <version>最新版本</version> 
</dependency>

# 使用 HttpClient 5.x（推荐，无需配置，已经是默认值）
wx.mp.config-storage.http-client-type=HttpComponents

# 或者继续使用 HttpClient 4.x
wx.mp.config-storage.http-client-type=HttpClient

// 使用 HttpClient 5.x（推荐）
WxMpService wxMpService = new WxMpServiceHttpComponentsImpl();

// 或者继续使用 HttpClient 4.x
WxMpService wxMpService = new WxMpServiceHttpClientImpl();

<dependency>
  <groupId>com.github.binarywang</groupId>
  <artifactId>weixin-java-mp</artifactId>
  <version>最新版本</version>
  <exclusions>
    
    <exclusion>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpclient</artifactId>
    </exclusion>
    <exclusion>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpmime</artifactId>
    </exclusion>
  </exclusions>
</dependency>

# 公众号配置
wx.mp.app-id=your_app_id
wx.mp.secret=your_secret
wx.mp.token=your_token
wx.mp.aes-key=your_aes_key

# HTTP 客户端配置
wx.mp.config-storage.http-client-type=HttpComponents  # HttpComponents, HttpClient, OkHttp, JoddHttp

# HTTP 代理配置（可选）
wx.mp.config-storage.http-proxy-host=proxy.example.com
wx.mp.config-storage.http-proxy-port=8080
wx.mp.config-storage.http-proxy-username=proxy_user
wx.mp.config-storage.http-proxy-password=proxy_pass

# 超时配置（可选）
wx.mp.config-storage.connection-timeout=5000
wx.mp.config-storage.so-timeout=5000
wx.mp.config-storage.connection-request-timeout=5000

weixin-java-common/
├── util/http/
│   ├── apache/          # HttpClient 4.x 实现
│   ├── hc/              # HttpClient 5.x (HttpComponents) 实现
│   ├── okhttp/          # OkHttp 实现
│   └── jodd/            # Jodd-http 实现

// Get the customer service management service
WxMaKefuService kefuService = wxMaService.getKefuService();

// Add a new customer service account
WxMaKfAccountRequest request = WxMaKfAccountRequest.builder()
    .kfAccount("service001@example")
    .kfNick("Customer Service 001")
    .kfPwd("password123")
    .build();
boolean result = kefuService.kfAccountAdd(request);

// Create a session between user and customer service
boolean sessionResult = kefuService.kfSessionCreate("user_openid", "service001@example");

// Get customer service list
WxMaKfList kfList = kefuService.kfList();

WxMaKefuService kefuService = wxMaService.getKefuService();

// 免确认授权模式 - 提升用户体验
TransferBillsRequest request = TransferBillsRequest.newBuilder()
    .receiptAuthorizationMode(WxPayConstants.ReceiptAuthorizationMode.NO_CONFIRM_RECEIPT_AUTHORIZATION)
    // 其他参数...
    .build();

// 需确认授权模式（默认）
TransferBillsRequest request2 = TransferBillsRequest.newBuilder()
    .receiptAuthorizationMode(WxPayConstants.ReceiptAuthorizationMode.CONFIRM_RECEIPT_AUTHORIZATION)
    // 其他参数...
    .build();

// 获取WxPayService实例
WxPayService wxPayService = new WxPayServiceImpl();
wxPayService.setConfig(config);

// 获取新版转账服务 - 这就是新开通商户需要使用的服务！
TransferService transferService = wxPayService.getTransferService();

// 构建转账请求
TransferBillsRequest request = TransferBillsRequest.newBuilder()
    .appid("your_appid")                    // 应用ID
    .outBillNo("T" + System.currentTimeMillis()) // 商户转账单号
    .transferSceneId("1005")                // 转账场景ID（佣金报酬）
    .openid("user_openid")                  // 用户openid
    .userName("张三")                        // 收款用户姓名（可选，自动加密）
    .transferAmount(100)                    // 转账金额（分）
    .transferRemark("佣金报酬")              // 转账备注
    .build();

// 发起转账
TransferBillsResult result = transferService.transferBills(request);
System.out.println("转账成功，微信转账单号：" + result.getTransferBillNo());

// 通过商户单号查询
TransferBillsGetResult result = transferService.getBillsByOutBillNo("T1642567890123");

// 通过微信转账单号查询  
TransferBillsGetResult result2 = transferService.getBillsByTransferBillNo("wx_transfer_bill_no");

System.out.println("转账状态：" + result.getState());

// 撤销转账
TransferBillsCancelResult cancelResult = transferService.transformBillsCancel("T1642567890123");
System.out.println("撤销状态：" + cancelResult.getState());

TransferBillsRequest request = TransferBillsRequest.newBuilder()
    .appid("your_appid")
    .outBillNo("NO_CONFIRM_" + System.currentTimeMillis())
    .transferSceneId("1005")                       // 佣金报酬场景
    .openid("user_openid")
    .transferAmount(200)                           // 2元
    .transferRemark("免确认收款转账")
    .receiptAuthorizationMode(WxPayConstants.ReceiptAuthorizationMode.NO_CONFIRM_RECEIPT_AUTHORIZATION)
    .userRecvPerception("Y")
    .build();

try {
    TransferBillsResult result = transferService.transferBills(request);
    System.out.println("转账成功，直接到账：" + result.getTransferBillNo());
} catch (WxPayException e) {
    if ("USER_NOT_AUTHORIZED".equals(e.getErrCode())) {
        System.err.println("用户未授权免确认收款，请先引导用户进行授权");
    }
}

TransferBillsRequest request = TransferBillsRequest.newBuilder()
    .appid("your_appid")
    .outBillNo("CONFIRM_" + System.currentTimeMillis())
    .transferSceneId("1005")
    .openid("user_openid")
    .transferAmount(150)                           // 1.5元
    .transferRemark("需确认收款转账")
    // .receiptAuthorizationMode(...) // 不设置时使用默认的确认模式
    .userRecvPerception("Y")
    .build();

TransferBillsResult result = transferService.transferBills(request);
System.out.println("转账发起成功，等待用户确认：" + result.getPackageInfo());

try {
    TransferBillsResult result = transferService.transferBills(request);
} catch (WxPayException e) {
    switch (e.getErrCode()) {
        case "USER_NOT_AUTHORIZED":
            // 用户未授权免确认收款
            System.err.println("请先引导用户进行免确认收款授权");
            // 可以引导用户到授权页面
            break;
        case "AUTHORIZATION_EXPIRED":
            // 授权已过期
            System.err.println("用户授权已过期，请重新授权");
            break;
        default:
            System.err.println("转账失败：" + e.getMessage());
    }
}

// 获取WxPayService实例
WxPayService wxPayService = new WxPayServiceImpl();
wxPayService.setConfig(config);

// 获取新版转账服务
TransferService transferService = wxPayService.getTransferService();

// 构建转账请求
TransferBillsRequest request = TransferBillsRequest.newBuilder()
    .appid("your_appid")                           // 应用ID
    .outBillNo("T" + System.currentTimeMillis())   // 商户转账单号
    .transferSceneId("1005")                       // 转账场景ID（佣金报酬）
    .openid("user_openid")                         // 用户openid
    .userName("张三")                               // 收款用户姓名（可选，需要加密）
    .transferAmount(100)                           // 转账金额（分）
    .transferRemark("佣金报酬")                     // 转账备注
    .notifyUrl("https://your-domain.com/notify")   // 回调地址（可选）
    .userRecvPerception("Y")                       // 用户收款感知（可选）
    .build();

try {
    TransferBillsResult result = transferService.transferBills(request);
    System.out.println("转账成功，微信转账单号：" + result.getTransferBillNo());
    System.out.println("状态：" + result.getState());
} catch (WxPayException e) {
    System.err.println("转账失败：" + e.getMessage());
}

// 通过商户单号查询
String outBillNo = "T1642567890123";
TransferBillsGetResult result = transferService.getBillsByOutBillNo(outBillNo);

// 通过微信转账单号查询
String transferBillNo = "1000000000000000000000000001";
TransferBillsGetResult result2 = transferService.getBillsByTransferBillNo(transferBillNo);

System.out.println("转账状态：" + result.getState());
System.out.println("转账金额：" + result.getTransferAmount());

// 撤销转账（仅在特定状态下可撤销）
String outBillNo = "T1642567890123";
TransferBillsCancelResult cancelResult = transferService.transformBillsCancel(outBillNo);
System.out.println("撤销结果：" + cancelResult.getState());

// 在回调接口中处理通知
@PostMapping("/transfer/notify")
public String handleTransferNotify(HttpServletRequest request) throws Exception {
    String notifyData = StreamUtils.copyToString(request.getInputStream(), StandardCharsets.UTF_8);
    
    // 构建签名头
    SignatureHeader header = new SignatureHeader();
    header.setTimeStamp(request.getHeader("Wechatpay-Timestamp"));
    header.setNonce(request.getHeader("Wechatpay-Nonce"));
    header.setSignature(request.getHeader("Wechatpay-Signature"));
    header.setSerial(request.getHeader("Wechatpay-Serial"));
    
    try {
        TransferBillsNotifyResult notifyResult = transferService.parseTransferBillsNotifyResult(notifyData, header);
        
        // 处理业务逻辑
        String outBillNo = notifyResult.getOutBillNo();
        String state = notifyResult.getState();
        
        System.out.println("转账单号：" + outBillNo + "，状态：" + state);
        
        return "SUCCESS";
    } catch (WxPayException e) {
        System.err.println("验签失败：" + e.getMessage());
        return "FAIL";
    }
}

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

<dependency>
  <groupId>com.github.binarywang</groupId>
  <artifactId>weixin-java-miniapp</artifactId>  
  <version>4.7.8.B</version>
</dependency>

./mvnw package -Pnative

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

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

wechat:
  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:开头的类路径
  miniapp: #小程序
    configs:
    - appid: wx118ce3xxc76ccg
      secret: 8a132a276ee2f8fb58b1ed8f2
      token: #微信小程序消息服务器配置的token
      aesKey: #微信小程序消息服务器配置的EncodingAESKey
      msgDataFormat: JSON
  cp: #企业微信
    corpId: wwa3be8efd2addfgj
    appConfigs:
    - agentId: 10001 #客户联系
      secret: T5fTj1n-sBAT4rKNW5c9IYNfPdXZ8-oGol5tX
      token: 2bSNqTcLtFYBUa1u2
      aesKey: AXazu2Xyw44SNY1x8go2phn9p9B2O9oiEfqPN
    - agentId: 10003 #会话内容存档
      secret: xIpum7Yt4NMXcyxdzcQ2l_46BG4QIQDR57MhA
      token:
      aesKey:
    - agentId: 3010011 #打卡
      secret: 3i2Mhfusifaw_-04bMYI8OoKGxPe9mDALbUxV
      token:
      aesKey:
    - agentId: 19998 #通讯录同步
      secret: rNyDae0Pg-3d-wqTd_ozMSJfF0DEjTCz3b_pr
      token: xUke8yZciAZqImGZ
      aesKey: EUTVyArqJcfnpFiudxjRpuOexNqBoPbwrNG3R
    - agentId: 20000 #微盘
      secret: D-TVMvUji7PZZdjhZOSgiy2MTuBd0OCdvI_zi
      token:
      aesKey:

@Data
@ConfigurationProperties(prefix = "wechat.pay")
public class WxPayProperties {

    private List<Config> configs;

    @Getter
    @Setter
    public static class Config {

        private String appId;
        private String mchId;
        private String subAppId;
        private String subMchId;
        private String apiV3Key;
        private String privateKeyPath;
        private String privateCertPath;

    }

}

@Configuration
@EnableConfigurationProperties(WxPayProperties.class)
@AllArgsConstructor
public class WxPayConfiguration {

    private WxPayProperties properties;

    @Bean
    public WxPayService wxPayService() {

        // 多配置
        WxPayService wxPayService = new WxPayServiceImpl();
        Map<String, WxPayConfig> payConfigs = this.properties.getConfigs().stream().map(config -> {
            WxPayConfig payConfig = new WxPayConfig();
            payConfig.setAppId(StringUtils.trimToNull(config.getAppId()));
            payConfig.setMchId(StringUtils.trimToNull(config.getMchId()));
            payConfig.setSubAppId(StringUtils.trimToNull(config.getSubAppId()));
            payConfig.setSubMchId(StringUtils.trimToNull(config.getSubMchId()));
            payConfig.setApiV3Key(StringUtils.trimToNull(config.getApiV3Key()));
            payConfig.setPrivateKeyPath(StringUtils.trimToNull(config.getPrivateKeyPath()));
            payConfig.setPrivateCertPath(StringUtils.trimToNull(config.getPrivateCertPath()));

            // 可以指定是否使用沙箱环境
            payConfig.setUseSandboxEnv(false);
            return payConfig;
        }).collect(Collectors.toMap(config -> config.getSubMchId(), a -> a));

        wxPayService.setMultiConfig(payConfigs);
        return wxPayService;
    }

}

@Setter
@Getter
@ConfigurationProperties(prefix = "wechat.miniapp")
public class WxMaProperties {

    private List<Config> configs;

    @Data
    public static class Config {

        /**
         * 设置微信小程序的appid
         */
        private String appid;

        /**
         * 设置微信小程序的Secret
         */
        private String secret;

        /**
         * 设置微信小程序消息服务器配置的token
         */
        private String token;

        /**
         * 设置微信小程序消息服务器配置的EncodingAESKey
         */
        private String aesKey;

        /**
         * 消息格式，XML或者JSON
         */
        private String msgDataFormat;

    }

}

/* Detailed source-code truncated for AI context efficiency. */

@Getter
@Setter
@ConfigurationProperties(prefix = "wechat.cp")
public class WxCpProperties {

  /**
   * 设置企业微信的corpId
   */
  private String corpId;

  private List<AppConfig> appConfigs;

  @Getter
  @Setter
  public static class AppConfig {
    /**
     * 设置企业微信应用的AgentId
     */
    private Integer agentId;

    /**
     * 设置企业微信应用的Secret
     */
    private String secret;

    /**
     * 设置企业微信应用的token
     */
    private String token;

    /**
     * 设置企业微信应用的EncodingAESKey
     */
    private String aesKey;

  }

}

/* Detailed source-code truncated for AI context efficiency. */

---

## File: solon-plugins/wx-java-channel-solon-plugin/README.md

# wx-java-channel-solon-plugin

## 快速开始
1. 引入依赖
    ```xml
    <dependencies>
        <dependency>
            <groupId>com.github.binarywang</groupId>
            <artifactId>wx-java-channel-solon-plugin</artifactId>
            <version>${version}</version>
        </dependency>
   
        
        <dependency>
            <groupId>redis.clients</groupId>
            <artifactId>jedis</artifactId>
            <version>${jedis.version}</version>
        </dependency>

        
        <dependency>
            <groupId>org.redisson</groupId>
            <artifactId>redisson</artifactId>
            <version>${redisson.version}</version>
        </dependency>
    </dependencies>
    ```
2. 添加配置(app.properties)
    ```properties
    # 视频号配置(必填)
    ## 视频号小店的appId和secret
    wx.channel.app-id=@appId
    wx.channel.secret=@secret
    # 视频号配置 选填
    ## 设置视频号小店消息服务器配置的token
    wx.channel.token=@token
    ## 设置视频号小店消息服务器配置的EncodingAESKey
    wx.channel.aes-key=
    ## 支持JSON或者XML格式，默认JSON
    wx.channel.msg-data-format=JSON
    ## 是否使用稳定版 Access Token
    wx.channel.use-stable-access-token=false
    
    
    # ConfigStorage 配置（选填）
    ## 配置类型: memory(默认), jedis, redisson, redis_template
    wx.channel.config-storage.type=memory
    ## 相关redis前缀配置: wx:channel(默认)
    wx.channel.config-storage.key-prefix=wx:channel
    wx.channel.config-storage.redis.host=127.0.0.1
    wx.channel.config-storage.redis.port=6379
    wx.channel.config-storage.redis.password=123456
 
    
    # http 客户端配置（选填）
    ## # http客户端类型: http_client(默认)
    wx.channel.config-storage.http-client-type=http_client
    wx.channel.config-storage.http-proxy-host=
    wx.channel.config-storage.http-proxy-port=
    wx.channel.config-storage.http-proxy-username=
    wx.channel.config-storage.http-proxy-password=
    ## 最大重试次数，默认：5 次，如果小于 0，则为 0
    wx.channel.config-storage.max-retry-times=5
    ## 重试时间间隔步进，默认：1000 毫秒，如果小于 0，则为 1000
    wx.channel.config-storage.retry-sleep-millis=1000
    ```
3. 自动注入的类型
- `WxChannelService`
- `WxChannelConfig`
4. 使用样例

```java
import me.chanjar.weixin.channel.api.WxChannelService;
import me.chanjar.weixin.channel.bean.shop.ShopInfoResponse;
import me.chanjar.weixin.channel.util.JsonUtils;
import me.chanjar.weixin.common.error.WxErrorException;
import org.noear.solon.annotation.Inject;

@Component
public class DemoService {
  @Inject
  private WxChannelService wxChannelService;

  public String getShopInfo() throws WxErrorException {
    // 获取店铺基本信息
    ShopInfoResponse response = wxChannelService.getBasicService().getShopInfo();
    // 此处为演示，如果要返回response的结果，建议自己封装一个VO，避免直接返回response
    return JsonUtils.encode(response);
  }
}