WxJava SDK

The Session Archive (会话存档) SDK has been refactored to use a ThreadLocal pattern. Instead of a shared SDK with reference counting, each thread now maintains its own independent SDK instance. This ensures thread safety and allows multiple calls within the same thread (e.g., fetching records, decrypting data, and downloading media) to reuse the same SDK instance without repeated initialization.

Key Lifecycle Rules:

• Lazy Initialization: The SDK is initialized automatically on the first call within a thread.
• Thread-Bound: The SDK instance is tied to the current thread.
• Manual Cleanup Required: Because the SDK uses native resources, you must explicitly release the SDK when a thread's task is finished to prevent native memory and connection leaks.

// Typical usage pattern
WxCpMsgAuditService msgAuditService = wxCpService.getMsgAuditService();

try {
    // Multiple calls reuse the same SDK instance within this thread
    List<WxCpChatDatas.WxCpChatData> records = msgAuditService.getChatRecords(seq, 100L, null, null, 30L);
    for (WxCpChatDatas.WxCpChatData record : records) {
        WxCpChatModel model = msgAuditService.getDecryptChatData(record, 2);
        // ...
    }
} finally {
    // CRITICAL: Always call this in a finally block to release native resources
    msgAuditService.closeThreadLocalSdk();
}

Starting from version 4.8.0, the wx-java-miniapp-multi-spring-boot-starter supports two multi-tenant implementation modes. Choosing the right mode depends on your tenant count and programming model.

1. Isolated Mode (ISOLATED - Default)

Each tenant gets its own WxMaService instance and its own independent HTTP client.

• Pros: Thread-safe, no ThreadLocal dependency (ideal for asynchronous/reactive programming), and complete isolation between tenants.
• Cons: Higher resource consumption because each tenant creates a new HTTP client.
• Best for: SaaS applications with a small number of tenants (recommended < 50), or environments using asynchronous/reactive programming.

2. Shared Mode (SHARED)

A single WxMaService instance manages all tenant configurations, sharing one HTTP client across all tenants.

• Pros: Significantly lower resource usage and smaller memory footprint. Supports large-scale scenarios (100+ tenants).
• Cons: Relies on ThreadLocal to switch configurations. Requires careful handling of thread context in asynchronous scenarios.
• Best for: Large-scale applications (> 50 tenants) using synchronous programming where resource optimization is critical.

The starter automatically injects WxPayMultiServices. Use this bean to retrieve a specific WxPayService instance by its configuration key.

Key Concept: The configKey passed to getWxPayService(configKey) must match the key used in your configuration file (e.g., wx.pay.configs.<configKey>), not necessarily the appId unless you used the appId as the key.

@Service
public class PayService {
  @Autowired
  private WxPayMultiServices wxPayMultiServices;

  public void createOrder(String configKey, String openId, Integer totalFee, String body) throws Exception {
    // Retrieve the specific service for the given config key
    WxPayService wxPayService = wxPayMultiServices.getWxPayService(configKey);

    if (wxPayService == null) {
      throw new IllegalArgumentException("Config not found: " + configKey);
    }
    
    // Use the service as usual
    WxPayUnifiedOrderV3Request request = new WxPayUnifiedOrderV3Request();
    // ... set request parameters ...
    wxPayService.createOrderV3(TradeTypeEnum.JSAPI, request);
  }
}

When implementing complex WeChat Pay logic, follow these recommended patterns:

1. Multi-tenant SaaS Scenarios: Use custom keys (such as a tenantId) to manage configurations. Register them using addConfig(String configKey, WxPayConfig) and switch contexts using switchover(tenantId).
2. One Merchant with Multiple AppIDs: Use the mchId_appId format for keys. Switch contexts precisely using switchover(mchId, appId).
3. Asynchronous/Thread Pool Scenarios: Avoid relying on ThreadLocal (which switchover uses). Instead, use getConfig(mchId, appId) to retrieve the required configuration directly in the worker thread.

Important Notes:

• Thread Safety: switchover uses WxPayConfigHolder (based on ThreadLocal), making it thread-safe for the current thread. Direct retrieval via getConfig(mchId, appId) does not depend on ThreadLocal and is safe in any context.
• Notification Callbacks: The SDK automatically handles cases where appId might be missing in a callback by falling back to mchId matching during a switchover(mchId, appId) call.
• Backward Compatibility: Existing single-appId usage remains fully supported and requires no code changes.

To maintain backward compatibility for users of the 收付通 (Ecommerce) payment module, WxJava provides a compatibility layer that maps old API models to the current unified V3 API.

Key Architectural Concepts:

• Legacy Models: Old data structures are restored in the com.github.binarywang.wxpay.bean.ecommerce package. These classes are marked with @Deprecated to signal that users should migrate to the unified V3 API.
• Service Adapters: The EcommerceService provides deprecated method overloads. These overloads accept legacy request/response types, map them to the current unified request/enums, invoke the standard V3 methods, and then map the results back to the legacy formats.
• Unified Logic: The compatibility layer does not reimplement HTTP transport, signature verification, or notification logic. It strictly acts as a mapping layer over the existing unified implementation.