163 lines
9.1 KiB
Markdown
163 lines
9.1 KiB
Markdown
# 复盘文档 - 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: 单元测试未生成
|
||
**现象**: 按照提示词要求，应该生成单元测试文件，但实际生成的代码文件中缺少单元测试。
|
||
|
||
**根因分析**:
|
||
1. 提示词中对单元测试的要求不够具体，没有明确要求生成哪些测试类
|
||
2. 代码生成阶段没有强制检查单元测试文件是否生成
|
||
3. 提示词中虽然要求"单元测试覆盖率不低于 80%"，但没有明确指定测试文件的路径和命名规范
|
||
|
||
**解决方案**:
|
||
1. 在后续的提示词设计中，明确指定需要生成的单元测试文件路径和命名规范
|
||
2. 在代码生成阶段增加对单元测试文件的强制检查
|
||
3. 补充生成缺失的单元测试文件
|
||
|
||
### 问题 2: 部分错误码定义与实际代码不完全匹配
|
||
**现象**: 错误码枚举中定义了 8 个错误码，但在实际代码中部分错误码的使用场景与定义略有差异。
|
||
|
||
**根因分析**:
|
||
1. 错误码定义和代码实现是分开进行的，缺乏一致性检查
|
||
2. 错误码的定义过于宽泛，没有针对具体场景进行细化
|
||
|
||
**解决方案**:
|
||
1. 在错误码定义阶段，与代码实现保持同步，确保定义与实际使用一致
|
||
2. 细化错误码的定义，针对具体场景提供更精确的错误码
|
||
3. 建立错误码使用规范，确保团队成员遵循统一的标准
|
||
|
||
## 行动计划
|
||
|
||
| 序号 | 行动项 | 责任人 | 优先级 | 完成时间 |
|
||
|------|--------|--------|--------|----------|
|
||
| 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 技巧
|
||
|
||
1. **引用真源**: 在提示词开头引用需求文档和设计文档的链接，确保生成的代码符合需求和设计要求。
|
||
- 示例: "请根据以下需求文档和设计文档生成代码..."
|
||
|
||
2. **明确的输出格式要求**: 在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
|
||
- 示例: "在 `datai-salesforce-tooling/src/main/java/com/datai/tooling/factory/` 目录下创建 `ToolingConnectionFactory.java`..."
|
||
|
||
3. **详细的代码规范要求**: 在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
|
||
- 示例: "使用 Lombok 的 `@Slf4j` 注解记录日志，使用 `@Operation` 和 `@Tag` 注解添加 Swagger 文档..."
|
||
|
||
### 避免的坑
|
||
|
||
1. **不要忽略单元测试要求**: 在提示词中忽略单元测试要求或要求不够具体，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
|
||
- 避免: "请生成单元测试"
|
||
- 推荐: "在 `src/test/java/...` 目录下创建 `ToolingConnectionServiceTest.java`，包含以下测试方法..."
|
||
|
||
2. **不要使用模糊的错误码定义**: 错误码定义过于宽泛或模糊，会导致错误处理不够精确，影响用户体验。
|
||
- 避免: "TOOLING_ERROR: 发生错误"
|
||
- 推荐: "TOOLING_CONN_001: Session 无效或已过期"
|
||
|
||
3. **不要违反分层架构原则**: 在代码实现中违反 Controller → Service → Factory 的分层架构，会导致代码耦合度高，难以维护。
|
||
- 避免: 在 Controller 中直接创建 ToolingConnection
|
||
- 推荐: Controller 调用 Service，Service 调用 Factory，Factory 创建连接
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
|
||
|
||
### 1. 单元测试要求更具体
|
||
在提示词模板中增加单元测试的详细要求：
|
||
- 明确指定测试文件的路径和命名规范
|
||
- 列出需要测试的核心方法
|
||
- 指定测试覆盖率要求
|
||
- 提供测试用例示例
|
||
|
||
### 2. 错误码定义更细化
|
||
在提示词模板中增加错误码的详细定义要求：
|
||
- 明确错误码的命名规范（如 `TOOLING_[模块]_[序号]`）
|
||
- 要求每个错误码都有明确的使用场景
|
||
- 要求错误码与代码实现保持一致
|
||
|
||
### 3. 增加接口文档要求
|
||
在提示词模板中增加 API 文档的要求：
|
||
- 要求使用 Swagger 注解
|
||
- 要求提供接口调用示例
|
||
- 要求描述接口的注意事项
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-004-01-连接管理.md)
|
||
- [设计文档](../design/2026-02-03-004-01-连接管理-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-004-01-ADR-连接管理技术选型.md)
|
||
- [提示词](../prompts/2026-02-03-004-01-prompt-Tooling连接管理.md)
|
||
- [变更日志](../changelog/2026-02-05-004-01-changelog.md)
|
||
- [API 文档](../api-docs/2026-02-05-004-01-api.md)
|
||
- [会话记录](../sessions/2026-01-28-004-session.md)
|