314 lines
11 KiB
Markdown
314 lines
11 KiB
Markdown
# 复盘文档：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 模拟外部依赖
|
||
- 覆盖正常流程和异常流程
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](../requirements/sub/2026-01-28-003-04-异步操作.md)
|
||
- [设计文档](../design/2026-02-03-003-04-异步操作-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-003-04-ADR-异步操作轮询策略.md)
|
||
- [提示词文档](../prompts/2026-02-03-003-04-prompt-异步操作.md)
|
||
- [会话记录](../sessions/2026-02-06-003-04-session.md)
|
||
- [变更日志](../changelog/2026-02-06-003-04-changelog.md)
|
||
- [API 文档](../api-docs/2026-02-06-003-04-api.md)
|
||
- [父需求 - MetadataAPI源org实现](../requirements/2026-01-28-003-MetadataAPI源org实现.md)
|