330 lines
20 KiB
Markdown
330 lines
20 KiB
Markdown
# 复盘文档 - Apex 连接管理
|
||
|
||
## 元数据
|
||
- 需求编号：002-01
|
||
- 需求名称：Apex 连接管理
|
||
- 创建时间：2026-02-02
|
||
- 创建人：AI Assistant
|
||
- 状态：已完成
|
||
|
||
## 复盘概述
|
||
本次复盘对 Apex 连接管理功能的开发过程进行了全面回顾，从需求定义到变更记录的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
## 目标与实际产出对比
|
||
|
||
### 目标
|
||
- 实现 Salesforce Apex API 连接管理功能，包括连接工厂、会话头管理、调用选项配置、调试头部配置、字段截断头配置、包版本头配置和连接缓存管理等功能
|
||
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
- 生成符合项目规范的代码，包括 7 个 REST API 接口
|
||
- 固定使用 source org 类型
|
||
- 继承 AbstractConnectionFactory<SoapConnection>，复用缓存机制
|
||
|
||
### 实际产出
|
||
- 成功实现了 Salesforce Apex API 连接管理功能，包括连接工厂、会话头管理、调用选项配置、调试头部配置、字段截断头配置、包版本头配置和连接缓存管理等功能
|
||
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档
|
||
- 生成的代码符合项目规范，包括 10 个 Java 文件（1 个 Factory、1 个 Service 接口、1 个 Service 实现、1 个 Controller、5 个 DTO、1 个 VO）
|
||
- 成功实现了 7 个 REST API 接口
|
||
- 固定使用 source org 类型
|
||
- 成功继承 AbstractConnectionFactory<SoapConnection>，复用缓存机制
|
||
- 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
|
||
- 生成了完整的设计文档、决策记录、提示词文档、会话记录和变更日志
|
||
|
||
## 成功经验
|
||
|
||
### 1. SSOT 流程的严格执行
|
||
从需求定义到变更记录的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。每个阶段都生成了相应的文档，包括设计文档、决策记录、提示词文档、会话记录和变更日志，确保了开发过程的透明性和可追溯性。
|
||
|
||
### 2. 详细的提示词设计
|
||
阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。提示词明确列出了需要生成的文件清单、REST API 接口列表、代码规范要求（命名规范、注释规范、日志规范、异常处理）和测试要求（覆盖率不低于 80%，包含正常和异常场景），大大提高了代码生成的准确性和质量。
|
||
|
||
### 3. 完整的会话记录
|
||
阶段 7 和阶段 8 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。会话记录包含了所有执行阶段的状态和关键决策，所有生成的文档和代码文件列表，以及关键决策和理由，为后续的复盘和改进提供了宝贵的数据支持。
|
||
|
||
### 4. 与现有架构保持一致
|
||
在技术选型和代码实现过程中，始终与现有架构保持一致。选择了 AbstractConnectionFactory + SessionManager 方案，复用了现有的基础设施，提高了开发效率，降低了维护成本。代码实现符合 Spring Boot 最佳实践和若依框架规范，使用了 Lombok 简化代码，使用 Swagger 注解生成 API 文档，使用 Spring Security 进行权限控制，确保了代码的一致性和可维护性。
|
||
|
||
### 5. 高效的代码生成
|
||
基于详细的提示词，一次性生成了所有需要的代码文件，包括 10 个 Java 文件和 7 个 REST API 接口。代码生成过程高效、准确，生成的代码符合项目规范，包含完整的异常处理和日志记录，大大提高了开发效率。
|
||
|
||
## 改进点
|
||
|
||
### 1. 阶段间的过渡可以更流畅
|
||
在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。例如，在进入阶段 3（方案决策）时，可以更详细地解释 ADR 的作用和重要性，以及如何进行技术方案的比较和选择。这样可以提高用户的参与度，确保用户理解每个阶段的目的和价值。
|
||
|
||
### 2. API 文档的自动生成可以考虑
|
||
当前 API 文档是手动编写的，虽然详细但耗时。可以考虑使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。Swagger 可以从代码注解中自动生成 API 文档，包括请求参数、响应参数、示例等，大大减少了手动编写的工作量，提高了文档的准确性和一致性。
|
||
|
||
### 3. 单元测试的生成可以更完善
|
||
虽然提示词中提到了测试要求（覆盖率不低于 80%，包含正常和异常场景），但实际生成的代码中没有包含单元测试。在后续的代码生成中，可以增加单元测试的生成，确保代码的质量和可靠性。单元测试可以包括对每个服务方法的测试，包括正常场景、异常场景和边界场景，确保代码的正确性和健壮性。
|
||
|
||
### 4. 代码注释可以更详细
|
||
生成的代码虽然包含注释，但部分注释可以更详细。例如，在 ApexConnectionFactory 的 createConnection() 方法中，可以更详细地解释每个步骤的作用和原因，包括为什么使用 API 65.0 版本，为什么设置连接超时为 60 秒等。这样可以提高代码的可读性和可维护性，帮助其他开发人员更好地理解代码。
|
||
|
||
### 5. 错误处理可以更统一
|
||
虽然代码中使用了统一的异常类（SalesforceAuthException、SalesforceOperationException），但错误消息的格式可以更统一。例如，可以定义一个错误消息模板，确保所有错误消息的格式一致，包括错误代码、错误消息、错误详情等。这样可以提高错误处理的一致性和可维护性，帮助前端更好地处理和显示错误信息。
|
||
|
||
## 问题分析
|
||
|
||
### 问题 1：阶段 4 被跳过
|
||
**问题描述**：在阶段 4（数据库结构生成）时，发现本需求不涉及数据库变更，因此跳过了此阶段。
|
||
|
||
**根因分析**：
|
||
- Apex 连接管理功能主要依赖 Salesforce 的外部 API，不需要本地数据库存储
|
||
- 会话信息通过 SessionManager 管理，存储在现有表中
|
||
- 连接信息通过 AbstractConnectionFactory 的内存缓存管理，不需要持久化
|
||
- 所有配置信息（如 API 版本、超时时间）通过代码或配置文件管理
|
||
|
||
**解决方案**：
|
||
- 在需求分析阶段，提前识别是否涉及数据库变更
|
||
- 如果不涉及数据库变更，在阶段 4 明确说明原因，并记录在会话记录中
|
||
- 在后续的需求中，提前进行数据库变更分析，避免阶段 4 的跳过
|
||
|
||
**预防措施**：
|
||
- 在需求定义阶段，增加"是否涉及数据库变更"的明确说明
|
||
- 在设计文档中，增加"数据模型设计"章节，明确说明是否需要数据库表
|
||
- 在决策记录中，记录是否涉及数据库变更的决策和理由
|
||
|
||
### 问题 2：代码生成后未进行验证
|
||
**问题描述**：在阶段 6（执行代码生成）后，生成的代码没有进行验证，直接进入了阶段 7（记录当前会话）。
|
||
|
||
**根因分析**：
|
||
- 提示词中包含了详细的代码规范要求，但没有明确要求进行代码验证
|
||
- 用户没有要求进行代码验证
|
||
- AI Assistant 没有主动进行代码验证
|
||
|
||
**解决方案**：
|
||
- 在提示词中增加代码验证要求，包括编译检查、代码风格检查、单元测试等
|
||
- 在代码生成后，主动进行代码验证，确保代码的正确性和质量
|
||
- 在进入下一阶段前，向用户确认代码是否正确
|
||
|
||
**预防措施**：
|
||
- 在提示词模板中增加代码验证要求
|
||
- 在阶段 6 的验收清单中增加代码验证检查项
|
||
- 在阶段转换时，主动向用户确认代码是否正确
|
||
|
||
## 行动计划
|
||
|
||
### 针对改进点 1：阶段间的过渡可以更流畅
|
||
- **行动项**：在阶段转换时，增加对下一阶段的目的和流程的解释
|
||
- **责任人**：AI Assistant
|
||
- **时间节点**：立即执行
|
||
- **预期效果**：提高用户的理解和参与度，确保用户理解每个阶段的目的和价值
|
||
|
||
### 针对改进点 2：API 文档的自动生成可以考虑
|
||
- **行动项**：探索使用 Swagger 等工具自动生成 API 文档
|
||
- **责任人**：项目团队
|
||
- **时间节点**：下一个迭代
|
||
- **预期效果**：提高文档的准确性和维护性，减少手动编写的工作量
|
||
|
||
### 针对改进点 3：单元测试的生成可以更完善
|
||
- **行动项**：在后续的代码生成中，增加单元测试的生成
|
||
- **责任人**：AI Assistant
|
||
- **时间节点**：立即执行
|
||
- **预期效果**：确保代码的质量和可靠性，提高测试覆盖率
|
||
|
||
### 针对改进点 4：代码注释可以更详细
|
||
- **行动项**：在代码生成中，增加更详细的代码注释
|
||
- **责任人**：AI Assistant
|
||
- **时间节点**：立即执行
|
||
- **预期效果**：提高代码的可读性和可维护性，帮助其他开发人员更好地理解代码
|
||
|
||
### 针对改进点 5：错误处理可以更统一
|
||
- **行动项**：定义统一的错误消息模板，确保所有错误消息的格式一致
|
||
- **责任人**：项目团队
|
||
- **时间节点**：下一个迭代
|
||
- **预期效果**：提高错误处理的一致性和可维护性，帮助前端更好地处理和显示错误信息
|
||
|
||
### 针对问题 1：阶段 4 被跳过
|
||
- **行动项**：在需求分析阶段，提前识别是否涉及数据库变更
|
||
- **责任人**：AI Assistant
|
||
- **时间节点**：立即执行
|
||
- **预期效果**：避免阶段 4 的跳过，确保所有阶段都得到执行
|
||
|
||
### 针对问题 2：代码生成后未进行验证
|
||
- **行动项**：在代码生成后，主动进行代码验证
|
||
- **责任人**：AI Assistant
|
||
- **时间节点**：立即执行
|
||
- **预期效果**：确保代码的正确性和质量，提高代码的可靠性
|
||
|
||
## 提取模式
|
||
|
||
### 有效的 Prompt 技巧
|
||
|
||
#### 1. 具体的输出格式要求
|
||
在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。例如，在本次提示词中，明确列出了需要生成的 10 个 Java 文件的路径和说明，以及 7 个 REST API 接口的请求路径和方法，确保了生成的代码符合预期。
|
||
|
||
#### 2. 引用真源
|
||
在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。例如，在本次提示词中，引用了需求文档、设计文档和决策记录的链接，确保了生成的代码符合需求和设计要求，避免了代码与需求不一致的问题。
|
||
|
||
#### 3. 详细的代码规范要求
|
||
在提示词中明确指定代码规范、命名规范、注释规范、日志规范、异常处理等，可以提高生成代码的质量和可读性。例如，在本次提示词中，详细说明了命名规范（类名使用大驼峰，方法名使用小驼峰，常量使用全大写下划线分隔）、注释规范（类注释、方法注释、字段注释）、日志规范（使用 SLF4J + Logback，日志级别使用 INFO、WARN、ERROR）、异常处理（使用统一的异常类，详细的错误日志记录），确保了生成的代码符合项目规范。
|
||
|
||
### 避免的坑
|
||
|
||
#### 1. 不要使用模糊的描述
|
||
在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。例如，如果只说"请生成高质量的代码"，AI 可能会生成代码风格不一致、注释不完整、异常处理不充分的代码。相反，应该使用具体的描述，如"请生成符合 Spring Boot 最佳实践和若依框架规范的代码，使用 Lombok 简化代码，使用 Swagger 注解生成 API 文档，使用 Spring Security 进行权限控制"。
|
||
|
||
#### 2. 不要忽略测试要求
|
||
在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。例如，如果提示词中没有提到测试要求，AI 可能不会生成单元测试，导致代码的质量和可靠性无法保证。相反，应该在提示词中明确说明测试要求，如"单元测试覆盖率不低于 80%，包含正常场景、异常场景和边界场景"。
|
||
|
||
#### 3. 不要违反项目规则
|
||
在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。例如，如果生成的代码不使用若依框架的 AjaxResult 作为统一响应格式，不使用 @PreAuthorize 注解进行权限控制，不使用 @Valid 注解进行参数校验，会导致代码不符合项目要求，需要重新生成。相反，应该严格遵守项目规则，确保生成的代码符合项目要求。
|
||
|
||
## 代码重新生成经验（2026-02-04）
|
||
|
||
### 重新生成背景
|
||
在 2026-02-04，对 Apex 连接管理功能的代码进行了重新生成（v1.1.0），主要目的是优化代码结构，确保与需求文档完全一致。
|
||
|
||
### 重新生成过程
|
||
1. **快速阶段检查**：由于之前已完成阶段 1-5，本次重新生成直接从阶段 6 开始
|
||
2. **代码重新生成**：基于现有的提示词文档，重新生成了 10 个 Java 文件
|
||
3. **变更记录更新**：更新了根目录 CHANGELOG.md 和 docs/changelog/ 下的变更日志
|
||
4. **文档状态更新**：更新了索引、需求文档和会话记录
|
||
|
||
### 重新生成收获
|
||
|
||
#### 1. 现有文档的价值
|
||
- 设计文档、决策记录、提示词文档等现有文档为代码重新生成提供了坚实的基础
|
||
- 不需要重新进行需求分析和方案设计，大大节省了时间
|
||
- 提示词文档的详细程度确保了重新生成的代码质量
|
||
|
||
#### 2. 代码重新生成的效率
|
||
- 基于详细的提示词，一次性重新生成了所有代码文件
|
||
- 重新生成的代码结构更清晰，实现更规范
|
||
- 整个过程耗时较短，效率高
|
||
|
||
#### 3. 变更记录的重要性
|
||
- 及时更新变更日志，记录了代码重新生成的原因和内容
|
||
- 版本号管理（v1.1.0）清晰标识了代码的演进
|
||
- 向后兼容的承诺确保了 API 接口的稳定性
|
||
|
||
### 重新生成改进点
|
||
|
||
#### 1. 代码结构优化
|
||
- **ApexConnectionFactory**：完善了连接创建逻辑，增强了异常处理机制
|
||
- **ApexConnectionServiceImpl**：优化了参数校验逻辑，完善了头部设置逻辑
|
||
- **ApexConnectionController**：统一了接口响应格式，完善了 Swagger 文档
|
||
- **DTO 和 VO 类**：完善了注解和注释，提高了代码可读性
|
||
|
||
#### 2. 代码质量提升
|
||
- 增强了异常处理的完整性
|
||
- 完善了日志记录的详细程度
|
||
- 优化了代码注释的准确性
|
||
- 统一了代码风格
|
||
|
||
### 重新生成经验总结
|
||
1. **文档驱动开发的优势**：完善的文档体系支持代码的快速重新生成
|
||
2. **版本管理的重要性**：通过版本号管理代码演进，确保可追溯性
|
||
3. **向后兼容的承诺**：API 接口保持不变，确保现有调用方的稳定性
|
||
4. **持续改进的价值**：代码重新生成是持续改进的一部分，不断提高代码质量
|
||
|
||
## 代码编译问题修复经验（2026-02-04）
|
||
|
||
### 修复背景
|
||
在代码重新生成后，进行编译检查时发现多个编译错误，需要修复以确保代码可以正常编译和运行。
|
||
|
||
### 修复的问题清单
|
||
|
||
#### 1. SalesforceOperationException 类型问题
|
||
**问题**：`SalesforceOperationException` 继承 `Exception`（受检异常），导致 Controller 方法必须处理此异常。
|
||
**修复**：将 `SalesforceOperationException` 改为继承 `RuntimeException`，成为运行时异常。
|
||
**经验**：所有自定义异常应该继承 `RuntimeException`，便于 Spring 全局异常处理器统一处理。
|
||
|
||
#### 2. ApexCompileServiceImpl 中的 API 调用问题
|
||
**问题**：`getConnection()` 方法调用缺少 `orgType` 参数。
|
||
**修复**：添加 `ORG_TYPE = "source"` 常量，所有调用传入该参数。
|
||
**经验**：在使用工厂模式时，确保方法签名和调用一致。
|
||
|
||
#### 3. 方法不存在问题
|
||
**问题**：`ExecuteAnonymousResult.getLogId()`、`CompileClassResult.getProblemType()` 等方法不存在。
|
||
**修复**：移除不存在的 API 调用，或提供替代实现（如手动计算代码覆盖率）。
|
||
**经验**：在编写代码前，必须仔细查阅 Salesforce API 文档，确保调用的方法存在。
|
||
|
||
#### 4. 参数类型不匹配问题
|
||
**问题**：`setCreateTime()` 需要 `Date` 类型，但传入 `LocalDateTime`；`setTests()` 需要 `TestsNode[]` 类型，但传入 `String[]`。
|
||
**修复**：进行类型转换，或移除不支持的参数设置。
|
||
**经验**：注意 Java 8 日期时间 API 与传统 `Date` 类型的转换，以及复杂类型参数的匹配。
|
||
|
||
#### 5. ApexConnectionServiceImpl 中的 API 调用问题
|
||
**问题**：`SoapConnection` 的方法签名与预期不符，如 `setSessionHeader()` 接受 `String` 而非 `SessionHeader_element`。
|
||
**修复**：根据实际的 Salesforce Apex API 签名调整代码。
|
||
**经验**：Salesforce 的不同 API（Partner、Tooling、Apex、Metadata）有不同的方法签名，不能混用。
|
||
|
||
### 修复收获
|
||
|
||
#### 1. 编译检查的重要性
|
||
- 代码生成后必须进行编译检查，确保代码可以正常编译
|
||
- 编译错误是代码质量的第一道防线
|
||
- 及时修复编译错误可以避免运行时错误
|
||
|
||
#### 2. API 文档的仔细查阅
|
||
- 在使用第三方 API 时，必须仔细查阅官方文档
|
||
- 不能假设不同 API 的方法签名一致
|
||
- 需要通过实际查阅源码或文档确认方法签名
|
||
|
||
#### 3. 类型安全的重要性
|
||
- Java 是强类型语言，类型不匹配会导致编译错误
|
||
- 在使用新 API（如 Java 8 日期时间 API）时，注意与传统类型的转换
|
||
- 复杂类型参数需要特别注意类型匹配
|
||
|
||
#### 4. 异常处理的最佳实践
|
||
- 自定义异常应该继承 `RuntimeException`
|
||
- 利用 Spring 的全局异常处理器统一处理异常
|
||
- Controller 层不应该处理受检异常
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板（`docs/Prompt/0000-template.md`）在以下几个方面可以改进：
|
||
|
||
### 1. 代码验证要求
|
||
当前模板中没有明确的代码验证要求。计划在下一个迭代中更新提示词模板，增加代码验证要求，包括：
|
||
- 编译检查：确保代码可以正常编译
|
||
- 代码风格检查：确保代码符合项目代码风格
|
||
- 单元测试：确保代码包含单元测试，覆盖率不低于 80%
|
||
|
||
### 2. 阶段过渡说明
|
||
当前模板中没有明确的阶段过渡说明。计划在下一个迭代中更新提示词模板，增加阶段过渡说明，包括：
|
||
- 在阶段转换时，向用户解释下一阶段的目的和流程
|
||
- 在阶段转换时，向用户展示上一阶段的成果
|
||
- 在阶段转换时，向用户确认是否进入下一阶段
|
||
|
||
### 3. 单元测试生成要求
|
||
当前模板中的测试要求不够具体。计划在下一个迭代中更新提示词模板，增加更具体的单元测试生成要求，包括：
|
||
- 每个服务方法都需要对应的单元测试
|
||
- 单元测试需要包含正常场景、异常场景和边界场景
|
||
- 单元测试需要使用 JUnit 5 + Mockito
|
||
- 单元测试覆盖率不低于 80%
|
||
|
||
### 4. 代码注释要求
|
||
当前模板中的代码注释要求不够具体。计划在下一个迭代中更新提示词模板，增加更具体的代码注释要求，包括：
|
||
- 类注释：包含类的功能描述、作者、创建时间
|
||
- 方法注释：包含方法的功能描述、参数说明、返回值说明、异常说明
|
||
- 字段注释：包含字段的功能描述、类型说明
|
||
- 关键逻辑注释：包含关键逻辑的说明和原因
|
||
|
||
### 5. 错误处理要求
|
||
当前模板中的错误处理要求不够具体。计划在下一个迭代中更新提示词模板，增加更具体的错误处理要求，包括：
|
||
- 使用统一的异常类（SalesforceAuthException、SalesforceOperationException）
|
||
- 错误消息格式统一，包括错误代码、错误消息、错误详情
|
||
- 详细的错误日志记录，包括错误时间、错误位置、错误原因、错误堆栈
|
||
|
||
## 相关文档
|
||
|
||
### 需求文档
|
||
- [Apex 连接管理需求](../requirements/sub/2026-01-28-002-01-连接管理.md)
|
||
|
||
### 设计文档
|
||
- [Apex 连接管理设计](../design/2026-02-02-002-01-连接管理-设计.md)
|
||
|
||
### 决策记录
|
||
- [Apex 连接管理技术选型](../decisions/2026-02-02-002-01-ADR-Apex连接管理技术选型.md)
|
||
|
||
### 提示词文档
|
||
- [Apex 连接管理提示词](../prompts/2026-02-02-002-01-prompt-Apex连接管理.md)
|
||
|
||
### 会话记录
|
||
- [Apex 连接管理会话记录](../sessions/2026-02-02-002-01-session.md)
|
||
|
||
### 变更日志
|
||
- [Apex 连接管理变更日志](../changelog/2026-02-02-002-01-changelog.md)
|