11 KiB
复盘文档：003-04 异步操作
元数据
- 需求编号: 003-04
- 需求名称: 异步操作
- 创建时间: 2026-02-06
- 创建人: AI Assistant
- 状态: 已完成
复盘概述
本次复盘对 003-04 异步操作功能的开发过程进行了全面回顾。该功能是 Metadata API 管理模块的重要组成部分，为部署操作（003-03）和其他异步操作提供状态管理能力。复盘从需求定义到代码提交的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
目标与实际产出对比
目标
- 实现 Metadata API 异步操作管理模块
- 提供异步操作状态查询、服务端同步轮询、异步操作取消、操作历史记录功能
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
- 生成符合项目规范的代码
- 复用现有表结构，避免重复创建
实际产出
- ✅ 成功实现了异步操作管理功能，包括状态查询、服务端同步轮询、取消操作、历史记录
- ✅ 严格按照 SSOT 流程执行，每个阶段都有相应的文档
- ✅ 生成的代码符合项目规范，遵循若依框架和项目既有模式
- ✅ 复用了现有的
datai_metadata_async表，无需新建表 - ✅ 生成了 5 个新代码文件，修改了 1 个文件
- ✅ 提供了 5 个 REST API 接口，满足前端调用需求
成功经验
1. 复用现有代码和表结构的策略成功
经验描述: 在开发前充分调研了现有代码，发现已经存在 datai_metadata_async 表和基础的 CRUD 操作，决定复用现有表结构并扩展业务方法。
成功原因:
- 在阶段 1（需求定义）中明确了复用现有表的目标
- 在阶段 2（方案设计）中确认了复用策略的可行性
- 避免了重复创建表和基础代码，减少了开发工作量
- 保持了数据模型的一致性
可推广性: 高。在后续开发中，应继续遵循"先调研、后开发"的原则，充分复用现有资源。
2. 清晰的架构决策（ADR）指导实现
经验描述: 在阶段 3 创建了详细的 ADR 文档，明确了服务端同步轮询策略，为后续代码实现提供了清晰的指导。
成功原因:
- ADR 文档详细对比了三种轮询策略的优缺点
- 明确记录了决策理由：简单可靠、实现成本低、简化上层业务代码
- 为代码实现提供了明确的参数指导（轮询间隔 5 秒、超时 5 分钟）
可推广性: 高。对于技术方案选择，应继续编写 ADR 文档，记录决策过程和理由。
3. 分层架构设计确保代码质量
经验描述: 严格按照 Controller → Service → Factory → Metadata API 的分层架构设计代码。
成功原因:
- Controller 层专注于请求处理和参数校验
- Service 层专注于业务逻辑和异常处理
- Factory 层专注于连接管理
- 各层职责清晰，便于维护和测试
可推广性: 高。继续遵循分层架构设计原则，确保代码的可维护性。
4. 完善的异常处理机制
经验描述: 实现了详细的异常转换规则，将 Salesforce 异常转换为业务异常。
成功原因:
- 针对不同的错误类型（InvalidSessionId、Unauthorized、InvalidAsyncId 等）提供了特定的异常处理
- 异常信息清晰，便于前端展示和问题定位
- 异常处理不影响主流程，数据库记录失败不会中断业务
可推广性: 高。在后续开发中，继续完善异常处理机制。
5. 详细的日志记录
经验描述: 在关键操作点（状态查询、轮询、取消）都添加了详细的日志记录。
成功原因:
- 使用 SLF4J 日志框架，支持不同级别的日志
- 日志信息包含关键参数（asyncId、state、轮询次数等）
- 便于问题排查和性能监控
可推广性: 高。继续遵循"关键操作必记录日志"的原则。
改进点
1. Mapper XML 的 SQL 实现可以同步完成
改进描述: 在代码生成阶段，Mapper 接口添加了新方法，但对应的 XML SQL 实现未同步完成。
具体措施:
- 在生成 Java 代码的同时，同步生成对应的 XML SQL
- 建立 Mapper 接口方法与 XML 的对应检查清单
优先级: 中 责任人: AI Assistant 时间节点: 立即执行
2. 单元测试可以在代码生成阶段同步完成
改进描述: 代码生成阶段未同步生成单元测试，需要后续补充。
具体措施:
- 在提示词中明确要求生成单元测试
- 使用 Mockito 模拟 Salesforce API 调用
- 覆盖正常流程和异常流程
优先级: 中 责任人: AI Assistant 时间节点: 下一个迭代
3. API 文档的示例可以更丰富
改进描述: API 文档中的请求/响应示例可以包含更多场景（成功、失败、超时等）。
具体措施:
- 在 API 文档中增加多种场景的示例
- 包含错误响应的示例
- 提供 curl 命令示例
优先级: 低 责任人: AI Assistant 时间节点: 下一个迭代
4. 可以考虑添加性能监控
改进描述: 异步操作轮询可能耗时较长（最多 5 分钟），可以考虑添加性能监控。
具体措施:
- 记录轮询次数和耗时
- 添加性能指标收集（如 Micrometer）
- 提供性能监控接口
优先级: 低 责任人: 项目团队 时间节点: 下一个迭代
问题分析
问题 1: 代码生成时未同步检查依赖项
问题描述: 在生成 MetadataAsyncServiceImpl 时，发现 DataiMetadataAsyncMapper 缺少需要的方法，需要后续添加。
根因分析:
- 代码生成前未充分检查 Mapper 接口的完整性
- 提示词中未明确要求检查依赖项
影响:
- 需要额外修改 Mapper 接口
- 增加了开发步骤
解决方案:
- 在代码生成前，先检查所有依赖项的完整性
- 在提示词中增加"检查依赖项"的要求
- 建立依赖项检查清单
预防措施:
- 在阶段 6 开始前，先检查所有依赖项
- 更新提示词模板，增加依赖项检查要求
问题 2: 权限配置未在代码生成阶段完成
问题描述: 代码中使用了新的权限点（salesforce:metadata:async:query、salesforce:metadata:async:cancel），但未在代码生成阶段同步配置权限。
根因分析:
- 权限配置分散在多个文件中，容易遗漏
- 提示词中未明确要求配置权限
影响:
- 需要后续手动配置权限
- 可能导致权限不生效
解决方案:
- 在代码生成阶段，同步生成权限配置
- 在提示词中增加权限配置要求
- 建立权限配置检查清单
预防措施:
- 更新提示词模板，增加权限配置要求
- 在代码生成后检查权限配置
行动计划
| 序号 | 行动项 | 责任人 | 时间节点 | 优先级 |
|---|---|---|---|---|
| 1 | 补充 Mapper XML 的 SQL 实现 | AI Assistant | 立即执行 | 高 |
| 2 | 编写单元测试 | AI Assistant | 下一个迭代 | 中 |
| 3 | 配置权限 | AI Assistant | 立即执行 | 高 |
| 4 | 更新提示词模板，增加依赖项检查要求 | AI Assistant | 立即执行 | 中 |
| 5 | 探索性能监控方案 | 项目团队 | 下一个迭代 | 低 |
提取模式
有效的 Prompt 技巧
1. 明确的复用策略
技巧描述: 在提示词开头明确说明复用现有资源的策略。
示例:
## 复用策略
- 复用现有的 `datai_metadata_async` 表
- 复用 `MetadataConnectionFactory` 进行连接管理
- 复用现有的异常类（SalesforceAuthException、SalesforceOperationException）
效果: 确保生成的代码与现有系统保持一致，避免重复创建。
2. 详细的接口定义
技巧描述: 在提示词中提供详细的接口定义，包括方法签名、参数、返回值。
示例:
## Service 接口定义
### getAsyncResult(String asyncId)
- 功能：获取异步操作结果
- 参数：asyncId - 异步操作 ID
- 返回：AsyncResultVo
- 异常：SalesforceAuthException、SalesforceOperationException
效果: 生成的代码更符合设计要求，减少修改次数。
3. 异常处理规范
技巧描述: 在提示词中明确异常转换规则和错误处理要求。
示例:
## 异常处理
- InvalidSessionId / Session expired → SalesforceAuthException
- Unauthorized → SalesforceAuthException
- InvalidAsyncId → SalesforceOperationException
- 其他 → SalesforceOperationException
效果: 生成的代码具有统一的异常处理机制。
避免的坑
1. 不要忽略依赖项检查
坑描述: 在代码生成时未检查依赖项，导致生成的代码无法编译。
避免方法:
- 在代码生成前，先检查所有依赖项
- 建立依赖项检查清单
- 在提示词中明确要求检查依赖项
2. 不要遗漏权限配置
坑描述: 代码中使用了新的权限点，但未同步配置权限。
避免方法:
- 在代码生成阶段，同步生成权限配置
- 建立权限配置检查清单
- 在提示词中增加权限配置要求
3. 不要忽略数据库持久化
坑描述: 业务逻辑中缺少数据库持久化，导致操作记录丢失。
避免方法:
- 在提示词中明确要求数据库持久化
- 在代码生成后检查持久化逻辑
- 建立持久化检查清单
模板迭代
经过本次复盘，发现当前的提示词模板可以在以下方面改进：
1. 增加依赖项检查要求
在提示词模板中增加"依赖项检查"章节，要求：
- 列出所有依赖的类和方法
- 检查依赖项是否存在
- 如不存在，先创建依赖项
2. 增加权限配置要求
在提示词模板中增加"权限配置"章节，要求：
- 列出所有使用的权限点
- 生成权限配置代码
- 提供权限配置检查清单
3. 增加数据库持久化要求
在提示词模板中增加"数据库持久化"章节，要求：
- 明确持久化策略（插入/更新）
- 处理持久化异常（不影响主流程）
- 记录创建人和更新人
4. 增加单元测试要求
在提示词模板中增加"单元测试"章节，要求：
- 为每个 Service 方法生成单元测试
- 使用 Mockito 模拟外部依赖
- 覆盖正常流程和异常流程