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-30-003-ADR-批量操作技术选型.md

5.1 KiB
Raw Permalink Blame History

ADR-003: 批量操作技术选型

状态

已接受

日期

2026-01-30

背景

批量操作是 Salesforce Partner API 的重要功能，需要设计一个可靠、高效的批量操作方案。该功能需要满足以下要求：

  1. 分层架构：符合若依框架规范，采用分层架构（Controller、Service、DTO、VO）
  2. 自动分批处理：支持最多 1000 条记录，每批最多 200 条，自动分批处理
  3. 批量操作行为控制：支持 AllOrNoneHeader 控制批量操作行为
  4. 性能优化：使用 DisableFeedTrackingHeader 提高性能，批次间添加休眠时间避免 API 限流
  5. 异常处理：统一处理各种异常情况，使用 datai-salesforce-common 模块的异常体系
  6. 参数验证：完善的参数验证，提高数据安全性
  7. RESTful API：提供标准的 REST API 接口
  8. 代码质量：代码符合项目规范，便于维护和扩展

决策

选择方案 1：完整分层架构 + 自动分批处理 + 性能优化，理由如下：

  1. 符合若依框架规范：若依框架采用分层架构，创建完整的 Controller、Service、DTO、VO 层符合框架规范，便于团队协作和维护
  2. 支持大规模数据处理：自动分批处理支持最多 1000 条记录，每批最多 200 条，满足大规模数据处理需求
  3. 支持部分失败情况：默认不使用 AllOrNoneHeader，支持部分失败情况，提高容错性
  4. 性能优化完善：使用 DisableFeedTrackingHeader 提高性能，批次间添加休眠时间（默认 100ms）避免 API 限流
  5. 异常处理统一：统一的异常处理机制便于调试和维护，提高系统的稳定性
  6. 参数验证完善：完善的参数验证提高数据安全性，防止无效数据进入系统
  7. 符合项目长期规划：项目计划实现所有 Partner API 功能，完整的分层架构为后续功能扩展提供良好的基础
  8. 与已有 ADR 一致：与 ADR-001（认证和会话管理）和 ADR-002（CRUD 操作）的架构决策保持一致

后果

正面影响

  1. 代码结构清晰：完整的分层架构使代码结构清晰，便于理解和维护
  2. 符合框架规范：符合若依框架规范，便于团队协作和代码复用
  3. 性能优化：自动分批处理、DisableFeedTrackingHeader、批次间休眠等性能优化措施显著提高性能
  4. 可维护性高：职责分离明确，便于后续功能扩展和维护
  5. 数据安全性高：完善的参数验证提高数据安全性，防止无效数据进入系统
  6. 异常处理统一：统一的异常处理机制便于调试和维护，提高系统的稳定性
  7. 容错性高：支持部分失败情况，提高系统的容错性
  8. 为后续功能扩展提供良好基础：完整的分层架构为后续功能扩展（如查询功能、描述功能等）提供良好的基础
  9. 架构一致：与 ADR-001 和 ADR-002 的架构决策保持一致，保证项目架构的统一性

负面影响

  1. 开发成本高：代码量较多，开发成本高
  2. 性能略有影响：DTO 和 VO 转换可能影响性能（但影响很小）
  3. 复杂度较高：自动分批处理逻辑需要仔细实现，增加了代码复杂度

替代方案

方案 2：简化架构 + 固定批量大小

技术选型：

  • 创建 PartnerBatchController、PartnerBatchService
  • 不使用 DTO 和 VO，直接使用 Map
  • 固定批量大小 200 条，不支持自动分批处理
  • 使用 AllOrNoneHeader，全有或全无模式
  • 不使用 DisableFeedTrackingHeader
  • 不使用批次间休眠

优点：

  • 架构简单，易于理解
  • 开发速度快
  • 实现逻辑简单
  • 批量操作行为明确

缺点：

  • 不符合若依框架规范
  • 不支持大规模数据处理（最多 200 条记录）
  • 批量操作行为不够灵活（全有或全无模式）
  • 性能优化不足（不使用 DisableFeedTrackingHeader 和批次间休眠）
  • 参数验证不完善
  • 扩展性受限
  • 与已有 ADR 不一致

适用场景：

  • 小型项目，对批量操作需求简单的项目
  • 对性能要求不高的项目

方案 3：使用若依框架通用批量操作

技术选型：

  • 使用若依框架通用批量操作功能
  • 不创建专门的批量操作模块
  • 不支持自动分批处理
  • 不支持 AllOrNoneHeader
  • 不支持 DisableFeedTrackingHeader
  • 不支持批次间休眠

优点：

  • 开发速度快
  • 若依框架提供通用批量操作功能

缺点：

  • 不符合 Salesforce API 的特殊性
  • 难以满足定制化需求
  • 不支持自动分批处理
  • 性能优化不足
  • 异常处理不完善
  • 参数验证不完善
  • 与已有 ADR 不一致

适用场景：

  • 对批量操作需求简单的项目
  • 对性能要求不高的项目

相关文档