11 KiB
复盘文档 - 检查部署和检索状态
元数据
- 需求编号：003-07
- 需求名称：检查部署和检索状态
- 创建时间：2026-02-06
- 创建人：AI Assistant
- 状态：已完成
复盘概述
本次复盘对"检查部署和检索状态"功能的开发过程进行了全面回顾。该功能是 Metadata API 模块的重要组成部分，为异步操作提供完整的状态监控能力。通过复盘，我们总结了成功经验、识别了改进点、分析了问题，并制定了行动计划，旨在提高后续开发过程的效率和质量。
目标与实际产出对比
目标
- 实现 Salesforce Metadata API 部署和检索状态检查功能
- 支持单次状态查询、轮询监控和历史记录查询
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
- 生成符合项目规范的代码，包含单元测试
实际产出
- ✅ 成功实现了 5 个核心功能（部署状态检查、检索状态检查、轮询部署状态、轮询检索状态、历史查询）
- ✅ 提供了 5 个 REST API 接口，支持灵活的参数配置
- ✅ 创建了 1 个数据库表（datai_metadata_status_check），包含 6 个索引
- ✅ 生成了 14 个代码文件（8 个代码生成器生成 + 4 个手动实现 + 2 个单元测试）
- ✅ 定义了 9 个标准错误码，覆盖各种异常场景
- ✅ 严格按照 SSOT 流程执行，完成了阶段 1-8 的所有文档
- ✅ 编写了 14 个单元测试用例，覆盖成功、失败和边界场景
成功经验
1. 代码生成器与手动实现的良好结合
经验描述：本次开发充分利用了代码生成器生成基础代码（Entity、Mapper、基础 Service），同时针对业务逻辑编写了手动实现的 Service 和 Controller。这种结合方式既提高了开发效率，又保证了业务逻辑的灵活性。
具体案例：
- 代码生成器生成了
DataiMetadataStatusCheck相关的 8 个基础文件 - 手动实现了
IMetadataStatusService接口和MetadataStatusServiceImpl，包含复杂的业务逻辑（调用 Metadata API、事务管理、异步记录） - 手动实现了
MetadataStatusController，提供 5 个 REST API 接口
推广建议：对于涉及外部 API 调用的功能，建议采用"代码生成器生成基础代码 + 手动实现业务逻辑"的模式。
2. 异步审计日志的设计
经验描述：状态检查历史采用异步方式写入数据库，避免了阻塞主流程，提高了系统响应速度。
具体案例：
@Async("threadPoolTaskExecutor")
public void recordStatusCheck(String asyncId, String operationType, String status, String errorMessage) {
// 异步记录状态检查历史
}
推广建议：对于非关键路径的日志记录操作，建议使用异步方式执行，提高系统性能。
3. 关联表状态同步机制
经验描述：在检查状态的同时，自动更新关联表（datai_metadata_deploy_log 和 datai_metadata_retrieve）的状态字段，确保数据一致性。
具体案例：
private void updateDeployHistory(String asyncId, DeployResult result) {
// 更新部署日志表的状态
}
private void updateRetrieveHistory(String asyncId, RetrieveResult result) {
// 更新检索记录表的状态
}
推广建议：对于有关联关系的数据操作，建议在主操作完成后自动同步关联表的状态，避免数据不一致。
4. 完善的错误码体系
经验描述：定义了 9 个标准错误码，覆盖会话过期、未授权、无效 ID、操作未找到、检查失败、超时、中断、远程调用失败等各种异常场景。
具体案例：
STATUS_001- 会话已过期STATUS_003- 无效的异步操作 IDSTATUS_006- 轮询超时
推广建议：为每个功能模块定义独立的错误码体系，便于问题定位和错误处理。
5. 轮询策略的灵活配置
经验描述：轮询功能支持自定义轮询间隔和超时时间，默认间隔 2000ms，默认超时 300000ms（5分钟），满足不同场景的需求。
具体案例：
public DeployResult pollDeployStatus(String asyncId, long interval, long timeout) {
long pollInterval = interval > 0 ? interval : DEFAULT_POLL_INTERVAL;
long pollTimeout = timeout > 0 ? timeout : DEFAULT_POLL_TIMEOUT;
// 轮询逻辑
}
推广建议：对于需要等待外部操作完成的功能，建议提供可配置的轮询参数，提高灵活性。
改进点
1. Mapper 引用的前期调研不足
问题描述：在编写 MetadataStatusServiceImpl 时，最初使用了不存在的 DataiMetadataDeployMapper，实际应该使用 DataiMetadataDeployLogMapper。
影响：需要返工修改代码，增加了开发时间。
改进措施：
- 在编写业务代码前，先确认相关的 Mapper 和实体类是否存在
- 建立数据库表和代码文件的映射关系文档
责任人：AI Assistant 时间节点：立即执行
2. 单元测试的边界场景覆盖可以更全面
问题描述：虽然编写了 14 个测试用例，但对于某些边界场景（如网络超时、Salesforce 服务不可用）的测试覆盖不足。
影响：可能导致某些异常场景在生产环境中出现问题。
改进措施：
- 增加对网络异常、服务不可用等边界场景的测试
- 使用 Mockito 模拟各种异常场景
责任人：AI Assistant 时间节点：下一个迭代
3. API 文档的示例可以更详细
问题描述：API 文档中的请求和响应示例相对简单，缺少复杂的嵌套对象示例。
影响：前端开发人员可能需要额外沟通才能理解复杂的响应结构。
改进措施：
- 在 API 文档中增加更详细的示例，包括复杂的嵌套对象
- 提供完整的请求和响应示例
责任人：AI Assistant 时间节点：立即执行
问题分析
问题 1：部署表结构的理解偏差
问题描述：最初以为部署操作使用 DataiMetadataDeploy 表，实际使用的是 DataiMetadataDeployLog 表。
根因分析：
- 对现有表结构了解不够深入
- 没有仔细查看已有的部署相关代码
解决方案：
- 在开发前详细查看相关的现有代码和表结构
- 建立表结构和业务功能的映射文档
预防措施：
- 开发前进行代码走查，了解相关模块的表结构
- 维护一份数据库表结构文档
问题 2：单元测试中的 Mock 对象配置复杂
问题描述：由于 MetadataStatusServiceImpl 依赖多个 Mapper 和 ConnectionFactory，单元测试中的 Mock 配置较为复杂。
根因分析：
- Service 层的依赖较多
- 没有使用依赖注入的最佳实践
解决方案：
- 考虑使用构造函数注入，便于单元测试
- 使用 @MockBean 简化 Mock 配置
预防措施：
- 在设计阶段考虑可测试性
- 遵循依赖注入的最佳实践
行动计划
| 序号 | 行动项 | 责任人 | 时间节点 | 优先级 |
|---|---|---|---|---|
| 1 | 建立数据库表和代码文件的映射关系文档 | AI Assistant | 2026-02-07 | 高 |
| 2 | 增加单元测试的边界场景覆盖 | AI Assistant | 2026-02-10 | 中 |
| 3 | 完善 API 文档的示例 | AI Assistant | 2026-02-07 | 高 |
| 4 | 优化 Service 层的依赖注入方式 | AI Assistant | 2026-02-10 | 中 |
| 5 | 维护数据库表结构文档 | 项目团队 | 持续进行 | 低 |
提取模式
有效的 Prompt 技巧
1. 具体的输出格式要求
技巧描述：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
应用案例：在阶段 5 的提示词中，明确指定了：
- 文件路径：
datai-salesforce-metadata/src/main/java/com/datai/metadata/... - 命名规范：
DataiMetadataStatusCheck（大驼峰命名） - 包结构：
com.datai.metadata.service
2. 引用真源
技巧描述：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
应用案例：
基于以下真源文档：
- [需求文档](../requirements/sub/2026-01-28-003-07-检查部署和检索状态.md)
- [设计文档](../design/2026-02-03-003-07-检查部署和检索状态-设计.md)
3. 详细的代码规范要求
技巧描述：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
应用案例：
- 使用 Lombok 的
@Data注解简化实体类 - 使用 Swagger 的
@Schema注解进行 API 文档标注 - 使用 SLF4J 进行日志记录
避免的坑
1. 不要假设表结构
坑描述：在编写业务代码时，假设某个表存在或具有某些字段，实际可能不存在或字段不同。
避免方法：
- 编写代码前，先查看数据库表结构和现有代码
- 使用
Glob工具搜索相关的实体类和 Mapper
2. 不要忽略现有代码的复用
坑描述：在编写新功能时，忽略现有代码的复用，导致重复造轮子。
避免方法：
- 开发前搜索相关的现有代码
- 查看类似功能的实现方式
3. 不要省略单元测试的异常场景
坑描述：只编写正常流程的单元测试，忽略异常场景的测试。
避免方法：
- 为每个方法编写至少 3 个测试用例：成功场景、失败场景、边界场景
- 使用 Mockito 模拟各种异常
模板迭代
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
1. 增加表结构确认环节
在提示词中增加一个环节，要求确认相关的数据库表结构和 Mapper 文件：
## 表结构确认
在编写业务代码前，请确认以下表结构和 Mapper 文件：
1. 使用 `Glob` 工具搜索相关的实体类（如 `*Deploy*.java`）
2. 使用 `Read` 工具查看实体类的字段
3. 确认 Mapper 接口的方法名
2. 增加可测试性要求
在提示词中增加对可测试性的要求：
## 可测试性要求
1. 使用构造函数注入或 Setter 注入，便于单元测试
2. 避免在方法中直接创建依赖对象
3. 为每个公共方法编写单元测试
3. 增加 API 文档示例要求
在提示词中增加对 API 文档示例的要求：
## API 文档要求
1. 提供完整的请求示例，包括所有字段
2. 提供完整的响应示例，包括嵌套对象
3. 提供错误响应示例
相关文档
总结
本次"检查部署和检索状态"功能的开发总体顺利，成功实现了所有目标功能，并生成了完整的文档和代码。通过复盘，我们识别了改进点并制定了行动计划，特别是加强了对现有表结构的调研和单元测试的覆盖。这些经验将应用到后续的开发工作中，持续提高开发效率和代码质量。