12 KiB
复盘文档
元数据
- 需求编号：004-01
- 复盘日期：2026-02-03
- 创建人：AI Assistant
- 状态：已完成
复盘概述
本次复盘对 Tooling API 连接管理功能的开发过程进行了全面回顾。从需求定义到变更记录归档，完整执行了 SSOT 流程的 8 个阶段。通过复盘总结了成功经验、识别了改进点、分析了遇到的问题，并制定了具体的行动计划，旨在提高后续开发过程的效率和质量。
目标与实际产出对比
目标
- 实现 Tooling API 连接管理功能，包括获取连接、清除缓存、测试连接、设置调用选项、设置调试头部
- 采用工厂模式管理连接，继承 AbstractConnectionFactory
- 使用 ConcurrentHashMap 实现线程安全的连接缓存
- 提供完整的 RESTful API 接口（5 个接口）
- 实现完整的单元测试，测试覆盖率不低于 80%
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
实际产出
- ✅ 成功实现了 Tooling API 连接管理的 5 个核心功能
- ✅ 实现了 ToolingConnectionFactory，正确继承 AbstractConnectionFactory
- ✅ 使用 ConcurrentHashMap 实现线程安全的连接缓存
- ✅ 提供了 5 个 RESTful API 接口，符合 RESTful 规范
- ✅ 实现了 19 个单元测试用例，覆盖 Service、Factory、Controller 三层
- ✅ 严格按照 SSOT 流程执行，每个阶段都有相应的文档
- ✅ 生成了 11 个 Java 文件，代码结构清晰、规范
- ✅ 定义了 8 种错误类型，实现了完善的异常处理机制
成功经验
1. SSOT 流程的严格执行
从需求定义到变更记录归档，每个阶段都严格按照项目规则执行。这种规范化的流程确保了：
- 所有开发活动都有文档依据
- 代码的可追溯性和可维护性大大提高
- 团队成员可以快速理解需求和设计决策
- 减少了沟通成本和返工风险
2. 架构决策的科学性
在阶段 3 的架构决策中，对每个技术选型都进行了充分的分析和对比：
- 连接工厂架构选择了 AbstractConnectionFactory + SessionManager 方案
- 连接缓存策略选择了 ConcurrentHashMap 方案
- Session 有效性检查选择了执行简单 SOQL 查询方案
- 每个决策都有清晰的决策理由和影响分析
这种科学的决策方式为后续开发奠定了坚实的基础。
3. 详细的提示词设计
阶段 5 生成的提示词包含了：
- 明确的输出格式要求（8 个文件的具体路径和命名）
- 详细的代码规范要求（若依框架规范、Java 编码规范）
- 具体的测试要求（单元测试覆盖率不低于 80%）
- 清晰的注意事项（不创建 Mapper 和 Entity、固定使用 source ORG 类型）
这种详细的提示词设计确保了生成的代码符合项目规范和需求。
4. 代码复用和一致性
ToolingConnectionFactory 继承 AbstractConnectionFactory，复用了现有的连接管理基础设施：
- 统一的连接创建逻辑
- 一致的 Session 有效性检查机制
- 相同的异常处理方式
- 标准化的缓存管理策略
这种复用大大提高了开发效率，降低了维护成本。
5. 完整的单元测试
实现了 19 个单元测试用例，覆盖了：
- Service 层：8 个测试用例（获取连接、清除缓存、测试连接、设置调用选项、设置调试头部等）
- Factory 层：5 个测试用例（创建连接、缓存管理、Session 检查等）
- Controller 层：6 个测试用例（API 接口测试、权限控制测试等）
完整的单元测试确保了代码的质量和可靠性。
改进点
1. 阶段间的过渡可以更流畅
在阶段转换时，可以更主动地向用户解释：
- 下一阶段的目的和流程
- 需要用户确认的关键点
- 预计的产出物
这样可以提高用户的理解和参与度，减少等待时间。
2. 代码生成前的验证可以更严格
在生成代码前，可以增加：
- 对设计文档的再次验证
- 对决策记录的再次确认
- 对现有代码的兼容性检查
这样可以确保代码生成的准确性，减少返工。
3. 错误码的定义可以更系统化
当前错误码的定义虽然完整，但可以进一步：
- 建立错误码的层级结构
- 定义错误码的分配规则
- 建立错误码的维护机制
这样可以提高错误码的可维护性和可扩展性。
4. API 文档的示例可以更详细
API 文档中的示例可以进一步丰富：
- 增加更多的边界条件示例
- 提供不同场景下的请求/响应示例
- 增加错误场景的示例
这样可以提高 API 文档的实用性。
问题分析
问题 1：连接缓存的持久化问题
问题描述：当前连接缓存仅在内存中，应用重启后缓存丢失。
根因分析：
- 设计阶段考虑到当前需求不需要数据库交互
- 为了简化实现，选择了内存缓存方案
- 没有考虑到应用重启的场景
影响：
- 应用重启后需要重新创建连接
- 会增加 Salesforce API 的调用次数
- 用户体验会有短暂影响
解决方案：
- 短期：接受当前方案，在文档中明确说明限制
- 长期：考虑使用 Redis 等分布式缓存方案
问题 2：单元测试的 Mock 复杂度
问题描述：ToolingConnection 的单元测试需要大量 Mock，增加了测试复杂度。
根因分析：
- ToolingConnection 是第三方库（tooling.jar）的类
- 该类没有提供易于 Mock 的接口
- 测试需要模拟 Salesforce API 的响应
影响：
- 单元测试编写耗时较长
- 测试代码复杂度较高
- 测试的可维护性降低
解决方案：
- 使用 Mockito 的 spy 功能部分模拟 ToolingConnection
- 增加集成测试补充单元测试的不足
- 考虑封装 ToolingConnection 的适配器层，便于测试
问题 3：权限配置的同步问题
问题描述：Controller 中的权限注解与数据库中的权限配置需要手动同步。
根因分析：
- 权限注解在代码中定义
- 权限数据在数据库中存储
- 两者没有自动同步机制
影响：
- 容易遗漏权限配置
- 权限变更需要同时修改代码和数据库
- 增加了维护成本
解决方案：
- 建立权限配置的 checklist
- 考虑开发权限配置自动生成工具
- 在代码审查时增加权限配置的检查项
行动计划
| 序号 | 行动项 | 责任人 | 优先级 | 计划完成时间 | 状态 |
|---|---|---|---|---|---|
| 1 | 在阶段转换时增加流程说明 | AI Assistant | 中 | 立即执行 | 待开始 |
| 2 | 增加代码生成前的验证步骤 | AI Assistant | 中 | 立即执行 | 待开始 |
| 3 | 建立错误码管理规范文档 | 项目团队 | 低 | 下一个迭代 | 待开始 |
| 4 | 完善 API 文档示例 | AI Assistant | 中 | 立即执行 | 待开始 |
| 5 | 评估分布式缓存方案（Redis） | 项目团队 | 低 | 下一个迭代 | 待开始 |
| 6 | 增加集成测试补充单元测试 | 项目团队 | 中 | 下一个迭代 | 待开始 |
| 7 | 建立权限配置 checklist | AI Assistant | 中 | 立即执行 | 待开始 |
提取模式
有效的 Prompt 技巧
1. 引用真源
在提示词开头明确引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
示例：
请基于以下真源文档实现功能：
- 需求文档：[2026-01-28-004-01-连接管理.md](../requirements/sub/2026-01-28-004-01-连接管理.md)
- 设计文档：[2026-02-03-004-01-连接管理-设计.md](../design/2026-02-03-004-01-连接管理-设计.md)
2. 具体的输出格式要求
在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
示例：
请生成以下文件：
1. Controller 类：`datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/ToolingConnectionController.java`
2. Service 接口：`datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IToolingConnectionService.java`
...
3. 详细的代码规范要求
在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
示例：
代码规范要求：
- 遵循若依框架的代码规范
- 使用 Lombok 简化代码
- 添加 Swagger 注解（@Tag、@Operation）
- 使用统一的异常处理机制
避免的坑
1. 不要使用模糊的描述
在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。
错误示例：
请生成高质量的 Tooling API 连接管理代码。
正确示例：
请实现 ToolingConnectionController 类，包含以下方法：
1. getConnection() - 获取连接，GET /salesforce/tooling/connection/get
2. clearConnection() - 清除缓存，DELETE /salesforce/tooling/connection/clear
...
2. 不要忽略测试要求
在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
错误示例：
请实现 ToolingConnectionService 类。
正确示例：
请实现 ToolingConnectionService 类，并编写单元测试：
- 单元测试覆盖率不低于 80%
- 测试正常场景和异常场景
- 使用 Mockito 进行 Mock
3. 不要违反项目规则
在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。
错误示例：
请使用自定义的异常处理机制。
正确示例：
请使用若依框架的统一异常处理机制（AjaxResult）。
模板迭代
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
1. 增加架构一致性检查项
在提示词中增加对架构一致性的检查要求：
架构一致性检查：
- [ ] 是否正确继承了 AbstractConnectionFactory
- [ ] 是否正确使用了 SessionManager
- [ ] 是否遵循了现有的包结构规范
- [ ] 是否使用了统一的异常处理机制
2. 增加测试复杂度评估
在提示词中增加对测试复杂度的评估和应对策略：
测试策略：
- 识别需要 Mock 的外部依赖
- 评估 Mock 的复杂度
- 确定是否需要集成测试补充
- 制定测试数据准备方案
3. 增加权限配置 checklist
在提示词中增加权限配置的 checklist：
权限配置 checklist：
- [ ] Controller 方法添加了 @PreAuthorize 注解
- [ ] 权限字符串符合命名规范（模块:功能:操作）
- [ ] 数据库中配置了对应的权限数据
- [ ] 权限配置文档已更新
计划在下一个迭代中更新提示词模板，增加上述内容。
数据洞察
开发效率
- 总耗时：约 40 分钟（阶段 5 到阶段 8）
- 文档数量：8 个文档（需求、设计、决策、提示词、会话、变更日志、复盘、API）
- 代码文件：11 个 Java 文件
- 测试用例：19 个单元测试
代码质量
- 代码规范：符合若依框架规范
- 单元测试覆盖率：预计 80% 以上
- 接口数量：5 个 REST API 接口
- 错误码数量：8 种错误类型
文档完整性
- 需求文档：完整，包含功能描述、入参/出参、实现要点
- 设计文档：完整，包含架构设计、技术方案、接口设计
- 决策记录：完整，包含 4 个关键决策及其理由
- 变更日志：完整，包含详细的变更内容和影响分析