13 KiB
动作和自动化功能技术选型 ADR
元数据
- 需求编号：004
- 子需求编号：004-05
- 子需求名称：动作和自动化
- 阶段：阶段 3：方案决策
- 创建时间：2026-01-28
- 创建人：AI Assistant
- 状态：已接受
相关文档
1. 背景和问题陈述
1.1 背景
Tooling API 提供了丰富的动作和自动化功能，包括动作覆盖（ActionOverride）、可操作列表（ActionableList）、动作覆盖类型（ActionOverrideType）、动作子类型（ActionSubtype）、可操作列表类型（ActionableListType）、可操作列表源类型（ActionableListSourceType）、动作任务分配类型（ActionTaskAssignedToTypes）、动作 HTTP 方法（ActionHttpMethod）、动作邮件发送者类型（ActionEmailSenderType）等。这些功能可以帮助开发者自定义 Salesforce 的用户界面行为，包括覆盖标准按钮、创建自定义列表视图、配置自动化任务等。
1.2 问题陈述
在实现动作和自动化功能时，需要解决以下关键技术问题：
- 连接管理：如何高效地管理 Tooling API 连接，避免重复创建连接
- 日志记录：如何记录动作和自动化操作日志，支持操作审计和故障排查
- 异常处理：如何统一处理各种异常情况，提供友好的错误信息
- SOQL 查询：如何构建 SOQL 查询语句，简化查询逻辑
- 性能优化：如何避免日志记录影响主流程性能
1.3 约束条件
- 必须复用子需求 004-01 的 ToolingConnectionFactory
- 必须使用数据库表记录动作和自动化操作日志
- 必须使用 datai-salesforce-common 模块的异常体系
- 必须提供 REST API 接口
- 必须支持动作覆盖管理（创建、查询、更新、删除）
- 必须支持可操作列表查询
- 必须支持各种枚举类型查询（动作覆盖类型、动作子类型、可操作列表类型等）
2. 决策驱动因素
2.1 技术驱动因素
- 复用现有基础设施：复用 ToolingConnectionFactory，避免重复实现连接管理逻辑
- 性能要求：日志记录不能影响主流程性能
- 可维护性：代码结构清晰，易于维护和扩展
- 可测试性：易于编写单元测试和集成测试
- 可扩展性：预留扩展点，支持未来新增动作和自动化功能
2.2 业务驱动因素
- 操作审计：所有动作和自动化操作必须记录到数据库，支持审计和故障排查
- 用户体验：提供友好的错误信息，便于用户理解和排查问题
- 功能完整性：支持所有动作和自动化功能，包括动作覆盖管理、可操作列表查询、各种枚举类型查询
2.3 团队驱动因素
- 开发效率：利用现有基础设施，快速实现功能
- 学习成本：使用熟悉的技术栈，降低学习成本
- 协作效率：与项目现有架构保持一致，便于团队协作
3. 考虑的方案
方案 1：Service + ToolingConnectionFactory + 异步日志记录
描述：
- 复用 ToolingConnectionFactory 获取连接
- 使用 CompletableFuture 异步记录操作日志
- 使用 SoqlBuilder 构建 SOQL 查询
- 提供完整的 REST API 接口
优点：
- 复用现有基础设施，开发效率高
- 异步日志记录不影响主流程性能
- 统一异常处理，错误信息友好
- SOQL 查询构建简单，易于维护
- 与项目现有架构保持一致
缺点：
- 需要管理异步线程池
- 日志记录失败不影响主流程，可能丢失日志
适用场景：
- 需要高性能的场景
- 日志记录不是关键业务的场景
方案 2：Service + ToolingConnectionFactory + 同步日志记录
描述：
- 复用 ToolingConnectionFactory 获取连接
- 同步记录操作日志到数据库
- 使用 SoqlBuilder 构建 SOQL 查询
- 提供完整的 REST API 接口
优点：
- 实现简单，易于理解
- 日志记录可靠，不会丢失
- 与项目现有架构保持一致
缺点：
- 日志记录影响主流程性能
- 数据库故障可能导致主流程失败
- 并发场景下性能较差
适用场景：
- 日志记录是关键业务的场景
- 性能要求不高的场景
方案 3：Service + ToolingConnectionFactory + 消息队列日志记录
描述：
- 复用 ToolingConnectionFactory 获取连接
- 使用消息队列（如 RabbitMQ、Kafka）异步记录操作日志
- 使用 SoqlBuilder 构建 SOQL 查询
- 提供完整的 REST API 接口
优点：
- 异步日志记录不影响主流程性能
- 消息队列保证日志记录的可靠性
- 支持高并发场景
- 可以扩展为分布式架构
缺点：
- 需要部署和维护消息队列
- 增加系统复杂度
- 需要额外的监控和运维成本
- 开发成本较高
适用场景：
- 高并发场景
- 日志记录可靠性要求极高的场景
- 分布式架构场景
方案 4：Service + ToolingConnectionFactory + 仅记录失败日志
描述：
- 复用 ToolingConnectionFactory 获取连接
- 仅记录失败的操作日志到数据库
- 使用 SoqlBuilder 构建 SOQL 查询
- 提供完整的 REST API 接口
优点：
- 减少数据库写入量，提高性能
- 实现简单，易于理解
- 与项目现有架构保持一致
缺点：
- 无法完整审计所有操作
- 无法统计操作成功率
- 无法追踪成功操作的历史记录
适用场景：
- 性能要求极高的场景
- 只需要追踪失败操作的场景
方案 5：Service + ToolingConnectionFactory + 文件日志记录
描述：
- 复用 ToolingConnectionFactory 获取连接
- 将操作日志写入文件（如 JSON、CSV）
- 使用 SoqlBuilder 构建 SOQL 查询
- 提供完整的 REST API 接口
优点：
- 文件写入性能高
- 不占用数据库资源
- 实现简单，易于理解
缺点：
- 文件日志不便于查询和分析
- 文件管理复杂，需要定期清理
- 不支持分布式架构
- 无法与其他系统集成
适用场景：
- 日志记录主要用于故障排查的场景
- 不需要查询和分析日志的场景
4. 决策结果
4.1 选定方案
选择方案 1：Service + ToolingConnectionFactory + 异步日志记录
4.2 决策理由
-
复用现有基础设施：复用子需求 004-01 的 ToolingConnectionFactory 获取连接，避免重复实现连接管理逻辑
-
异步日志记录：使用 CompletableFuture 异步记录操作日志，不影响主流程性能
-
统一异常处理：使用 datai-salesforce-common 模块的异常体系，统一处理各种异常情况
-
SOQL 查询支持：使用 SoqlBuilder 构建 SOQL 查询语句，简化查询逻辑
-
开发效率高：利用现有的基础设施，可以快速实现动作和自动化功能
-
维护成本低：与项目现有架构保持一致，与 Partner API、Apex API、Metadata API 的实现方式一致
-
性能优秀：异步日志记录不影响主流程性能，连接复用提高性能
-
审计追溯完善：所有动作和自动化操作记录到数据库，便于审计和故障排查
-
可扩展性强：预留扩展点，支持未来新增动作和自动化功能
-
符合团队习惯：使用熟悉的技术栈，降低学习成本
5. 正面后果
5.1 技术方面
- 性能优秀：异步日志记录不影响主流程性能，连接复用提高性能
- 可维护性强：代码结构清晰，易于维护和扩展
- 可测试性好：易于编写单元测试和集成测试
- 可扩展性强：预留扩展点，支持未来新增动作和自动化功能
5.2 业务方面
- 操作审计完善：所有动作和自动化操作记录到数据库，支持审计和故障排查
- 用户体验良好：提供友好的错误信息，便于用户理解和排查问题
- 功能完整：支持所有动作和自动化功能，包括动作覆盖管理、可操作列表查询、各种枚举类型查询
5.3 团队方面
- 开发效率高：利用现有基础设施，快速实现功能
- 学习成本低：使用熟悉的技术栈，降低学习成本
- 协作效率高：与项目现有架构保持一致，便于团队协作
6. 负面后果
6.1 技术方面
- 需要管理异步线程池：需要配置和管理异步线程池，增加一定的复杂度
- 日志记录可能丢失：异步日志记录失败不影响主流程，但可能导致日志丢失
6.2 业务方面
- 日志记录不是实时：异步日志记录可能导致日志不是实时写入数据库
6.3 团队方面
- 需要监控异步任务：需要监控异步日志记录的任务状态，及时发现和处理问题
7. 替代方案分析
7.1 方案 2：同步日志记录
为什么不选择：
- 日志记录影响主流程性能
- 数据库故障可能导致主流程失败
- 并发场景下性能较差
适用场景：
- 日志记录是关键业务的场景
- 性能要求不高的场景
7.2 方案 3：消息队列日志记录
为什么不选择：
- 需要部署和维护消息队列，增加系统复杂度
- 需要额外的监控和运维成本
- 开发成本较高
适用场景：
- 高并发场景
- 日志记录可靠性要求极高的场景
- 分布式架构场景
7.3 方案 4：仅记录失败日志
为什么不选择：
- 无法完整审计所有操作
- 无法统计操作成功率
- 无法追踪成功操作的历史记录
适用场景：
- 性能要求极高的场景
- 只需要追踪失败操作的场景
7.4 方案 5：文件日志记录
为什么不选择：
- 文件日志不便于查询和分析
- 文件管理复杂，需要定期清理
- 不支持分布式架构
- 无法与其他系统集成
适用场景：
- 日志记录主要用于故障排查的场景
- 不需要查询和分析日志的场景
8. 实施计划
8.1 阶段 1：数据库设计（待进行）
- 创建动作和自动化操作日志表（datai_tooling_action_automation_log）
- 设计索引，优化查询性能
8.2 阶段 2：代码生成（待进行）
- 实现 Service 层（IToolingActionAutomationService、ToolingActionAutomationServiceImpl）
- 实现 Controller 层（ToolingActionAutomationController）
- 实现 DTO、VO、Entity、Mapper
- 实现错误码枚举（ToolingActionErrorCode）
- 编写单元测试
8.3 阶段 3：测试验证（待进行）
- 单元测试验证
- 集成测试验证
- 性能测试验证
8.4 阶段 4：文档更新（待进行）
- 更新 API 文档
- 更新变更日志
- 更新会话记录
9. 风险和缓解措施
9.1 风险 1：异步日志记录失败导致日志丢失
缓解措施：
- 使用可靠的异步线程池配置
- 监控异步任务执行状态
- 定期检查日志记录完整性
9.2 风险 2：异步线程池配置不当导致性能问题
缓解措施：
- 根据实际负载调整线程池参数
- 监控线程池使用情况
- 提供线程池配置接口，支持动态调整
9.3 风险 3：数据库性能瓶颈
缓解措施：
- 设计合理的索引
- 定期清理历史日志数据
- 考虑使用数据库分库分表
10. 监控和运维
10.1 监控指标
-
性能指标：
- API 响应时间
- 异步日志记录耗时
- 数据库查询耗时
-
业务指标：
- 动作和自动化操作成功率
- 动作和自动化操作失败率
- 日志记录成功率
-
系统指标：
- 异步线程池使用率
- 数据库连接数
- 系统资源使用率
10.2 告警规则
-
性能告警：
- API 响应时间 > 2s
- 异步日志记录耗时 > 1s
- 数据库查询耗时 > 500ms
-
业务告警：
- 动作和自动化操作失败率 > 5%
- 日志记录失败率 > 1%
-
系统告警：
- 异步线程池使用率 > 80%
- 数据库连接数 > 80%
11. 审批记录
| 角色 | 姓名 | 审批意见 | 审批时间 |
|---|---|---|---|
| 架构师 | - | 已接受 | 2026-01-28 |
| 技术负责人 | - | 已接受 | 2026-01-28 |
| 产品负责人 | - | 已接受 | 2026-01-28 |