weixin-java-tools/docs/CP_MSG_AUDIT_SDK_SAFE_USAGE.md

企业微信会话存档SDK安全使用指南

问题背景

在使用企业微信会话存档功能时，部分开发者遇到了JVM崩溃的问题。典型错误信息如下：

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

问题原因

旧版API设计存在以下问题：

1. SDK生命周期管理混乱

   • getChatDatas() 方法会返回SDK实例给调用方
   • 开发者需要手动调用 Finance.DestroySdk() 来销毁SDK
   • 但SDK在框架内部有7200秒的缓存机制

2. 手动销毁导致缓存失效

   • 当开发者手动销毁SDK后，框架缓存中的SDK引用变为无效
   • 后续调用（如 getMediaFile()）仍然使用已销毁的SDK
   • 底层C++库访问无效指针，导致SIGSEGV错误

3. 多线程并发问题

   • 在多线程环境下，一个线程销毁SDK后
   • 其他线程仍在使用该SDK，导致崩溃

解决方案

从 4.8.0 版本开始，WxJava提供了新的安全API，完全由框架管理SDK生命周期。

新API列表

旧API（已废弃）	新API（推荐使用）	说明
getChatDatas()	getChatRecords()	拉取聊天记录，不暴露SDK
getDecryptData(sdk, ...)	getDecryptChatData(...)	解密聊天数据，无需传入SDK
getChatPlainText(sdk, ...)	getChatRecordPlainText(...)	获取明文数据，无需传入SDK
getMediaFile(sdk, ...)	downloadMediaFile(...)	下载媒体文件，无需传入SDK

使用示例

错误用法（旧API，已废弃）

// ❌ 不推荐：容易导致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());

正确用法（新API，推荐）

// ✅ 推荐：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，框架会自动管理

完整示例：拉取并处理会话存档

import me.chanjar.weixin.cp.api.WxCpService;
import me.chanjar.weixin.cp.api.WxCpMsgAuditService;
import me.chanjar.weixin.cp.bean.msgaudit.WxCpChatDatas;
import me.chanjar.weixin.cp.bean.msgaudit.WxCpChatModel;
import me.chanjar.weixin.cp.constant.WxCpConsts;

import java.util.List;

public class MsgAuditExample {
    
    private final WxCpService wxCpService;
    
    public void processMessages(long seq) throws Exception {
        WxCpMsgAuditService msgAuditService = wxCpService.getMsgAuditService();
        
        // 拉取聊天记录
        List<WxCpChatDatas.WxCpChatData> chatRecords = 
            msgAuditService.getChatRecords(seq, 1000L, null, null, 1000L);
        
        for (WxCpChatDatas.WxCpChatData chatData : chatRecords) {
            seq = chatData.getSeq();
            
            // 获取明文数据
            String plainText = msgAuditService.getChatRecordPlainText(chatData, 2);
            WxCpChatModel model = WxCpChatModel.fromJson(plainText);
            
            // 处理不同类型的消息
            switch (model.getMsgType()) {
                case WxCpConsts.MsgAuditMediaType.TEXT:
                    processTextMessage(model);
                    break;
                    
                case WxCpConsts.MsgAuditMediaType.IMAGE:
                    processImageMessage(model, msgAuditService);
                    break;
                    
                case WxCpConsts.MsgAuditMediaType.FILE:
                    processFileMessage(model, msgAuditService);
                    break;
                    
                default:
                    // 处理其他类型消息
                    break;
            }
        }
    }
    
    private void processTextMessage(WxCpChatModel model) {
        String content = model.getText().getContent();
        System.out.println("文本消息：" + content);
    }
    
    private void processImageMessage(WxCpChatModel model, WxCpMsgAuditService msgAuditService) 
            throws Exception {
        String sdkFileId = model.getImage().getSdkFileId();
        String md5Sum = model.getImage().getMd5Sum();
        String targetPath = "/path/to/save/" + md5Sum + ".jpg";
        
        // 下载图片（无需传入SDK）
        msgAuditService.downloadMediaFile(sdkFileId, null, null, 1000L, targetPath);
        System.out.println("图片已保存：" + targetPath);
    }
    
    private void processFileMessage(WxCpChatModel model, WxCpMsgAuditService msgAuditService) 
            throws Exception {
        String sdkFileId = model.getFile().getSdkFileId();
        String fileName = model.getFile().getFileName();
        String targetPath = "/path/to/save/" + fileName;
        
        // 下载文件（无需传入SDK）
        msgAuditService.downloadMediaFile(sdkFileId, null, null, 1000L, targetPath);
        System.out.println("文件已保存：" + targetPath);
    }
}

使用Lambda处理媒体文件流

新API同样支持使用Lambda表达式处理媒体文件的数据流：

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

技术实现原理

引用计数机制

新API在内部实现了SDK引用计数机制：

1. 获取SDK时：引用计数 +1
2. 使用完成后：引用计数 -1
3. 计数归零时：SDK被自动释放

// 框架内部实现（简化版）
public void downloadMediaFile(String sdkFileId, ...) {
    long sdk = initSdk();  // 获取或初始化SDK
    configStorage.incrementMsgAuditSdkRefCount(sdk);  // 引用计数 +1
    
    try {
        // 执行实际操作
        getMediaFile(sdk, sdkFileId, ...);
    } finally {
        // 确保引用计数一定会减少
        configStorage.decrementMsgAuditSdkRefCount(sdk);  // 引用计数 -1
    }
}

SDK缓存机制

SDK初始化后会缓存7200秒（企业微信官方文档规定），避免频繁初始化：

• 首次调用：初始化新的SDK
• 7200秒内：复用缓存的SDK
• 超过7200秒：重新初始化SDK

新API的引用计数机制与缓存机制完美配合，确保SDK不会被提前销毁。

迁移指南

第一步：使用新API替换旧API

查找代码中的旧API调用：

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

替换为对应的新API（参考前面的对照表）。

第二步：移除手动SDK管理代码

删除所有 Finance.DestroySdk() 调用，SDK生命周期由框架自动管理。

第三步：测试验证

1. 在测试环境验证新API功能正常
2. 观察日志，确认没有SDK相关的错误
3. 进行压力测试，验证多线程环境下的稳定性

常见问题

Q1: 旧代码会立即停止工作吗？

A: 不会。旧API被标记为 @Deprecated，但仍然可用，只是不推荐继续使用。建议尽快迁移到新API以避免潜在问题。

Q2: 如何知道SDK是否被正确释放？

A: 框架会自动管理SDK生命周期，开发者无需关心。如果需要调试，可以查看配置存储中的引用计数。

Q3: 多线程环境下新API安全吗？

A: 是的。新API使用了引用计数机制，配合 synchronized 关键字，确保多线程环境下的安全性。

Q4: 性能会受影响吗？

A: 不会。新API在实现上增加了引用计数的开销，但这是轻量级的操作（原子操作），对性能影响可以忽略不计。SDK缓存机制保持不变。

Q5: 可以同时使用新旧API吗？

A: 技术上可以，但强烈不推荐。混用可能导致SDK生命周期管理混乱，建议统一使用新API。

相关链接

• 企业微信会话存档官方文档
• WxJava GitHub 仓库
• 问题反馈

版本要求

• 最低版本: 4.8.0
• 推荐版本: 最新版本

反馈与支持

如果在使用过程中遇到问题，请：

1. 查看本文档的常见问题部分
2. 在 GitHub 上提交 Issue
3. 加入微信群获取社区支持

---

最后更新时间: 2026-01-14