4.0 KiB
4.0 KiB
ADR-002: CRUD 操作技术选型
状态
已接受
日期
2026-01-30
背景
CRUD 操作是 Salesforce Partner API 的核心功能，需要设计一个可靠、高效的 CRUD 操作方案。该功能需要满足以下要求：
- 分层架构：符合若依框架规范，采用分层架构（Controller、Service、DTO、VO）
- 批量操作：支持批量操作（Create、Update、Delete、Upsert），减少网络往返次数
- 数据转换：将 Map<String, Object> 转换为 SObject 对象
- 异常处理：统一处理各种异常情况，使用 datai-salesforce-common 模块的异常体系
- 参数验证：完善的参数验证，提高数据安全性
- RESTful API：提供标准的 REST API 接口
- 代码质量：代码符合项目规范，便于维护和扩展
决策
选择方案 1：完整分层架构 + 批量操作支持，理由如下：
- 符合若依框架规范：若依框架采用分层架构，创建完整的 Controller、Service、DTO、VO 层符合框架规范，便于团队协作和维护
- 便于维护和扩展：完整的分层架构和职责分离使代码更易于理解和维护，便于后续功能扩展
- 支持批量操作：批量操作可以显著减少网络往返次数，提高性能，特别是在大数据量场景下
- 异常处理统一：统一的异常处理机制便于调试和维护，提高系统的稳定性
- 参数验证完善：完善的参数验证提高数据安全性，防止无效数据进入系统
- 符合项目长期规划：项目计划实现所有 Partner API 功能，完整的分层架构为后续功能扩展提供良好的基础
后果
正面影响
- 代码结构清晰：完整的分层架构使代码结构清晰，便于理解和维护
- 符合框架规范：符合若依框架规范，便于团队协作和代码复用
- 性能优化：批量操作可以显著减少网络往返次数，提高性能
- 可维护性高：职责分离明确，便于后续功能扩展和维护
- 数据安全性高：完善的参数验证提高数据安全性，防止无效数据进入系统
- 异常处理统一：统一的异常处理机制便于调试和维护，提高系统的稳定性
- 为后续功能扩展提供良好基础：完整的分层架构为后续功能扩展（如批量操作、查询功能、描述功能等）提供良好的基础
负面影响
- 开发成本高：代码量较多，开发成本高
- 性能略有影响：DTO 和 VO 转换可能影响性能（但影响很小）
替代方案
方案 2：简化架构 + 不支持批量操作
技术选型：
- 创建 PartnerCrudController、PartnerCrudService
- 不创建 DTO 和 VO 类，直接使用 Map 和 Object
- 不创建 SObjectConverter 工具类
- 仅支持单个操作
优点：
- 代码量少，开发成本低
- 减少对象转换，性能更好
- 实现简单，易于理解
缺点：
- 代码结构不清晰，不符合若依框架规范
- 不便于维护和扩展
- 不支持批量操作，性能较差
- 参数验证不完善，数据安全性低
- 异常处理不统一，难以调试和维护
适用场景：
- 对开发速度要求较高的项目
- 对性能要求极高的项目（但批量操作通常比单个操作性能更好）
- 对代码质量和可维护性要求不高的项目
方案 3：使用若依框架的通用 CRUD 功能
技术选型：
- 使用若依框架的通用 CRUD 功能（如 BaseMapper、BaseService）
- 不创建独立的 Service 层
- 不创建 DTO 和 VO 类
优点：
- 复用若依框架的通用功能，减少重复代码
- 开发效率高
缺点：
- 不符合 Salesforce API 的特殊性
- 难以满足定制化需求
- 不支持批量操作
- 不支持 Salesforce 特有的功能（如 Upsert、Merge）
适用场景：
- 对 Salesforce API 集成要求不高的项目
- 对定制化要求不高的项目