kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
27ce31edd3
datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-02-06-004-08-retro.md

10 KiB
Raw Blame History

复盘文档 - SOQL 查询功能 (004-08)

元数据

  • 需求编号: 004-08
  • 需求名称: SOQL 查询功能
  • 版本号: v1.0.0
  • 创建时间: 2026-02-06
  • 创建人: AI Assistant
  • 状态: 已完成

复盘概述

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

SOQL 查询功能是 Tooling API 模块的重要组成部分，提供了执行 SOQL 查询、获取更多查询结果、查询所有结果（自动处理分页）、使用 SoqlBuilder 执行查询以及查询日志管理等功能。

目标与实际产出对比

目标

  • 实现 Tooling API SOQL 查询功能
  • 提供 5 个核心 REST API 接口（执行 SOQL 查询、queryMore、queryAll、SoqlBuilder 查询、日志管理）
  • 支持所有 Tooling API 对象的查询
  • 支持复杂的查询条件、排序、分页
  • 遵循 SSOT 流程，确保所有开发活动都有文档依据
  • 生成符合项目规范的代码

实际产出

  • ✅ 成功实现了 SOQL 查询功能的所有需求
  • ✅ 提供了 5 个核心 REST API 接口
  • ✅ 支持所有 Tooling API 对象的 SOQL 查询
  • ✅ 支持复杂的查询条件、排序、分页
  • ✅ 严格按照 SSOT 流程执行，每个阶段都有相应的文档
  • ✅ 生成的代码符合项目规范，包含完整的错误码体系
  • ✅ 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
  • ✅ 创建了详细的变更日志，记录了所有新增功能、代码文件和错误码

成功经验

1. SSOT 流程的严格执行

从需求定义到变更日志的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。特别是在阶段 8 的变更日志创建过程中，详细记录了所有新增功能、代码文件和错误码，为后续的维护和升级提供了重要参考。

2. 代码复用策略的有效实施

成功复用了 004-01 的连接管理功能（ToolingConnectionFactory）和现有的 SoqlBuilder 工具类，避免了重复开发，提高了代码的一致性和可维护性。这种复用策略在多个需求中得到了验证，是项目开发的最佳实践。

3. 完整的错误码体系设计

定义了 6 个标准错误码（TOOLING_SOQL_001 ~ TOOLING_SOQL_006），涵盖了 Session 无效、查询失败、权限不足、用户未登录、查询定位器无效、查询结果超出限制等常见错误场景。这种系统化的错误码设计提高了错误处理的规范性和用户体验。

4. 异步日志记录机制

采用 Spring @Async 异步记录操作日志，避免了日志记录对主流程性能的影响。这种设计在保证功能完整性的同时，优化了系统性能，是处理类似场景的有效方案。

5. 详细的会话记录

阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。这种详细的记录方式为后续的复盘和问题排查提供了重要依据。

改进点

1. 阶段间的过渡可以更流畅

在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。特别是在阶段 6 到阶段 7 的过渡中，可以更详细地说明会话记录的重要性和内容要求。

2. 代码生成前的验证可以更严格

在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。特别是在处理复杂的分页逻辑和异常处理时，应该更加仔细地验证设计文档的要求。

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

可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。虽然手动创建的 API 文档更加详细，但自动生成的文档可以减少维护成本。

4. 单元测试的覆盖率可以提升

虽然代码中包含了基本的异常处理，但单元测试的覆盖率还有提升空间。特别是对于分页逻辑、异常处理等复杂场景，应该增加更多的单元测试用例。

问题分析

问题 1：查询结果超过 50000 条记录的处理

问题描述: Salesforce 限制最多返回 50000 条记录，在 queryAll 方法中需要处理这种情况。

根因分析: 这是 Salesforce API 的固有限制，不是代码问题。但需要在代码中明确处理这种情况，避免用户困惑。

解决方案: 在 queryAll 方法中检查记录数量，超过限制时抛出异常，返回错误码 TOOLING_SOQL_006，并在错误信息中明确说明限制原因。

经验总结: 在集成第三方 API 时，必须详细了解其限制和约束，并在代码中明确处理这些限制，提供清晰的错误信息。

问题 2：queryLocator 的有效期管理

问题描述: queryLocator 有有效期限制，过期后需要重新查询。

根因分析: 这是 Salesforce API 的设计特性，queryLocator 在一定时间后会失效。

解决方案: 在 queryMore 方法中捕获 queryLocator 无效的异常，返回错误码 TOOLING_SOQL_005，并提示用户重新执行查询。

经验总结: 在使用有状态 API（如 queryLocator）时，必须考虑状态的有效期管理，提供清晰的错误处理和用户提示。

问题 3：SOQL 查询字符串的验证

问题描述: 用户可能提交无效的 SOQL 查询字符串，导致查询失败。

根因分析: 当前实现主要依赖 Salesforce API 进行查询验证，本地验证较少。

解决方案: 在后续版本中，可以考虑增加本地 SOQL 语法验证，提前发现明显的语法错误，减少无效的 API 调用。

经验总结: 在接收用户输入进行外部 API 调用时，应该尽可能进行本地验证，减少无效调用，提高用户体验。

行动计划

序号 行动项 责任人 时间节点 优先级
1 在阶段转换时，增加对下一阶段的目的和流程的解释 AI Assistant 立即执行 中
2 在生成代码前，增加对设计文档和决策记录的再次验证 AI Assistant 立即执行 中
3 探索使用 Swagger 等工具自动生成 API 文档 项目团队 下一个迭代 低
4 增加单元测试覆盖率，特别是分页逻辑和异常处理场景 项目团队 下一个迭代 高
5 考虑增加本地 SOQL 语法验证功能 项目团队 下一个迭代 中

提取模式

有效的 Prompt 技巧

  1. 具体的输出格式要求

    • 在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
    • 示例："创建 DTO 类 ToolingSoqlQueryRequestDTO.java，路径为 datai-salesforce-tooling/src/main/java/com/datai/tooling/dto/"

  2. 引用真源

    • 在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
    • 示例："基于需求文档 2026-01-28-004-08-SOQL查询功能.md 和设计文档..."

  3. 详细的代码规范要求

    • 在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
    • 示例："使用 Lombok 注解，添加 Swagger 注解，遵循若依框架规范"

避免的坑

  1. 不要忽略第三方 API 的限制

    • 在集成第三方 API 时，必须详细了解其限制和约束（如 Salesforce 的 50000 条记录限制）。
    • 避免：直接实现功能而不考虑 API 限制，导致运行时错误。

  2. 不要忽略有状态 API 的有效期管理

    • 在使用有状态 API（如 queryLocator）时，必须考虑状态的有效期管理。
    • 避免：假设 queryLocator 永久有效，导致过期后查询失败。

  3. 不要忽略用户输入的验证

    • 在接收用户输入进行外部 API 调用时，应该尽可能进行本地验证。
    • 避免：直接将用户输入传递给外部 API，导致无效调用和性能问题。

模板迭代

经过本次复盘，发现当前的提示词模板在以下方面可以改进：

  1. 第三方 API 限制说明

    • 在提示词模板中增加一个章节，要求明确列出第三方 API 的限制和约束。
    • 包括：记录数限制、频率限制、有效期限制等。

  2. 有状态 API 管理

    • 在提示词模板中增加对有状态 API（如 queryLocator、Session 等）的管理要求。
    • 包括：有效期管理、失效处理、重新获取策略等。

  3. 用户输入验证

    • 在提示词模板中增加对用户输入验证的要求。
    • 包括：必填字段验证、格式验证、范围验证等。

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

技术债务

当前债务

  1. 单元测试覆盖率不足: 需要增加更多的单元测试用例，特别是分页逻辑和异常处理场景。
  2. 本地 SOQL 验证缺失: 可以考虑增加本地 SOQL 语法验证，提前发现明显的语法错误。

偿还计划

  • 在下一个迭代中，优先完成单元测试的编写，目标覆盖率 80% 以上。
  • 在后续版本中，考虑引入 SOQL 解析器进行本地语法验证。

相关文档

总结

SOQL 查询功能的开发过程总体顺利，严格按照 SSOT 流程执行，成功实现了所有需求。通过本次复盘，总结了成功经验，识别了改进点，分析了问题，制定了行动计划。特别是代码复用策略、错误码体系设计和异步日志记录机制等经验值得在后续开发中推广。同时，也识别了单元测试覆盖率、本地 SOQL 验证等方面的技术债务，计划在后续迭代中逐步偿还。