datai/datai-scenes/datai-scene-salesforce/docs/decisions/2026-02-02-002-01-ADR-Apex连接管理技术选型.md

ADR-002-01: Apex 连接管理技术选型

状态

已接受

日期

2026-02-02

背景

Apex 连接管理是 Salesforce Apex API 集成的核心功能，需要设计一个可靠、高效的连接管理方案。该功能需要满足以下要求：

1. 连接工厂：创建和管理 SoapConnection 实例
2. 会话头管理：设置和更新 SessionHeader
3. 调用选项：配置 CallOptions 头部
4. 调试头部：配置 DebuggingHeader 用于调试
5. 字段截断头：配置 AllowFieldTruncationHeader
6. 包版本头：配置 PackageVersionHeader
7. 连接缓存：避免重复创建连接，提高性能
8. 自动 Session 检查：工厂自动检查 Session 有效性，过期时自动清除缓存
9. 线程安全：支持多线程环境下的连接获取
10. RESTful API：提供标准的 REST API 接口
11. 异常处理：统一处理各种异常情况
12. 固定使用 source org：所有方法固定使用 source org 类型

决策

选择方案 1：使用 AbstractConnectionFactory + SessionManager，理由如下：

1. 复用现有基础设施：AbstractConnectionFactory 已经提供了连接缓存和自动 Session 有效性检查功能，可以直接继承使用，减少重复代码
2. 与 SessionManager 深度集成：SessionManager 已经实现了会话管理和自动重新登录功能，可以直接调用其方法获取会话信息
3. 开发效率高：利用现有的基础设施，可以快速实现连接管理功能，缩短开发周期
4. 维护成本低：AbstractConnectionFactory 和 SessionManager 已经在项目中使用，经过充分测试，稳定性高
5. 线程安全：AbstractConnectionFactory 使用 ReentrantLock 保证多线程环境下的连接获取安全
6. 符合项目架构：与 datai-salesforce-auth 模块的架构设计保持一致
7. 与 Partner 模块保持一致：Partner 模块已经使用相同的架构模式，Apex 模块采用相同模式可以保持代码一致性

后果

正面影响

1. 开发效率高：利用现有的 AbstractConnectionFactory 和 SessionManager，可以快速实现连接管理功能
2. 代码复用率高：避免重复实现连接缓存和 Session 有效性检查功能
3. 维护成本低：AbstractConnectionFactory 和 SessionManager 已经在项目中使用，经过充分测试，稳定性高
4. 性能优秀：连接缓存机制避免重复创建连接，提高性能
5. 线程安全：使用 ReentrantLock 保证多线程环境下的连接获取安全
6. 架构一致：与 datai-salesforce-auth 模块和 Partner 模块的架构设计保持一致
7. 学习成本低：开发人员已经熟悉 Partner 模块的实现方式，可以快速上手 Apex 模块

负面影响

1. 依赖关系：需要依赖 datai-salesforce-auth 模块，增加了模块间的耦合度
2. 灵活性降低：如果 AbstractConnectionFactory 或 SessionManager 的功能不满足需求，需要修改基础模块
3. source org 限制：固定使用 source org 类型，无法灵活切换 org 类型

替代方案

方案 2：自定义工厂模式

• 技术选型：自定义 ApexConnectionFactory，不继承 AbstractConnectionFactory
• 优点：
  • 完全独立，不依赖 datai-salesforce-auth 模块
  • 灵活性高，可以根据需求定制功能
  • 可以实现更复杂的连接管理逻辑
• 缺点：
  • 需要自己实现连接缓存和 Session 有效性检查，开发成本高
  • 需要自己实现多线程安全机制
  • 代码复用率低，维护成本高
  • 与项目现有架构不一致
  • 与 Partner 模块的实现方式不一致，增加学习成本
• 适用场景：对连接管理有特殊需求，现有基础设施无法满足的项目

方案 3：每次调用创建新连接

• 技术选型：不使用连接缓存，每次调用都创建新的 SoapConnection
• 优点：
  • 实现简单，不需要考虑连接缓存和 Session 有效性检查
  • 完全独立，不依赖其他模块
  • 不需要处理并发问题
• 缺点：
  • 性能差，每次创建连接都需要消耗资源
  • Session 过期后无法自动处理
  • 不支持多线程环境
  • 不符合最佳实践
  • 在高并发场景下会导致性能瓶颈
• 适用场景：对性能要求不高，调用频率很低的项目

方案 4：使用 Spring 的 Connection Pool

• 技术选型：使用 Spring 的 DataSource 或自定义连接池管理 SoapConnection
• 优点：
  • 可以利用 Spring 的连接池管理功能
  • 支持连接池配置（最大连接数、超时时间等）
  • 可以监控连接池状态
• 缺点：
  • SoapConnection 不是标准的数据库连接，Spring 的连接池不完全适用
  • 需要自定义连接池适配器，开发成本高
  • 与项目现有架构不一致
  • 增加了系统的复杂性
• 适用场景：需要精细控制连接池行为的项目

相关文档

• 需求文档
• 设计文档