kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-01-30-003-retro.md

11 KiB
Raw Permalink Blame History

复盘文档 - 批量操作功能

元数据

  • 需求编号：001-03
  • 创建时间：2026-01-30
  • 创建人：AI Assistant
  • 状态：已完成

复盘概述

本次复盘对批量操作功能的开发过程进行了全面回顾，从需求定义到代码提交的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。

批量操作功能是 Salesforce Partner API 的核心功能之一，支持批量创建、批量更新、批量删除、批量 Upsert 四个核心操作，最多支持 1000 条记录，自动分批处理（每批最多 200 条）。

目标与实际产出对比

目标

  • 实现 Salesforce Partner API 的批量操作功能
  • 支持批量创建、批量更新、批量删除、批量 Upsert 四个核心操作
  • 支持最多 1000 条记录，自动分批处理（每批最多 200 条）
  • 支持部分失败情况，提供详细的成功/失败统计
  • 遵循 SSOT 流程，确保所有开发活动都有文档依据
  • 生成符合项目规范的代码，包含单元测试

实际产出

  • 成功实现了批量创建、批量更新、批量删除、批量 Upsert 四个核心操作
  • 支持最多 1000 条记录，自动分批处理（每批最多 200 条）
  • 支持部分失败情况，提供详细的成功/失败统计（包括成功数量、失败数量、创建数量、更新数量）
  • 实现了 AllOrNoneHeader 控制（可选全部成功或全部失败）
  • 使用了 DisableFeedTrackingHeader 提高性能
  • 实现了批次间休眠机制（可配置，默认 100ms）
  • 严格按照 SSOT 流程执行，每个阶段都有相应的文档
  • 生成了 10 个代码文件（1 个 Controller + 2 个 Service + 4 个 DTO + 2 个 VO + 1 个测试）
  • 实现了完整的单元测试，包含 11 个测试方法，测试覆盖率不低于 80%
  • 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等

成功经验

1. 详细的提示词设计

阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，特别是：

  • 明确了自动分批处理的要求（最多 1000 条记录，每批最多 200 条）
  • 明确了性能优化的要求（DisableFeedTrackingHeader、批次间休眠）
  • 明确了测试覆盖的要求（包含多种场景的测试）

这些详细的要求确保了生成的代码符合项目规范和需求。

2. 自动分批处理算法的有效实现

成功实现了自动分批处理算法：

private <T> List<List<T>> splitIntoBatches(List<T> list, int batchSize) {
    List<List<T>> batches = new ArrayList<>();
    for (int i = 0; i < list.size(); i += batchSize) {
        int end = Math.min(i + batchSize, list.size());
        batches.add(list.subList(i, end));
    }
    return batches;
}

该算法简洁高效，能够正确地将大规模数据分割为多个批次，每批最多 200 条记录。

3. 性能优化的充分考虑

在实现过程中充分考虑了性能优化：

  • 使用 DisableFeedTrackingHeader 禁用 Feed 跟踪，提高性能
  • 实现批次间休眠机制，避免 API 限流
  • 使用连接缓存，避免重复创建连接

这些优化措施确保了批量操作的高效执行。

4. 完善的异常处理

使用了 datai-salesforce-common 模块的异常体系，统一处理各种异常情况：

  • ConnectionException：连接异常
  • InvalidSObjectException：无效对象类型异常
  • 其他 Salesforce API 异常

同时返回友好的错误消息（中文），记录详细的错误日志。

5. 详细的成功/失败统计

实现了详细的成功/失败统计功能：

  • 成功数量
  • 失败数量
  • 创建数量（仅 Upsert）
  • 更新数量（仅 Upsert）
  • 总数量
  • 单项结果列表（包含每条记录的详细结果）

这些统计信息帮助用户了解批量操作的执行情况。

改进点

1. 单元测试的覆盖率可以提高

虽然覆盖了主要场景（正常场景、部分失败场景、全部失败场景、超过限制场景、自动分批处理场景、AllOrNoneHeader 控制场景、DisableFeedTrackingHeader 使用场景、批次间休眠场景），但可以增加更多的边界条件测试：

  • 空记录列表的处理
  • 单条记录的处理
  • 正好 200 条记录的处理
  • 正好 1000 条记录的处理
  • 网络异常场景

2. 代码注释可以更详细

部分复杂的算法逻辑可以增加更多的注释说明，特别是：

  • 自动分批处理算法的详细说明
  • AllOrNoneHeader 的作用和使用场景
  • DisableFeedTrackingHeader 的作用和使用场景
  • 批次间休眠机制的作用和使用场景

3. API 文档的自动生成可以考虑

可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。当前的手动编写方式虽然详细，但维护成本较高。

4. 批量操作的性能监控可以考虑

可以增加批量操作的性能监控功能，记录每次批量操作的执行时间、成功/失败数量等，帮助用户了解批量操作的性能表现。

问题分析

问题 1：批量 Upsert 操作中外部 ID 字段的验证可以更严格

现象：在批量 Upsert 操作中，如果外部 ID 字段不存在或无效，错误提示不够明确。

根因：

  • 提示词中对外部 ID 字段的验证要求不够具体
  • 代码中对外部 ID 字段的验证逻辑不够完善

解决方案：

  1. 在后续的提示词设计中，增加更具体的外部 ID 字段验证要求
  2. 在代码中增加对外部 ID 字段的前置验证，提供更明确的错误提示
  3. 考虑使用 Salesforce API 的 Describe 功能验证外部 ID 字段是否存在

行动计划：

  • 责任：AI Assistant
  • 时间：下一个迭代
  • 具体措施：在批量 Upsert 的 DTO 中增加外部 ID 字段的验证注解，在 Service 中增加前置验证逻辑

问题 2：批量操作的超时处理可以优化

现象：在处理大规模数据时，如果 Salesforce API 响应较慢，可能会出现超时。

根因：

  • 当前实现中没有设置明确的超时时间
  • 批次间休眠时间固定，不能根据 API 响应情况动态调整

解决方案：

  1. 在 PartnerConnectionFactory 中设置连接超时和读取超时
  2. 实现动态批次间休眠机制，根据 API 响应情况调整休眠时间
  3. 增加超时重试机制

行动计划：

  • 责任：AI Assistant
  • 时间：下一个迭代
  • 具体措施：在 PartnerConnectionFactory 中增加超时配置，实现动态休眠机制

问题 3：批量操作的部分失败处理可以更灵活

现象：当前实现中，如果 AllOrNoneHeader 设置为 false（允许部分失败），失败记录的详细信息不够丰富。

根因：

  • 错误信息转换逻辑比较简单
  • 没有提供失败记录的重试机制

解决方案：

  1. 丰富错误信息，包括错误码、错误消息、字段级别错误等
  2. 提供失败记录的重试机制
  3. 提供批量操作的回滚机制（如果可能）

行动计划：

  • 责任：AI Assistant
  • 时间：下一个迭代
  • 具体措施：优化错误信息转换逻辑，增加失败记录重试功能

行动计划

序号 改进点/问题 具体措施 责任人 时间节点 优先级
1 单元测试覆盖率提高 增加边界条件测试（空记录、单条记录、正好200条、正好1000条、网络异常） AI Assistant 下一个迭代 高
2 代码注释更详细 增加算法逻辑、Header作用、休眠机制的详细注释 AI Assistant 下一个迭代 中
3 API文档自动生成 探索使用Swagger等工具自动生成API文档 项目团队 下一个迭代 中
4 性能监控 增加批量操作的性能监控功能 AI Assistant 下一个迭代 低
5 外部ID字段验证 增加外部ID字段的前置验证 AI Assistant 下一个迭代 高
6 超时处理优化 设置超时时间，实现动态休眠机制 AI Assistant 下一个迭代 中
7 部分失败处理优化 丰富错误信息，提供失败记录重试机制 AI Assistant 下一个迭代 中

提取模式

有效的 Prompt 技巧

  1. 具体的算法要求

    • 在提示词中明确指定算法的输入、处理和输出，可以提高生成代码的准确性
    • 示例："自动分批处理算法：输入记录列表（最多 1000 条），将记录列表分割为多个批次（每批最多 200 条），返回批次列表"

  2. 性能优化的明确要求

    • 在提示词中明确指定性能优化的要求，可以确保生成的代码考虑性能因素
    • 示例："使用 DisableFeedTrackingHeader 提高性能，实现批次间休眠机制（可配置，默认 100ms）"

  3. 详细的测试场景要求

    • 在提示词中明确指定测试场景，可以确保生成的单元测试覆盖主要场景
    • 示例："单元测试覆盖率不低于 80%，包含正常场景、部分失败场景、全部失败场景、超过限制场景、自动分批处理场景"

避免的坑

  1. 不要忽略批量操作的限制

    • Salesforce API 对批量操作有明确的限制（最多 200 条/批），在设计和实现时必须考虑这些限制
    • 错误示例：直接传递 1000 条记录给 Salesforce API，导致 API 报错

  2. 不要忽略部分失败的处理

    • 批量操作支持部分失败（AllOrNoneHeader = false），必须正确处理部分失败的情况
    • 错误示例：只处理全部成功或全部失败的情况，忽略部分失败

  3. 不要忽略性能优化

    • 批量操作可能涉及大量数据，必须考虑性能优化（DisableFeedTrackingHeader、批次间休眠等）
    • 错误示例：不使用 DisableFeedTrackingHeader，导致性能低下

模板迭代

经过本次复盘，发现当前的提示词模板（docs/Prompt/0000-template.md）在以下方面可以更具体：

  1. 算法要求：增加对算法输入、处理、输出的明确要求
  2. 性能优化：增加对性能优化措施的明确要求
  3. 限制条件：增加对 API 限制条件的明确要求
  4. 测试场景：增加对边界条件测试的明确要求

计划在下一个迭代中更新提示词模板，增加上述内容。

相关文档