9.1 KiB
复盘文档 - Tooling 连接管理功能
元数据
- 需求编号: 004-01
- 子需求名称: 连接管理
- 版本号: v1.0.0
- 创建时间: 2026-02-05
- 创建人: AI Assistant
- 状态: 已完成
复盘概述
本次复盘对 Tooling API 连接管理功能（子需求 004-01）的开发过程进行了全面回顾。该功能是 Tooling API 模块的基础组件，为后续元数据操作、开发工具功能、AI 和智能功能等子需求提供连接管理能力。复盘从需求定义到变更日志的完整过程，总结了成功经验、改进点、问题分析和行动计划。
目标与实际产出对比
目标
- 实现 Tooling API 连接管理功能，提供获取连接、清除缓存、测试连接、设置调用选项、设置调试头部等核心功能
- 复用现有连接管理基础设施（AbstractConnectionFactory、SessionManager）
- 提供完整的 RESTful API 接口
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
- 生成符合项目规范的代码
实际产出
- ✅ 成功实现了 ToolingConnectionFactory，继承 AbstractConnectionFactory，复用现有连接管理基础设施
- ✅ 成功集成了 SessionManager，通过 Session ID 和 Instance URL 创建 Tooling API 连接
- ✅ 使用 ConcurrentHashMap 实现线程安全的连接缓存
- ✅ 执行简单 SOQL 查询验证 Session 有效性
- ✅ 提供了 5 个完整的 RESTful API 接口（获取连接、清除缓存、测试连接、设置调用选项、设置调试头部）
- ✅ 定义了 8 个标准错误码，覆盖连接管理的各种异常场景
- ✅ 严格按照 SSOT 流程执行，每个阶段都有相应的文档
- ✅ 生成的代码符合项目规范，包含完整的注释和 Swagger 注解
- ⚠️ 单元测试文件待补充（已记录在待办事项中）
成功经验
1. SSOT 流程的严格执行
从需求定义到变更日志的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据。特别是在阶段 1 的需求澄清阶段，通过详细的问答澄清了功能边界、认证集成、模块设计等关键问题，为后续开发奠定了坚实基础。
2. 复用现有基础设施
通过继承 AbstractConnectionFactory 和集成 SessionManager，成功复用了现有连接管理基础设施。这不仅减少了重复代码，还确保了与 Apex 连接管理、Metadata 连接管理的一致性，提高了代码的可维护性。
3. 详细的提示词设计
阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，特别是明确了需要生成的文件路径、类结构、方法签名等，确保了生成的代码符合项目规范和需求。
4. 清晰的架构设计
采用 Controller → Service → Factory → Tooling API 的分层架构，职责清晰，便于后续扩展和维护。Controller 层负责 REST API 接口，Service 层负责业务逻辑，Factory 层负责连接创建和管理。
5. 完整的错误码体系
定义了 8 个标准错误码，覆盖连接管理的各种异常场景，便于前端进行错误处理和用户提示。
改进点
1. 单元测试需要补充
虽然提示词中要求生成单元测试，但实际生成的代码文件中缺少单元测试。后续需要补充 ToolingConnectionServiceTest、ToolingConnectionFactoryTest、ToolingConnectionControllerTest 等单元测试文件。
建议: 在代码生成阶段，可以增加对单元测试生成的强制检查，确保测试文件与业务代码同时生成。
2. API 文档可以更加详细
当前 API 文档描述了接口的基本信息，但可以进一步增加接口的调用场景、注意事项、性能指标等信息，帮助开发者更好地理解和使用接口。
建议: 在 API 文档中增加"接口调用场景"和"注意事项"章节，描述接口的典型使用场景和需要注意的问题。
3. 阶段转换时的沟通可以更充分
在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。
建议: 在每个阶段开始时，简要介绍该阶段的目标、输出物和验收标准。
问题分析
问题 1: 单元测试未生成
现象: 按照提示词要求，应该生成单元测试文件，但实际生成的代码文件中缺少单元测试。
根因分析:
- 提示词中对单元测试的要求不够具体，没有明确要求生成哪些测试类
- 代码生成阶段没有强制检查单元测试文件是否生成
- 提示词中虽然要求"单元测试覆盖率不低于 80%"，但没有明确指定测试文件的路径和命名规范
解决方案:
- 在后续的提示词设计中，明确指定需要生成的单元测试文件路径和命名规范
- 在代码生成阶段增加对单元测试文件的强制检查
- 补充生成缺失的单元测试文件
问题 2: 部分错误码定义与实际代码不完全匹配
现象: 错误码枚举中定义了 8 个错误码，但在实际代码中部分错误码的使用场景与定义略有差异。
根因分析:
- 错误码定义和代码实现是分开进行的，缺乏一致性检查
- 错误码的定义过于宽泛，没有针对具体场景进行细化
解决方案:
- 在错误码定义阶段，与代码实现保持同步，确保定义与实际使用一致
- 细化错误码的定义，针对具体场景提供更精确的错误码
- 建立错误码使用规范，确保团队成员遵循统一的标准
行动计划
| 序号 | 行动项 | 责任人 | 优先级 | 完成时间 |
|---|---|---|---|---|
| 1 | 补充单元测试代码（ToolingConnectionServiceTest、ToolingConnectionFactoryTest、ToolingConnectionControllerTest） | AI Assistant | 高 | 2026-02-06 |
| 2 | 更新提示词模板，明确单元测试文件路径和命名规范 | AI Assistant | 中 | 2026-02-07 |
| 3 | 建立错误码使用规范文档 | 项目团队 | 中 | 2026-02-10 |
| 4 | 完善 API 文档，增加接口调用场景和注意事项 | AI Assistant | 低 | 2026-02-08 |
| 5 | 集成测试验证与 Salesforce 实际环境的兼容性 | 项目团队 | 中 | 2026-02-15 |
提取模式
有效的 Prompt 技巧
-
引用真源: 在提示词开头引用需求文档和设计文档的链接，确保生成的代码符合需求和设计要求。
- 示例: "请根据以下需求文档和设计文档生成代码..."
-
明确的输出格式要求: 在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
- 示例: "在
datai-salesforce-tooling/src/main/java/com/datai/tooling/factory/目录下创建ToolingConnectionFactory.java..."
- 示例: "在
-
详细的代码规范要求: 在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
- 示例: "使用 Lombok 的
@Slf4j注解记录日志，使用@Operation和@Tag注解添加 Swagger 文档..."
- 示例: "使用 Lombok 的
避免的坑
-
不要忽略单元测试要求: 在提示词中忽略单元测试要求或要求不够具体，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
- 避免: "请生成单元测试"
- 推荐: "在
src/test/java/...目录下创建ToolingConnectionServiceTest.java，包含以下测试方法..."
-
不要使用模糊的错误码定义: 错误码定义过于宽泛或模糊，会导致错误处理不够精确，影响用户体验。
- 避免: "TOOLING_ERROR: 发生错误"
- 推荐: "TOOLING_CONN_001: Session 无效或已过期"
-
不要违反分层架构原则: 在代码实现中违反 Controller → Service → Factory 的分层架构，会导致代码耦合度高，难以维护。
- 避免: 在 Controller 中直接创建 ToolingConnection
- 推荐: Controller 调用 Service，Service 调用 Factory，Factory 创建连接
模板迭代
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
1. 单元测试要求更具体
在提示词模板中增加单元测试的详细要求：
- 明确指定测试文件的路径和命名规范
- 列出需要测试的核心方法
- 指定测试覆盖率要求
- 提供测试用例示例
2. 错误码定义更细化
在提示词模板中增加错误码的详细定义要求：
- 明确错误码的命名规范（如
TOOLING_[模块]_[序号]） - 要求每个错误码都有明确的使用场景
- 要求错误码与代码实现保持一致
3. 增加接口文档要求
在提示词模板中增加 API 文档的要求：
- 要求使用 Swagger 注解
- 要求提供接口调用示例
- 要求描述接口的注意事项