kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/decisions/2026-01-28-004-01-ADR-连接管理技术选型.md

7.8 KiB
Raw Permalink Blame History

ADR-004-01: Tooling API 连接管理技术选型

状态

已接受

日期

2026-01-28

背景

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

  1. 会话管理：集成 SessionManager 获取 Session ID 和 Server URL
  2. 连接缓存：避免重复创建连接，提高性能
  3. 自动 Session 检查：工厂自动检查 Session 有效性，过期时自动清除缓存
  4. 线程安全：支持多线程环境下的连接获取
  5. 头部配置：支持 SessionHeader、CallOptions、DebuggingHeader 等头部配置
  6. 日志记录：所有连接操作记录到数据库
  7. RESTful API：提供标准的 REST API 接口
  8. 异常处理：统一处理各种异常情况

决策

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

  1. 复用现有基础设施：AbstractConnectionFactory 已经提供了连接缓存和自动 Session 有效性检查功能，可以直接继承使用，减少重复代码
  2. 与 SessionManager 深度集成：SessionManager 已经实现了会话管理和自动重新登录功能，可以直接调用其方法获取会话信息
  3. 开发效率高：利用现有的基础设施，可以快速实现连接管理功能，缩短开发周期
  4. 维护成本低：AbstractConnectionFactory 和 SessionManager 已经在项目中使用，经过充分测试，稳定性高
  5. 线程安全：AbstractConnectionFactory 使用 ReentrantLock 保证多线程环境下的连接获取安全
  6. 符合项目架构：与 datai-salesforce-auth 模块的架构设计保持一致，与 Partner API、Apex API、Metadata API 的实现方式一致
  7. 头部配置灵活：支持 SessionHeader、CallOptions、DebuggingHeader 等头部配置，满足不同场景需求
  8. 日志记录完善：所有连接操作记录到 datai_tooling_connection_log 表，便于审计和故障排查

后果

正面影响

  1. 开发效率高：利用现有的 AbstractConnectionFactory 和 SessionManager，可以快速实现连接管理功能
  2. 代码复用率高：避免重复实现连接缓存、Session 有效性检查、线程安全等功能
  3. 维护成本低：AbstractConnectionFactory 和 SessionManager 已经在项目中使用，经过充分测试，稳定性高
  4. 性能优秀：连接缓存机制避免重复创建连接，提高性能
  5. 线程安全：使用 ReentrantLock 保证多线程环境下的连接获取安全
  6. 架构一致：与 datai-salesforce-auth 模块的架构设计保持一致，与 Partner API、Apex API、Metadata API 的实现方式一致
  7. 头部配置灵活：支持 SessionHeader、CallOptions、DebuggingHeader 等头部配置，满足不同场景需求
  8. 日志记录完善：所有连接操作记录到数据库，便于审计和故障排查

负面影响

  1. 依赖关系：需要依赖 datai-salesforce-auth 模块，增加了模块间的耦合度
  2. 灵活性降低：如果 AbstractConnectionFactory 或 SessionManager 的功能不满足需求，需要修改基础模块
  3. 学习成本：需要理解 AbstractConnectionFactory 和 SessionManager 的工作原理

替代方案

方案 2：自定义工厂模式

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

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

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

方案 4：使用连接池

  • 技术选型：使用 Apache Commons Pool 或 HikariCP 实现连接池
  • 优点：
    • 连接复用率高，性能优秀
    • 支持连接池的动态扩容和缩容
    • 支持连接的健康检查
  • 缺点：
    • 实现复杂，需要配置连接池参数
    • 与 Salesforce Tooling API 的连接模型不完全匹配
    • 增加系统复杂度
    • 需要额外处理 Session 过期问题
  • 适用场景：高并发场景，需要管理大量连接的项目

相关文档

决策记录

决策过程

  1. 分析需求：根据需求文档，确定需要实现 Tooling API 连接管理功能，包括连接获取、缓存管理、头部配置、日志记录等
  2. 技术调研：调研了四种技术方案：AbstractConnectionFactory + SessionManager、自定义工厂、每次创建新连接、连接池
  3. 方案对比：
    • 方案 1（AbstractConnectionFactory + SessionManager）：开发效率高、代码复用率高、维护成本低、性能优秀
    • 方案 2（自定义工厂）：灵活性高，但开发成本高、维护成本高
    • 方案 3（每次创建新连接）：实现简单，但性能差、不符合最佳实践
    • 方案 4（连接池）：性能优秀，但实现复杂、与 Tooling API 连接模型不完全匹配
  4. 最终决策：选择方案 1，因为与项目现有架构一致，可以复用现有基础设施，开发效率高，维护成本低

关键决策点

  1. 继承 AbstractConnectionFactory：复用连接缓存和 Session 有效性检查功能
  2. 使用 SessionManager：复用会话管理和自动重新登录功能
  3. 支持头部配置：SessionHeader、CallOptions、DebuggingHeader
  4. 日志记录：所有连接操作记录到 datai_tooling_connection_log 表
  5. 固定使用 source ORG 类型：与需求一致，默认实现源 org 类型

风险评估

  1. 依赖风险：依赖 datai-salesforce-auth 模块，如果该模块出现问题，会影响 Tooling API 连接管理功能
    • 缓解措施：AbstractConnectionFactory 和 SessionManager 已经在项目中广泛使用，经过充分测试，稳定性高
  2. 性能风险：连接缓存可能导致内存占用增加
    • 缓解措施：连接缓存使用 ConcurrentHashMap，内存占用可控；支持手动清除缓存
  3. 安全风险：Session ID 存储在内存中，可能存在安全风险
    • 缓解措施：Session ID 只存储在服务端内存中，不暴露给客户端；支持手动清除缓存

后续行动

  1. 实现 ToolingConnectionFactory 类，继承 AbstractConnectionFactory
  2. 实现 ToolingConnectionService 接口和实现类
  3. 实现 ToolingConnectionController 类，提供 REST API 接口
  4. 创建 datai_tooling_connection_log 表，记录连接操作日志
  5. 实现 ToolingConnectionErrorCode 枚举，定义错误码
  6. 编写单元测试和集成测试

更新日志

版本 日期 更新内容 作者
1.0.0 2026-01-28 初始版本，记录 Tooling API 连接管理技术选型决策 AI Assistant