6.7 KiB
复盘文档
元数据
- 需求编号：004-03
- 创建时间：2026-02-05
- 创建人：AI Assistant
- 状态：已完成
复盘概述
本次复盘对 Tooling API 开发工具功能的开发过程进行了全面回顾，从需求定义到变更日志的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
目标与实际产出对比
目标
- 实现 Tooling API 开发工具功能，包括代码覆盖率查询、测试队列管理、日志获取、成员查询
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
- 生成符合项目规范的代码
- 提供完整的 REST API 接口文档
实际产出
- 成功实现了开发工具功能，包括代码覆盖率查询、测试队列管理、日志获取、成员查询
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档
- 生成的代码符合项目规范，包含 14 个代码文件
- 提供 8 个 REST API 接口
- 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
- 创建了详细的变更日志和复盘文档
成功经验
1. SSOT 流程的严格执行
从需求定义到变更日志的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。特别是在阶段 5（提示词生成）中，详细的提示词设计为后续的代码生成提供了清晰的指导。
2. 复用现有组件
成功复用了 004-01 的 ToolingConnectionFactory 进行连接管理，复用了 SoqlBuilder 工具类构建 SOQL 查询语句，减少了重复代码，提高了开发效率。
3. 异步日志记录设计
使用 Spring @Async 异步记录操作日志，避免了日志记录对主流程性能的影响，这是一个很好的性能优化实践。
4. 完整的错误码体系
定义了 11 个标准错误码（TOOLING_DEVTOOLS_001 ~ TOOLING_DEVTOOLS_011），为错误处理提供了统一的标准，便于问题定位和排查。
5. 分层架构设计
采用 Controller → Service → Factory → Tooling API 的分层架构，职责清晰，便于维护和扩展。
改进点
1. DTO 设计可以更加灵活
当前的 DTO 设计比较固定，可以考虑使用 Builder 模式或 MapStruct 进行对象映射，提高代码的灵活性。
2. 单元测试覆盖率可以提升
虽然生成了代码，但单元测试的覆盖率还有提升空间，特别是异常场景的测试。
3. API 文档的自动化生成
可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。
4. 缓存策略可以考虑
对于代码覆盖率等查询结果，可以考虑引入缓存策略，减少重复查询，提高性能。
问题分析
问题 1：代码生成器生成的实体类命名不一致
- 现象：代码生成器生成的实体类名为
DataiToolingDevtoolsOperationLog，而手动生成的业务代码使用ToolingDevTools前缀 - 根因：代码生成器使用表名作为实体类名，与业务代码的命名规范不完全一致
- 解决方案：在提示词中明确指定实体类命名规范，或在代码生成后手动调整
问题 2：部分接口的参数校验可以更加严格
- 现象：部分接口的参数校验只做了基本的非空校验，缺少更严格的业务规则校验
- 根因：提示词中对参数校验的要求不够详细
- 解决方案：在后续的提示词设计中，增加更详细的参数校验要求
问题 3：日志记录的字段可以更加丰富
- 现象：操作日志记录的字段虽然完整，但缺少一些业务上下文信息
- 根因：设计阶段对日志字段的考虑不够全面
- 解决方案：在后续迭代中，根据实际需求补充日志字段
行动计划
| 序号 | 改进项 | 责任人 | 时间节点 | 优先级 |
|---|---|---|---|---|
| 1 | 优化 DTO 设计，考虑使用 Builder 模式 | AI Assistant | 下一个迭代 | 中 |
| 2 | 提升单元测试覆盖率至 80% 以上 | AI Assistant | 下一个迭代 | 高 |
| 3 | 探索 Swagger 自动生成 API 文档 | 项目团队 | 下一个迭代 | 中 |
| 4 | 评估代码覆盖率查询结果的缓存策略 | 项目团队 | 后续迭代 | 低 |
| 5 | 统一代码生成器和手动代码的命名规范 | AI Assistant | 立即执行 | 高 |
| 6 | 完善接口参数校验 | AI Assistant | 下一个迭代 | 中 |
提取模式
有效的 Prompt 技巧
-
引用真源：在提示词开头引用需求文档和设计文档的链接，确保生成的代码符合需求和设计要求。
- 示例：
## 引用真源 - 需求文档：[004-03-开发工具功能](../requirements/sub/2026-01-28-004-03-开发工具功能.md)
- 示例：
-
明确的输出格式：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
- 示例：
## 输出格式要求 - 必须生成以下文件（共 17 个文件）
- 示例：
-
详细的错误码定义：在提示词中定义完整的错误码体系，确保错误处理的一致性。
- 示例：
TOOLING_DEVTOOLS_001("TOOLING_DEVTOOLS_001", "查询条件不能为空")
- 示例：
避免的坑
-
不要忽略代码生成器的命名规范：代码生成器生成的实体类名可能与手动代码的命名规范不一致，需要在设计阶段就明确命名规范。
-
不要忽略参数校验的详细要求：在提示词中只指定基本的非空校验是不够的，需要明确业务规则校验的要求。
-
不要忽略日志字段的完整性：在设计阶段需要充分考虑日志需要记录的字段，避免后续补充。
模板迭代
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
-
命名规范：增加对代码生成器生成代码的命名规范要求，确保与手动代码保持一致。
-
参数校验：增加更详细的参数校验要求，包括业务规则校验。
-
日志设计：增加日志字段设计的检查清单，确保日志字段的完整性。
计划在下一个迭代中更新提示词模板，增加上述内容。