325 lines
12 KiB
Markdown
325 lines
12 KiB
Markdown
# 复盘文档
|
||
|
||
## 元数据
|
||
- 需求编号：004-01
|
||
- 复盘日期：2026-02-03
|
||
- 创建人：AI Assistant
|
||
- 状态：已完成
|
||
|
||
## 复盘概述
|
||
本次复盘对 Tooling API 连接管理功能的开发过程进行了全面回顾。从需求定义到变更记录归档，完整执行了 SSOT 流程的 8 个阶段。通过复盘总结了成功经验、识别了改进点、分析了遇到的问题，并制定了具体的行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
## 目标与实际产出对比
|
||
|
||
### 目标
|
||
- 实现 Tooling API 连接管理功能，包括获取连接、清除缓存、测试连接、设置调用选项、设置调试头部
|
||
- 采用工厂模式管理连接，继承 AbstractConnectionFactory
|
||
- 使用 ConcurrentHashMap 实现线程安全的连接缓存
|
||
- 提供完整的 RESTful API 接口（5 个接口）
|
||
- 实现完整的单元测试，测试覆盖率不低于 80%
|
||
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
|
||
### 实际产出
|
||
- ✅ 成功实现了 Tooling API 连接管理的 5 个核心功能
|
||
- ✅ 实现了 ToolingConnectionFactory，正确继承 AbstractConnectionFactory
|
||
- ✅ 使用 ConcurrentHashMap 实现线程安全的连接缓存
|
||
- ✅ 提供了 5 个 RESTful API 接口，符合 RESTful 规范
|
||
- ✅ 实现了 19 个单元测试用例，覆盖 Service、Factory、Controller 三层
|
||
- ✅ 严格按照 SSOT 流程执行，每个阶段都有相应的文档
|
||
- ✅ 生成了 11 个 Java 文件，代码结构清晰、规范
|
||
- ✅ 定义了 8 种错误类型，实现了完善的异常处理机制
|
||
|
||
## 成功经验
|
||
|
||
### 1. SSOT 流程的严格执行
|
||
从需求定义到变更记录归档，每个阶段都严格按照项目规则执行。这种规范化的流程确保了：
|
||
- 所有开发活动都有文档依据
|
||
- 代码的可追溯性和可维护性大大提高
|
||
- 团队成员可以快速理解需求和设计决策
|
||
- 减少了沟通成本和返工风险
|
||
|
||
### 2. 架构决策的科学性
|
||
在阶段 3 的架构决策中，对每个技术选型都进行了充分的分析和对比：
|
||
- 连接工厂架构选择了 AbstractConnectionFactory + SessionManager 方案
|
||
- 连接缓存策略选择了 ConcurrentHashMap 方案
|
||
- Session 有效性检查选择了执行简单 SOQL 查询方案
|
||
- 每个决策都有清晰的决策理由和影响分析
|
||
|
||
这种科学的决策方式为后续开发奠定了坚实的基础。
|
||
|
||
### 3. 详细的提示词设计
|
||
阶段 5 生成的提示词包含了：
|
||
- 明确的输出格式要求（8 个文件的具体路径和命名）
|
||
- 详细的代码规范要求（若依框架规范、Java 编码规范）
|
||
- 具体的测试要求（单元测试覆盖率不低于 80%）
|
||
- 清晰的注意事项（不创建 Mapper 和 Entity、固定使用 source ORG 类型）
|
||
|
||
这种详细的提示词设计确保了生成的代码符合项目规范和需求。
|
||
|
||
### 4. 代码复用和一致性
|
||
ToolingConnectionFactory 继承 AbstractConnectionFactory，复用了现有的连接管理基础设施：
|
||
- 统一的连接创建逻辑
|
||
- 一致的 Session 有效性检查机制
|
||
- 相同的异常处理方式
|
||
- 标准化的缓存管理策略
|
||
|
||
这种复用大大提高了开发效率，降低了维护成本。
|
||
|
||
### 5. 完整的单元测试
|
||
实现了 19 个单元测试用例，覆盖了：
|
||
- Service 层：8 个测试用例（获取连接、清除缓存、测试连接、设置调用选项、设置调试头部等）
|
||
- Factory 层：5 个测试用例（创建连接、缓存管理、Session 检查等）
|
||
- Controller 层：6 个测试用例（API 接口测试、权限控制测试等）
|
||
|
||
完整的单元测试确保了代码的质量和可靠性。
|
||
|
||
## 改进点
|
||
|
||
### 1. 阶段间的过渡可以更流畅
|
||
在阶段转换时，可以更主动地向用户解释：
|
||
- 下一阶段的目的和流程
|
||
- 需要用户确认的关键点
|
||
- 预计的产出物
|
||
|
||
这样可以提高用户的理解和参与度，减少等待时间。
|
||
|
||
### 2. 代码生成前的验证可以更严格
|
||
在生成代码前，可以增加：
|
||
- 对设计文档的再次验证
|
||
- 对决策记录的再次确认
|
||
- 对现有代码的兼容性检查
|
||
|
||
这样可以确保代码生成的准确性，减少返工。
|
||
|
||
### 3. 错误码的定义可以更系统化
|
||
当前错误码的定义虽然完整，但可以进一步：
|
||
- 建立错误码的层级结构
|
||
- 定义错误码的分配规则
|
||
- 建立错误码的维护机制
|
||
|
||
这样可以提高错误码的可维护性和可扩展性。
|
||
|
||
### 4. API 文档的示例可以更详细
|
||
API 文档中的示例可以进一步丰富：
|
||
- 增加更多的边界条件示例
|
||
- 提供不同场景下的请求/响应示例
|
||
- 增加错误场景的示例
|
||
|
||
这样可以提高 API 文档的实用性。
|
||
|
||
## 问题分析
|
||
|
||
### 问题 1：连接缓存的持久化问题
|
||
**问题描述**：当前连接缓存仅在内存中，应用重启后缓存丢失。
|
||
|
||
**根因分析**：
|
||
- 设计阶段考虑到当前需求不需要数据库交互
|
||
- 为了简化实现，选择了内存缓存方案
|
||
- 没有考虑到应用重启的场景
|
||
|
||
**影响**：
|
||
- 应用重启后需要重新创建连接
|
||
- 会增加 Salesforce API 的调用次数
|
||
- 用户体验会有短暂影响
|
||
|
||
**解决方案**：
|
||
- 短期：接受当前方案，在文档中明确说明限制
|
||
- 长期：考虑使用 Redis 等分布式缓存方案
|
||
|
||
### 问题 2：单元测试的 Mock 复杂度
|
||
**问题描述**：ToolingConnection 的单元测试需要大量 Mock，增加了测试复杂度。
|
||
|
||
**根因分析**：
|
||
- ToolingConnection 是第三方库（tooling.jar）的类
|
||
- 该类没有提供易于 Mock 的接口
|
||
- 测试需要模拟 Salesforce API 的响应
|
||
|
||
**影响**：
|
||
- 单元测试编写耗时较长
|
||
- 测试代码复杂度较高
|
||
- 测试的可维护性降低
|
||
|
||
**解决方案**：
|
||
- 使用 Mockito 的 spy 功能部分模拟 ToolingConnection
|
||
- 增加集成测试补充单元测试的不足
|
||
- 考虑封装 ToolingConnection 的适配器层，便于测试
|
||
|
||
### 问题 3：权限配置的同步问题
|
||
**问题描述**：Controller 中的权限注解与数据库中的权限配置需要手动同步。
|
||
|
||
**根因分析**：
|
||
- 权限注解在代码中定义
|
||
- 权限数据在数据库中存储
|
||
- 两者没有自动同步机制
|
||
|
||
**影响**：
|
||
- 容易遗漏权限配置
|
||
- 权限变更需要同时修改代码和数据库
|
||
- 增加了维护成本
|
||
|
||
**解决方案**：
|
||
- 建立权限配置的 checklist
|
||
- 考虑开发权限配置自动生成工具
|
||
- 在代码审查时增加权限配置的检查项
|
||
|
||
## 行动计划
|
||
|
||
| 序号 | 行动项 | 责任人 | 优先级 | 计划完成时间 | 状态 |
|
||
|------|--------|--------|--------|--------------|------|
|
||
| 1 | 在阶段转换时增加流程说明 | AI Assistant | 中 | 立即执行 | 待开始 |
|
||
| 2 | 增加代码生成前的验证步骤 | AI Assistant | 中 | 立即执行 | 待开始 |
|
||
| 3 | 建立错误码管理规范文档 | 项目团队 | 低 | 下一个迭代 | 待开始 |
|
||
| 4 | 完善 API 文档示例 | AI Assistant | 中 | 立即执行 | 待开始 |
|
||
| 5 | 评估分布式缓存方案（Redis） | 项目团队 | 低 | 下一个迭代 | 待开始 |
|
||
| 6 | 增加集成测试补充单元测试 | 项目团队 | 中 | 下一个迭代 | 待开始 |
|
||
| 7 | 建立权限配置 checklist | AI Assistant | 中 | 立即执行 | 待开始 |
|
||
|
||
## 提取模式
|
||
|
||
### 有效的 Prompt 技巧
|
||
|
||
#### 1. 引用真源
|
||
在提示词开头明确引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
|
||
|
||
**示例**：
|
||
```
|
||
请基于以下真源文档实现功能：
|
||
- 需求文档：[2026-01-28-004-01-连接管理.md](../requirements/sub/2026-01-28-004-01-连接管理.md)
|
||
- 设计文档：[2026-02-03-004-01-连接管理-设计.md](../design/2026-02-03-004-01-连接管理-设计.md)
|
||
```
|
||
|
||
#### 2. 具体的输出格式要求
|
||
在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
|
||
|
||
**示例**：
|
||
```
|
||
请生成以下文件：
|
||
1. Controller 类：`datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/ToolingConnectionController.java`
|
||
2. Service 接口：`datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IToolingConnectionService.java`
|
||
...
|
||
```
|
||
|
||
#### 3. 详细的代码规范要求
|
||
在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
|
||
|
||
**示例**：
|
||
```
|
||
代码规范要求：
|
||
- 遵循若依框架的代码规范
|
||
- 使用 Lombok 简化代码
|
||
- 添加 Swagger 注解（@Tag、@Operation）
|
||
- 使用统一的异常处理机制
|
||
```
|
||
|
||
### 避免的坑
|
||
|
||
#### 1. 不要使用模糊的描述
|
||
在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。
|
||
|
||
**错误示例**：
|
||
```
|
||
请生成高质量的 Tooling API 连接管理代码。
|
||
```
|
||
|
||
**正确示例**：
|
||
```
|
||
请实现 ToolingConnectionController 类，包含以下方法：
|
||
1. getConnection() - 获取连接，GET /salesforce/tooling/connection/get
|
||
2. clearConnection() - 清除缓存，DELETE /salesforce/tooling/connection/clear
|
||
...
|
||
```
|
||
|
||
#### 2. 不要忽略测试要求
|
||
在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
|
||
|
||
**错误示例**：
|
||
```
|
||
请实现 ToolingConnectionService 类。
|
||
```
|
||
|
||
**正确示例**：
|
||
```
|
||
请实现 ToolingConnectionService 类，并编写单元测试：
|
||
- 单元测试覆盖率不低于 80%
|
||
- 测试正常场景和异常场景
|
||
- 使用 Mockito 进行 Mock
|
||
```
|
||
|
||
#### 3. 不要违反项目规则
|
||
在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。
|
||
|
||
**错误示例**：
|
||
```
|
||
请使用自定义的异常处理机制。
|
||
```
|
||
|
||
**正确示例**：
|
||
```
|
||
请使用若依框架的统一异常处理机制（AjaxResult）。
|
||
```
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
|
||
|
||
### 1. 增加架构一致性检查项
|
||
在提示词中增加对架构一致性的检查要求：
|
||
```
|
||
架构一致性检查：
|
||
- [ ] 是否正确继承了 AbstractConnectionFactory
|
||
- [ ] 是否正确使用了 SessionManager
|
||
- [ ] 是否遵循了现有的包结构规范
|
||
- [ ] 是否使用了统一的异常处理机制
|
||
```
|
||
|
||
### 2. 增加测试复杂度评估
|
||
在提示词中增加对测试复杂度的评估和应对策略：
|
||
```
|
||
测试策略：
|
||
- 识别需要 Mock 的外部依赖
|
||
- 评估 Mock 的复杂度
|
||
- 确定是否需要集成测试补充
|
||
- 制定测试数据准备方案
|
||
```
|
||
|
||
### 3. 增加权限配置 checklist
|
||
在提示词中增加权限配置的 checklist：
|
||
```
|
||
权限配置 checklist：
|
||
- [ ] Controller 方法添加了 @PreAuthorize 注解
|
||
- [ ] 权限字符串符合命名规范（模块:功能:操作）
|
||
- [ ] 数据库中配置了对应的权限数据
|
||
- [ ] 权限配置文档已更新
|
||
```
|
||
|
||
计划在下一个迭代中更新提示词模板，增加上述内容。
|
||
|
||
## 数据洞察
|
||
|
||
### 开发效率
|
||
- **总耗时**：约 40 分钟（阶段 5 到阶段 8）
|
||
- **文档数量**：8 个文档（需求、设计、决策、提示词、会话、变更日志、复盘、API）
|
||
- **代码文件**：11 个 Java 文件
|
||
- **测试用例**：19 个单元测试
|
||
|
||
### 代码质量
|
||
- **代码规范**：符合若依框架规范
|
||
- **单元测试覆盖率**：预计 80% 以上
|
||
- **接口数量**：5 个 REST API 接口
|
||
- **错误码数量**：8 种错误类型
|
||
|
||
### 文档完整性
|
||
- **需求文档**：完整，包含功能描述、入参/出参、实现要点
|
||
- **设计文档**：完整，包含架构设计、技术方案、接口设计
|
||
- **决策记录**：完整，包含 4 个关键决策及其理由
|
||
- **变更日志**：完整，包含详细的变更内容和影响分析
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-004-01-连接管理.md)
|
||
- [设计文档](../design/2026-02-03-004-01-连接管理-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-004-01-ADR-连接管理技术选型.md)
|
||
- [提示词](../prompts/2026-02-03-004-01-prompt-Tooling连接管理.md)
|
||
- [变更日志](../changelog/2026-02-03-004-01-changelog.md)
|
||
- [会话记录](../sessions/2026-02-03-004-01-session.md)
|
||
- [API 文档](../api-docs/2026-02-03-004-01-api.md)
|