datai/datai-scenes/datai-scene-salesforce/docs/decisions/2026-02-03-002-07-ADR-WSDL转换技术选型.md

ADR-002-07: WSDL 转换技术选型

状态

已接受

日期

2026-02-03

背景

WSDL 转换功能需要选择合适的技术方案，满足以下要求：

1. 支持从 URL 和 XML 两种方式转换 WSDL 到 Apex 代码
2. 支持查询转换历史和转换详情
3. 支持下载生成的 Apex 类代码（单个和批量）
4. 保证多线程安全
5. 与现有 Apex 功能（002-02、002-03、002-06）保持一致
6. 支持历史数据查询和审计

决策

决策 1：数据持久化策略

选择方案 1：数据库持久化（MySQL）

理由如下：

1. 与项目现有技术栈（MyBatis Plus、MySQL）集成良好
2. 与其他 Apex 功能（002-02、002-03、002-06）的数据持久化策略保持一致
3. 支持历史数据查询和审计需求
4. 数据可靠性高，避免内存丢失
5. 支持复杂的查询条件（时间范围、状态筛选等）
6. 支持分页查询，性能可控

放弃方案 2（仅使用内存缓存）的理由：

1. 服务重启后数据丢失，无法满足审计需求
2. 不支持历史数据查询和审计
3. 内存占用随数据量增加
4. 无法满足需要长期保存转换记录的业务场景

决策 2：多线程安全设计

选择方案 1：ReentrantLock

理由如下：

1. 与其他 Apex 功能（002-02、002-03、002-06）使用相同的并发控制机制，保持代码一致性
2. ReentrantLock 比 synchronized 更灵活，支持公平锁、可中断锁等特性
3. 在高并发场景下性能更好
4. 可维护性高，统一的并发控制策略便于维护和问题排查

放弃方案 2（数据库乐观锁）的理由：

1. 与其他 Apex 功能的并发控制机制不一致
2. 性能较低，每次都需要数据库查询和更新
3. 实现复杂度较高

决策 3：转换结果存储方式

选择方案 1：存储完整类代码（LONGTEXT）

理由如下：

1. 一次转换，多次使用，无需重复调用 Salesforce API
2. 性能高，减少网络请求
3. 离线可用，即使 Salesforce 连接失败也能下载
4. 与其他 Apex 功能（002-02、002-03）的结果存储策略保持一致
5. 满足审计需求，完整的 Apex 类代码支持追溯

放弃方案 2（只存储类名，代码从 Salesforce API 获取）的理由：

1. 每次下载都需要调用 Salesforce API，性能较低
2. 依赖 Salesforce 连接，连接失败时无法下载
3. 无法满足离线下载的需求

决策 4：批量下载实现

选择方案 1：Apache Commons Compress

理由如下：

1. 功能强大，支持多种压缩格式（ZIP、TAR、GZ 等）
2. API 简洁，易于使用
3. 社区活跃度高，文档丰富
4. 性能高，经过充分优化
5. 支持自定义压缩级别，可平衡压缩率和性能

放弃方案 2（Java 原生 ZIP）的理由：

1. 功能有限，只支持 ZIP 格式
2. API 相对复杂
3. 性能不如 Apache Commons Compress

后果

正面影响

1. 开发效率高：与现有技术栈（Spring Boot、MyBatis Plus、MySQL）集成良好
2. 数据可靠性高：数据库持久化，服务重启后数据不丢失
3. 查询性能好：支持复杂的查询条件和分页
4. 并发控制一致：与其他 Apex 功能使用相同的并发控制机制，便于维护
5. 下载性能高：存储完整类代码，无需重复调用 Salesforce API
6. 压缩功能强大：Apache Commons Compress 支持多种压缩格式
7. 可维护性高：统一的并发控制和数据持久化策略便于维护和问题排查

负面影响

1. 数据库存储成本高：存储完整类代码需要使用 LONGTEXT 类型，占用较多数据库空间
2. 需要引入额外依赖：Apache Commons Compress 需要作为项目依赖
3. 配置相对复杂：ReentrantLock 需要手动管理锁的获取和释放

替代方案

方案 1：数据持久化策略

方案 1：数据库持久化（MySQL）- 已选择

• 优点：
  • 数据持久化，系统重启后数据不丢失
  • 支持历史查询和审计
  • 便于数据统计和分析
  • 符合项目整体架构风格
• 缺点：
  • 需要设计数据库表结构
  • 需要编写 SQL 脚本
  • 数据库存储成本较高
• 适用场景：需要长期保存转换记录、支持历史查询的场景

方案 2：内存存储

• 优点：
  • 实现简单，无需设计数据库表
  • 性能高，无需数据库 I/O
  • 存储成本低
• 缺点：
  • 系统重启后数据丢失
  • 不支持历史查询和审计
  • 不便于数据统计和分析
• 适用场景：临时性转换、不需要保存历史的场景

方案 2：多线程安全设计

方案 1：ReentrantLock - 已选择

• 优点：
  • 与其他 Apex 功能（002-02、002-03、002-06）使用相同的并发控制机制，保持代码一致性
  • ReentrantLock 比 synchronized 更灵活，支持公平锁、可中断锁等特性
  • 在高并发场景下性能更好
  • 可维护性高，统一的并发控制策略便于维护和问题排查
• 缺点：
  • 需要手动管理锁的获取和释放
  • 容易出现死锁（如果锁使用不当）
• 适用场景：需要细粒度控制的并发场景

方案 2：数据库乐观锁

• 优点：
  • 无需手动管理锁
  • 数据库层面保证一致性
  • 不会出现死锁
• 缺点：
  • 性能较低，每次都需要数据库查询和更新
  • 与其他 Apex 功能的并发控制机制不一致
  • 实现复杂度较高
• 适用场景：需要数据库层面保证一致性的场景

方案 3：转换结果存储方式

方案 1：存储完整类代码（LONGTEXT）- 已选择

• 优点：
  • 一次转换，多次使用，无需重复调用 Salesforce API
  • 性能高，减少网络请求
  • 离线可用，即使 Salesforce 连接失败也能下载
• 缺点：
  • 数据库存储成本高（LONGTEXT 类型）
  • 可能占用大量数据库空间
• 适用场景：需要多次下载生成的 Apex 类代码的场景

方案 2：只存储类名，代码从 Salesforce API 获取

• 优点：
  • 数据库存储成本低
  • 节省数据库空间
• 缺点：
  • 每次下载都需要调用 Salesforce API
  • 性能较低，增加网络请求
  • 依赖 Salesforce 连接，连接失败时无法下载
• 适用场景：存储空间受限、不需要多次下载的场景

方案 4：批量下载实现

方案 1：Apache Commons Compress - 已选择

• 优点：
  • 功能强大，支持多种压缩格式（ZIP、TAR、GZ 等）
  • API 简洁，易于使用
  • 社区活跃度高，文档丰富
  • 性能高，经过充分优化
• 缺点：
  • 需要引入额外的依赖
• 适用场景：需要多种压缩格式支持的场景

方案 2：Java 原生 ZIP

• 优点：
  • 无需引入额外依赖
  • JDK 原生支持
• 缺点：
  • 功能有限，只支持 ZIP 格式
  • API 相对复杂
  • 性能不如 Apache Commons Compress
• 适用场景：只需要 ZIP 格式、不想引入额外依赖的场景

相关文档

• 需求文档
• 设计文档
• Apex代码编译和执行决策记录
• 测试执行决策记录
• 日志记录决策记录