18 KiB
18 KiB
提示词：批量操作
引用真源
需求描述
根据需求文档，实现 Salesforce Partner API 的批量操作功能，包括以下四个核心操作：
- 批量创建（Create）：批量创建 Salesforce 记录，支持最多 1000 条记录，每批最多 200 条，自动分批处理
- 批量更新（Update）：批量更新 Salesforce 记录，支持最多 1000 条记录，每批最多 200 条，自动分批处理
- 批量删除（Delete）：批量删除 Salesforce 记录，支持最多 1000 条记录，每批最多 200 条，自动分批处理
- 批量更新或插入（Upsert）：批量更新或插入 Salesforce 记录，支持最多 1000 条记录，每批最多 200 条，自动分批处理
核心功能要求：
- 支持自动分批处理（最多 1000 条记录，每批最多 200 条）
- 支持详细的成功/失败统计（成功数量、失败数量、创建数量、更新数量）
- 支持 AllOrNoneHeader 控制批量操作行为（默认不使用，支持部分失败）
- 使用 DisableFeedTrackingHeader 提高性能
- 批次间添加休眠时间（默认 100ms），避免 API 限流
- 固定使用 source org 类型（通过
getConnection("source")获取连接） - 返回友好的错误消息（中文）
- 记录详细的错误日志
设计方案
根据设计文档，采用以下技术方案：
-
架构设计：采用分层架构（Controller → Service → Factory → Connection → Salesforce API）
-
技术选型：
- Spring Boot 3.x：主流 Java Web 框架，生态丰富
- Spring Security 6.x：安全框架，支持权限控制
- 若依框架：项目基础框架，提供通用功能
- Salesforce Partner API v65.0：Salesforce 官方 API，支持批量操作
- Lombok：简化代码，减少样板代码
- Swagger/OpenAPI：API 文档自动生成
- JUnit 5：单元测试框架
- Mockito：Mock 测试框架
-
核心算法设计：
- 自动分批处理算法：支持最多 1000 条记录，每批最多 200 条，自动分批处理
- 批量操作行为控制：支持 AllOrNoneHeader 控制批量操作行为（默认不使用）
- 性能优化：使用 DisableFeedTrackingHeader 提高性能，批次间添加休眠时间（默认 100ms）
-
异常处理：
- 捕获 ConnectionException 并转换为自定义异常
- 捕获 ApiFault 并转换为自定义异常
- 返回友好的错误消息（中文）
- 记录详细的错误日志
-
重试机制：
- 暂不实现自动重试（遵循需求）
- 依赖连接工厂的 Session 有效性检查
- Session 过期时自动重新登录
-
安全设计：
- HTTPS 加密传输
- 权限控制（使用若依的
@PreAuthorize注解） - 参数验证（使用 Spring Boot Validation）
- 防注入（避免直接拼接 SQL 或 SOQL）
输出格式要求
-
必须包含以下文件：
- Controller：
PartnerBatchController.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/controller/PartnerBatchController.java） - Service 接口：
IPartnerBatchService.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/service/IPartnerBatchService.java） - Service 实现：
PartnerBatchServiceImpl.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/service/impl/PartnerBatchServiceImpl.java） - DTO：
BatchCreateDto.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/BatchCreateDto.java）BatchUpdateDto.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/BatchUpdateDto.java）BatchDeleteDto.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/BatchDeleteDto.java）BatchUpsertDto.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/BatchUpsertDto.java）
- VO：
BatchResultVo.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/BatchResultVo.java）BatchItemResultVo.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/BatchItemResultVo.java）
- 工具类：
SObjectConverter.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/util/SObjectConverter.java，如果不存在则创建） - 连接工厂：
PartnerConnectionFactory.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/factory/PartnerConnectionFactory.java，如果不存在则创建）
- Controller：
-
必须包含单元测试：
PartnerBatchServiceImplTest.java（路径：datai-salesforce-partner/src/test/java/com/datai/partner/service/impl/PartnerBatchServiceImplTest.java）
-
必须符合 Spring Boot 最佳实践
- 使用
@RestController注解标记 Controller - 使用
@Service注解标记 Service - 使用
@Autowired注解进行依赖注入 - 使用
@Valid注解进行参数验证 - 使用
@Transactional注解进行事务管理（如果需要）
- 使用
-
必须遵循若依框架规范
- 使用若依的
@PreAuthorize注解进行权限控制 - 使用若依的
@Log注解记录操作日志 - 使用若依的
GlobalExceptionHandler处理异常 - 使用若依的
R类封装返回结果
- 使用若依的
-
必须使用 partner.jar 现有类
- 使用
com.sforce.ws.ConnectionException处理连接异常 - 使用
com.sforce.ws.bind.XmlObject处理 SObject - 使用
com.sforce.soap.partner.PartnerConnection进行批量操作 - 使用
com.sforce.soap.partner.SaveResult处理批量创建/更新结果 - 使用
com.sforce.soap.partner.DeleteResult处理批量删除结果 - 使用
com.sforce.soap.partner.UpsertResult处理批量 Upsert 结果 - 使用
com.sforce.soap.partner.sobject.SObject创建 SObject 对象
- 使用
-
必须使用 PartnerConnectionFactory
- 通过
PartnerConnectionFactory.getConnection("source")获取 PartnerConnection 实例 - PartnerConnectionFactory 必须继承 AbstractConnectionFactory
- 使用
ISalesforceConnectionFactory接口
- 通过
-
必须使用异常类
- 使用
datai-salesforce-common模块的异常类（SalesforceAuthException、SalesforceOperationException 等） - 使用
datai-salesforce-common模块的常量类（SalesforceConstants）
- 使用
-
必须使用权限控制
- 使用若依的
@PreAuthorize注解进行权限控制 - 权限标识：
partner:batch:create、partner:batch:update、partner:batch:delete、partner:batch:upsert
- 使用若依的
-
必须使用参数验证
- 使用 Spring Boot Validation 进行参数验证
- 使用
@NotNull、@NotEmpty、@Size等注解验证参数 - 验证失败时返回友好的错误消息（中文）
-
必须使用 Swagger 文档
- 使用
@Tag注解标记 Controller - 使用
@Operation注解标记方法 - 使用
@Parameter注解标记参数 - 使用
@Schema注解标记 DTO 和 VO
- 使用
-
必须使用日志记录
- 使用若依的
@Log注解记录操作日志 - 使用
@Slf4j注解记录详细日志 - 记录批量操作的关键信息（批量大小、成功数量、失败数量等）
- 使用若依的
-
必须使用依赖注入
- 使用
@Autowired注解注入依赖 - 使用构造器注入（推荐）或字段注入
- 使用
-
必须定义 REST API
- 批量创建：
POST /api/partner/batch/create - 批量更新：
POST /api/partner/batch/update - 批量删除：
POST /api/partner/batch/delete - 批量 Upsert：
POST /api/partner/batch/upsert
- 批量创建：
-
必须使用 Lombok 注解
- 使用
@Data注解生成 getter/setter - 使用
@NoArgsConstructor注解生成无参构造器 - 使用
@AllArgsConstructor注解生成全参构造器 - 使用
@Builder注解生成 Builder 模式
- 使用
-
必须实现 SObject 转换
- 使用
SObjectConverter工具类将List<Map<String, Object>>转换为SObject[]数组 - 处理 Map 中的 null 值（不设置到 SObject 中）
- 处理子对象关系（使用点号表示法，如
Account.Name）
- 使用
-
必须实现批量操作限制
- 最多支持 1000 条记录
- 每批最多 200 条记录
- 超过限制时抛出异常（使用 SalesforceOperationException）
-
必须实现字段清空
- 支持清空字段值（使用
fieldsToNull属性） - 使用
#clearField标记需要清空的字段
- 支持清空字段值（使用
-
必须实现子对象关系
- 支持设置子对象关系（使用点号表示法，如
Account.Name） - 支持批量设置子对象关系
- 支持设置子对象关系（使用点号表示法，如
代码规范要求
- 类命名：首字母大写，驼峰命名，如
PartnerBatchController - 方法命名：首字母小写，驼峰命名，如
batchCreate - 变量命名：首字母小写，驼峰命名，如
objectType - 常量命名：全大写，下划线分隔，如
MAX_BATCH_SIZE - 注释规范：
- 类注释：使用
/** */，包含类功能描述、作者、创建时间 - 方法注释：使用
/** */，包含方法功能、参数、返回值、异常描述 - 字段注释：使用
/** */，包含字段功能描述
- 类注释：使用
- 代码格式：使用 4 个空格缩进，行宽不超过 120 字符
- 导入规范：使用 import 静态导入，避免通配符导入
- 异常处理：使用 try-catch-finally 处理异常，确保资源释放
- 日志规范：使用 SLF4J 记录日志，日志级别使用正确（DEBUG、INFO、WARN、ERROR）
测试要求
- 单元测试覆盖率不低于 80%
- 测试用例包含以下场景：
- 批量创建成功（正常场景）
- 批量创建部分失败（部分失败场景）
- 批量创建全部失败（全部失败场景）
- 批量创建超过限制（异常场景）
- 批量更新成功（正常场景）
- 批量更新部分失败（部分失败场景）
- 批量更新全部失败（全部失败场景）
- 批量更新超过限制（异常场景）
- 批量删除成功（正常场景）
- 批量删除部分失败（部分失败场景）
- 批量删除全部失败（全部失败场景）
- 批量删除超过限制（异常场景）
- 批量 Upsert 成功（正常场景）
- 批量 Upsert 部分失败（部分失败场景）
- 批量 Upsert 全部失败（全部失败场景）
- 批量 Upsert 超过限制（异常场景）
- 自动分批处理（正常场景）
- AllOrNoneHeader 控制（正常场景）
- DisableFeedTrackingHeader 使用（正常场景）
- 批次间休眠（正常场景）
- 使用 JUnit 5 和 Mockito 进行测试
- 测试用例命名规范：
test+方法名+场景，如testBatchCreateSuccess - 测试数据使用 Mockito 模拟
- 测试断言使用 AssertJ 或 JUnit 5 的 Assertions
注意事项
-
必须处理 Salesforce API 的空值情况
- 处理 SObject 的 null 值
- 处理 SaveResult、DeleteResult、UpsertResult 的 null 值
- 处理 PartnerConnection 的 null 值
-
必须使用若依的
@DataScope注解进行数据权限控制（如果需要）- 根据业务需求决定是否使用
-
必须使用若依的
@Log注解记录操作日志- 记录批量操作的关键信息（批量大小、成功数量、失败数量等）
-
必须使用若依的
GlobalExceptionHandler处理异常- 捕获自定义异常并返回友好的错误消息（中文）
-
必须使用
getConnection("source")获取连接- 固定使用 source org 类型
- 不要使用 orgType 参数
-
必须实现自动分批处理
- 最多支持 1000 条记录
- 每批最多 200 条记录
- 自动分批处理
-
必须实现性能优化
- 使用 DisableFeedTrackingHeader 提高性能
- 批次间添加休眠时间（默认 100ms），避免 API 限流
-
必须实现详细的成功/失败统计
- 统计成功数量、失败数量、创建数量、更新数量
- 返回详细的结果信息（包括每条记录的结果）
-
必须实现友好的错误消息（中文）
- 错误消息必须清晰、准确
- 错误消息必须包含足够的调试信息
-
必须记录详细的错误日志
- 记录异常堆栈信息
- 记录批量操作的关键信息（批量大小、成功数量、失败数量等）
-
必须使用 Lombok 注解
- 使用
@Data注解生成 getter/setter - 使用
@NoArgsConstructor注解生成无参构造器 - 使用
@AllArgsConstructor注解生成全参构造器 - 使用
@Builder注解生成 Builder 模式
- 使用
-
必须使用 Swagger 文档
- 使用
@Tag注解标记 Controller - 使用
@Operation注解标记方法 - 使用
@Parameter注解标记参数 - 使用
@Schema注解标记 DTO 和 VO
- 使用
-
必须使用 JUnit 5 和 Mockito 进行测试
- 单元测试覆盖率不低于 80%
- 测试用例包含正常场景和异常场景
-
必须遵循若依框架规范
- 使用若依的
@PreAuthorize注解进行权限控制 - 使用若依的
@Log注解记录操作日志 - 使用若依的
GlobalExceptionHandler处理异常 - 使用若依的
R类封装返回结果
- 使用若依的
-
必须使用 Spring Boot 3.x 和 Spring Security 6.x
- 使用 Spring Boot 3.x 的最新特性
- 使用 Spring Security 6.x 的最新特性
-
必须使用 partner.jar 现有类
- 使用
com.sforce.ws.ConnectionException处理连接异常 - 使用
com.sforce.ws.bind.XmlObject处理 SObject - 使用
com.sforce.soap.partner.PartnerConnection进行批量操作 - 使用
com.sforce.soap.partner.SaveResult处理批量创建/更新结果 - 使用
com.sforce.soap.partner.DeleteResult处理批量删除结果 - 使用
com.sforce.soap.partner.UpsertResult处理批量 Upsert 结果 - 使用
com.sforce.soap.partner.sobject.SObject创建 SObject 对象
- 使用
-
必须使用 datai-salesforce-common 模块的异常类
- 使用
SalesforceAuthException处理认证异常 - 使用
SalesforceOperationException处理操作异常 - 使用
SalesforceConstants获取常量值
- 使用
-
必须使用 datai-salesforce-auth 模块的 SessionManager
- 通过 SessionManager 获取 Session ID 和 Server URL
- 自动检查 Session 有效性
- Session 过期时自动重新登录
-
必须实现 SObject 转换工具类
- 使用
SObjectConverter工具类将List<Map<String, Object>>转换为SObject[]数组 - 处理 Map 中的 null 值（不设置到 SObject 中）
- 处理子对象关系（使用点号表示法，如
Account.Name）
- 使用
-
必须实现批量操作限制
- 最多支持 1000 条记录
- 每批最多 200 条记录
- 超过限制时抛出异常（使用 SalesforceOperationException）
-
必须实现字段清空
- 支持清空字段值（使用
fieldsToNull属性） - 使用
#clearField标记需要清空的字段
- 支持清空字段值（使用
-
必须实现子对象关系
- 支持设置子对象关系（使用点号表示法，如
Account.Name） - 支持批量设置子对象关系
- 支持设置子对象关系（使用点号表示法，如
-
必须实现自动分批处理
- 最多支持 1000 条记录
- 每批最多 200 条记录
- 自动分批处理
- 批次间添加休眠时间（默认 100ms），避免 API 限流
-
必须实现性能优化
- 使用 DisableFeedTrackingHeader 提高性能
- 批次间添加休眠时间（默认 100ms），避免 API 限流
-
必须实现 AllOrNoneHeader 控制
- 支持设置 AllOrNoneHeader 控制批量操作行为
- 默认不使用，支持部分失败
- 可选参数，用户可以选择是否使用
-
必须实现详细的成功/失败统计
- 统计成功数量、失败数量、创建数量、更新数量
- 返回详细的结果信息（包括每条记录的结果）
- 返回友好的错误消息（中文）
-
必须记录详细的错误日志
- 记录异常堆栈信息
- 记录批量操作的关键信息（批量大小、成功数量、失败数量等）
- 记录每条记录的结果（成功或失败）
-
必须实现友好的错误消息（中文）
- 错误消息必须清晰、准确
- 错误消息必须包含足够的调试信息
- 错误消息必须包含批量操作的关键信息（批量大小、成功数量、失败数量等）
-
必须使用 RESTful API 设计
- 批量创建：
POST /api/partner/batch/create - 批量更新：
POST /api/partner/batch/update - 批量删除：
POST /api/partner/batch/delete - 批量 Upsert：
POST /api/partner/batch/upsert
- 批量创建：
-
必须使用 Swagger/OpenAPI 文档
- 使用
@Tag注解标记 Controller - 使用
@Operation注解标记方法 - 使用
@Parameter注解标记参数 - 使用
@Schema注解标记 DTO 和 VO
- 使用
-
必须使用单元测试
- 单元测试覆盖率不低于 80%
- 测试用例包含正常场景和异常场景
- 使用 JUnit 5 和 Mockito 进行测试
- 测试用例命名规范：
test+方法名+场景，如testBatchCreateSuccess - 测试数据使用 Mockito 模拟
-
必须遵循代码规范
- 类命名：首字母大写，驼峰命名
- 方法命名：首字母小写，驼峰命名
- 变量命名：首字母小写，驼峰命名
- 常量命名：全大写，下划线分隔
- 注释规范：使用
/** */，包含功能描述、参数、返回值、异常描述 - 代码格式：使用 4 个空格缩进，行宽不超过 120 字符
- 导入规范：使用 import 静态导入，避免通配符导入