kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/docs/archive/retros/20260119-destructive-changes-retro.md

9.4 KiB
Raw Permalink Blame History

迭代复盘 - Destructive Changes功能实现

目标 vs 结果指标对比

指标 目标值 实际值 达成率 分析
功能完成数 5 个核心功能 5 个核心功能 100% 所有功能均已实现，包括 destructiveChanges.xml 配置、Destructive Changes 部署、Destructive Changes 验证、Destructive Changes 历史记录、Destructive Changes 回滚
代码质量 符合项目编码规范，有清晰的注释 符合项目编码规范，有清晰的注释 100% 代码质量良好，符合项目规范
测试覆盖率 > 80% > 80% 100% 单元测试和集成测试覆盖充分，测试通过率 100%
文档完整性 需求文档、ADR、Prompt、会话记录、变更记录、复盘报告 需求文档、ADR、Prompt、会话记录、变更记录、复盘报告 100% 所有文档均已创建并更新

3 条有效 Prompt 模式

模式 1: XML 解析和构建

  • 描述: 在 Prompt 中明确要求使用 Java XML 解析库（如 JAXB 或 DOM4J）处理 destructiveChanges.xml，提供 XML 解析和构建功能
  • 适用场景: 需要处理 XML 格式的配置文件时
  • 示例: 
    使用 Java XML 解析库处理 destructiveChanges.xml：
1. 创建 DestructiveChangesXmlParser 工具类，验证 destructiveChanges.xml 格式
2. 使用 DocumentBuilderFactory 和 DocumentBuilder 解析 XML
3. 验证根元素是否为 "Package"
4. 验证 types 元素是否包含至少一个 members 元素
5. 验证 types 元素是否包含一个 name 元素
6. 创建 DestructiveChangesXmlBuilder 工具类，构建 destructiveChanges.xml
7. 使用 StringBuilder 构建 XML 字符串
8. 使用 Collectors.groupingBy 按元数据类型分组
9. 使用 FileWriter 将 XML 保存到文件
  • 效果: 提高了 XML 解析和构建的准确性，减少了 XML 格式错误

模式 2: 备份和回滚机制

  • 描述: 在 Prompt 中明确要求在删除元数据组件之前先备份元数据组件，使用事务确保回滚的原子性，提供回滚日志记录
  • 适用场景: 需要实现删除和回滚功能的场景
  • 示例: 
    实现备份和回滚机制：
1. 在删除元数据组件之前，先备份元数据组件
2. 使用事务确保删除和回滚的原子性
3. 提供回滚日志记录，记录回滚的详细信息
4. 支持批量回滚，提高回滚效率
5. 提供回滚验证功能，验证回滚的完整性
6. 只有成功的部署才能回滚
7. 回滚需要备份数据
  • 效果: 提高了删除操作的安全性，确保数据可以恢复，降低了数据丢失风险

模式 3: 配置验证功能

  • 描述: 在 Prompt 中明确要求提供配置验证功能，验证 destructiveChanges.xml 格式和删除规则，提供详细的错误信息
  • 适用场景: 需要验证配置文件格式的场景
  • 示例: 
    实现配置验证功能：
1. 创建 DestructiveChangesXmlParser 工具类，验证 destructiveChanges.xml 格式
2. 使用 Java XML 解析库验证 destructiveChanges.xml 格式
3. 验证根元素是否为 "Package"
4. 验证 types 元素是否包含至少一个 members 元素
5. 验证 types 元素是否包含一个 name 元素
6. 提供详细的错误信息，包括错误位置和错误原因
7. 支持批量验证，提高验证效率
  • 效果: 提高了配置文件的准确性，减少了配置错误，提高了用户体验

3 条踩坑与改进

踩坑 1: XML 解析库选择不当导致解析错误

  • 现象: 使用 XML 解析库时出现解析错误，无法正确解析 destructiveChanges.xml
  • 原因分析: 没有选择合适的 XML 解析库，或者没有正确配置 XML 解析库
  • 改进措施: 使用 Java 标准的 DocumentBuilderFactory 和 DocumentBuilder 解析 XML，正确配置 XML 解析库
  • 避免思路: 在 Prompt 中明确要求使用 Java 标准的 XML 解析库，提供详细的配置说明

踩坑 2: 备份数据不完整导致回滚失败

  • 现象: 回滚时发现备份数据不完整，无法恢复被删除的元数据组件
  • 原因分析: 没有在删除元数据组件之前完整备份元数据组件，或者备份数据存储不当
  • 改进措施: 在删除元数据组件之前完整备份元数据组件，使用事务确保备份数据的完整性
  • 避免思路: 在 Prompt 中明确要求在删除元数据组件之前完整备份元数据组件，使用事务确保备份数据的完整性

踩坑 3: 验证逻辑不完善导致误删除

  • 现象: 验证逻辑不完善，导致误删除元数据组件
  • 原因分析: 没有仔细验证 destructiveChanges.xml 格式和删除规则，或者验证逻辑不完善
  • 改进措施: 仔细验证 destructiveChanges.xml 格式和删除规则，提供详细的错误信息，支持预验证功能
  • 避免思路: 在 Prompt 中明确要求仔细验证 destructiveChanges.xml 格式和删除规则，提供详细的错误信息

Visual Debt

记录哪些代码修改了但还没来得及同步到 Canvas：

  • Authentication.canvas 需要更新 - 新增 Destructive Changes 功能节点
  • 其他 Canvas 文件: 无
  • 具体修改: 需要在 Authentication.canvas 中添加 Destructive Changes 功能相关的节点，包括 IDestructiveChangesService、DestructiveChangesServiceImpl、IDestructiveChangesConfigService、DestructiveChangesConfigServiceImpl、DestructiveChangesController 等

AI Tooling

Trae 读取 Canvas 时的表现：

  • 理解程度: Trae 对 Canvas 的理解程度良好，能够理解架构图中的节点和关系
  • 复杂逻辑: Trae 能够理解复杂的嵌套逻辑，包括 XML 解析和构建、备份和回滚机制、配置验证功能等设计模式
  • 改进建议: 可以在 Canvas 中添加更多的注释和说明，提高可读性，特别是对于复杂的 XML 解析和构建逻辑

模板更新记录

日期 模板名称 更新内容 更新原因
2026-01-19 020-destructive-changes.md 新增 Destructive Changes 功能实现提示词模板 支持 Destructive Changes 功能的实现
2026-01-19 0019-destructive-changes.md 新增 Destructive Changes 功能架构决策模板 支持 Destructive Changes 功能的架构决策

技能练习记录

技能领域 练习内容 练习效果 改进方向
XML 解析和构建 使用 Java XML 解析库处理 destructiveChanges.xml，提供 XML 解析和构建功能 提高了 XML 解析和构建的准确性，减少了 XML 格式错误 可以进一步优化 XML 解析和构建的性能，提高解析速度
备份和回滚机制 在删除元数据组件之前先备份元数据组件，使用事务确保回滚的原子性 提高了删除操作的安全性，确保数据可以恢复，降低了数据丢失风险 可以进一步优化备份和回滚的性能，提高回滚速度
配置验证功能 提供配置验证功能，验证 destructiveChanges.xml 格式和删除规则 提高了配置文件的准确性，减少了配置错误，提高了用户体验 可以进一步优化验证逻辑，提高验证速度和准确性
RESTful API 设计 使用 RESTful API 设计规范设计接口 提高了接口的可读性和可维护性，符合 RESTful API 设计规范 可以进一步优化接口的响应格式和错误处理
异步编程 复用 Spring 的 @Async 注解和自定义线程池实现异步执行 提高了系统的并发处理能力，支持并发部署 可以进一步优化线程池的参数配置和拒绝策略
事务管理 使用事务确保删除和回滚的原子性 确保了删除和回滚的原子性，避免了部分回滚导致数据不一致 可以进一步优化事务的隔离级别和传播行为

总结

本次迭代成功实现了 Destructive Changes 功能，包括 destructiveChanges.xml 配置、Destructive Changes 部署、Destructive Changes 验证、Destructive Changes 历史记录、Destructive Changes 回滚。所有功能均已实现，代码质量良好，测试覆盖率达标，文档完整。

通过本次迭代，我们积累了以下经验：

  1. 使用 Java XML 解析库处理 destructiveChanges.xml，提供 XML 解析和构建功能，提高了 XML 解析和构建的准确性
  2. 在删除元数据组件之前先备份元数据组件，使用事务确保回滚的原子性，提高了删除操作的安全性
  3. 提供配置验证功能，验证 destructiveChanges.xml 格式和删除规则，提高了配置文件的准确性
  4. 使用 RESTful API 设计规范，提高了接口的可读性和可维护性
  5. 复用 Spring 的 @Async 注解和自定义线程池实现异步执行，提高了系统的并发处理能力
  6. 使用事务确保删除和回滚的原子性，避免了部分回滚导致数据不一致

同时，我们也发现了一些问题：

  1. XML 解析库选择不当导致解析错误，需要使用 Java 标准的 XML 解析库
  2. 备份数据不完整导致回滚失败，需要在删除元数据组件之前完整备份元数据组件
  3. 验证逻辑不完善导致误删除，需要仔细验证 destructiveChanges.xml 格式和删除规则

这些问题都在本次迭代中得到了解决，并在 Prompt 中明确列出了所有需要的实现细节，避免类似问题的再次发生。

总体而言，本次迭代是一次成功的迭代，达成了所有的目标，为后续的开发工作奠定了良好的基础。