kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3d290a8dd1
datai/docs/archive/retros/2026-01-28-013-1-retro.md

12 KiB
Raw Blame History

Apex 编译器接口与错误处理 - 复盘文档

元数据

  • 需求编号：013-1
  • 创建时间：2026-01-28
  • 创建人：AI Assistant
  • 状态：已完成

复盘概述

本次复盘对 Apex 编译器接口与错误处理功能的开发过程进行了全面回顾，从需求定义到变更记录的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。

目标与实际产出对比

目标

  1. 实现统一错误模型，创建 ApexCompileIssue 类映射 Salesforce SOAP API 的 CompileIssue
  2. 实现编译器结果封装，创建 CompileResult 类封装编译结果
  3. 实现 WSDL 转 Apex 结果封装，创建 WsdlToApexResult 类封装 WSDL 转换结果
  4. 实现异常体系，创建 ApexException 及其子类
  5. 实现服务接口，创建 ApexCompilerService 和 WsdlConverterService 接口
  6. 遵循 SSOT 流程，确保所有开发活动都有文档依据
  7. 生成符合项目规范的代码，包含单元测试

实际产出

  1. 成功实现了统一错误模型，创建了 ApexCompileIssue 类
  2. 成功实现了编译器结果封装，创建了 CompileResult 类
  3. 成功实现了 WSDL 转 Apex 结果封装，创建了 WsdlToApexResult 类
  4. 成功实现了异常体系，创建了 ApexException 及其子类（ApexCompilationException、ApexRuntimeException、ApexConnectionException）
  5. 成功实现了服务接口，创建了 ApexCompilerService 和 WsdlConverterService 接口
  6. 成功实现了服务实现，创建了 ApexCompilerServiceImpl 和 WsdlConverterServiceImpl
  7. 成功实现了单元测试，创建了 ApexCompilerServiceTest 和 WsdlConverterServiceTest
  8. 严格按照 SSOT 流程执行，每个阶段都有相应的文档
  9. 生成的代码符合项目规范，包含单元测试
  10. 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等

成功经验

1. SSOT 流程的严格执行

从需求定义到变更记录的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。每个阶段完成后都会向用户确认，确保用户对进度和方向的理解一致。

2. 详细的提示词设计

阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。提示词引用了真源（需求文档、设计文档、决策记录），确保了代码生成的准确性。

3. 完整的会话记录

阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。会话记录包含了每个阶段的执行状态、关键决策和生成的文档链接，便于后续查阅。

4. 基于真实源代码的需求优化

在阶段 1，通过读取 Salesforce SOAP API 的真实源代码（CompileClassResult.java、CompileTriggerResult.java 等），优化了需求文档，确保了需求的准确性和可行性。这种基于真实源代码的需求优化方法，避免了需求与实际 API 不匹配的问题。

5. 灵活的阶段跳过机制

在阶段 4，通过分析需求确认不涉及数据库变更，灵活地跳过了数据库结构生成阶段，直接进入提示词生成阶段。这种灵活的阶段跳过机制，提高了开发效率，避免了不必要的文档创建。

改进点

1. 阶段间的过渡可以更流畅

在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。例如，在进入阶段 6（代码生成）前，可以更详细地说明将要生成的代码文件、代码结构、测试策略等。

2. 代码生成前的验证可以更严格

在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。例如，可以检查设计文档中的接口定义是否与需求文档中的功能需求一致，决策记录中的技术选型是否与实际代码实现一致。

3. API 文档的自动生成可以考虑

可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。目前 API 文档是手动编写的，容易出现遗漏或不准确的情况。

4. 单元测试的覆盖率验证

在代码生成完成后，可以增加单元测试覆盖率的验证步骤，确保测试用例的完整性。目前虽然生成了单元测试，但没有验证测试覆盖率是否达到要求。

5. 代码生成的批量验证

在代码生成完成后，可以增加批量验证步骤，检查所有生成的代码文件是否符合项目规范，包括命名规范、注释规范、导入规范等。目前虽然提示词中包含了代码规范要求，但没有批量验证步骤。

问题分析

本次需求执行过程中未发现重大问题，整体执行顺利。所有阶段都按时完成，生成的代码符合项目规范和需求，文档完整准确。

无重大问题

  • 需求定义清晰准确，基于真实源代码优化
  • 设计方案合理，技术选型正确
  • 代码生成符合规范，包含单元测试
  • 文档完整准确，索引更新及时
  • 会话记录完整，可追溯性强

行动计划

针对改进点 1：阶段间的过渡可以更流畅

  • 行动：在阶段转换时，增加对下一阶段的目的和流程的详细解释
  • 责任人：AI Assistant
  • 时间：立即执行
  • 具体措施：
    • 在进入阶段 6（代码生成）前，详细说明将要生成的代码文件、代码结构、测试策略等
    • 在进入阶段 7（会话记录）前，详细说明会话记录的内容和作用
    • 在进入阶段 8（变更记录与归档）前，详细说明变更记录的内容和作用
    • 在进入阶段 9（闭环复盘和接口文档）前，详细说明复盘文档和 API 文档的内容和作用

针对改进点 2：代码生成前的验证可以更严格

  • 行动：在生成代码前，增加对设计文档和决策记录的再次验证
  • 责任人：AI Assistant
  • 时间：立即执行
  • 具体措施：
    • 检查设计文档中的接口定义是否与需求文档中的功能需求一致
    • 检查决策记录中的技术选型是否与实际代码实现一致
    • 检查设计文档中的数据模型是否与需求文档中的数据模型一致
    • 检查设计文档中的异常处理是否与需求文档中的异常处理一致

针对改进点 3：API 文档的自动生成可以考虑

  • 行动：探索使用 Swagger 等工具自动生成 API 文档
  • 责任人：项目团队
  • 时间：下一个迭代
  • 具体措施：
    • 调研 Swagger 等工具的集成方案
    • 评估自动生成 API 文档的可行性和成本
    • 制定 API 文档自动生成的实施方案
    • 在下一个需求中试点 API 文档自动生成

针对改进点 4：单元测试的覆盖率验证

  • 行动：在代码生成完成后，增加单元测试覆盖率的验证步骤
  • 责任人：AI Assistant
  • 时间：立即执行
  • 具体措施：
    • 在代码生成完成后，运行单元测试
    • 使用 JaCoCo 等工具生成测试覆盖率报告
    • 验证测试覆盖率是否达到 80% 的要求
    • 如果测试覆盖率不达标，补充测试用例

针对改进点 5：代码生成的批量验证

  • 行动：在代码生成完成后，增加批量验证步骤
  • 责任人：AI Assistant
  • 时间：立即执行
  • 具体措施：
    • 检查所有生成的代码文件是否符合命名规范
    • 检查所有生成的代码文件是否包含必要的注释
    • 检查所有生成的代码文件的导入语句是否规范
    • 检查所有生成的代码文件的异常处理是否符合规范

提取模式

有效的 Prompt 技巧

1. 具体的输出格式要求

在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。例如：

## 输出格式要求
### 模型层
- 文件路径：`datai-salesforce-apex/src/main/java/com/datai/apex/model/`
- 文件格式：Java 类文件
- 必须使用 Lombok 注解（@Data、@NoArgsConstructor、@AllArgsConstructor）
- 必须实现 Serializable 接口

2. 引用真源

在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。例如：

## 引用真源
- 需求文档：[REQ-013-1.md](../requirements/REQ-013-1.md)
- 设计文档：[2026-01-28-013-1-Apex编译器接口设计.md](../design/2026-01-28-013-1-Apex编译器接口设计.md)
- 决策记录：[2026-01-28-013-1-ADR-Apex编译器接口技术选型.md](../decisions/2026-01-28-013-1-ADR-Apex编译器接口技术选型.md)

3. 详细的代码规范要求

在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。例如：

## 代码规范要求
### 命名规范
- 类名：使用大驼峰命名法（PascalCase）
- 方法名：使用小驼峰命名法（camelCase）
- 变量名：使用小驼峰命名法（camelCase）
- 常量名：使用全大写字母和下划线（UPPER_SNAKE_CASE）

### 注释规范
- 类注释：使用 Javadoc 格式，包含类的功能描述、作者、版本等信息
- 方法注释：使用 Javadoc 格式，包含方法的功能描述、参数说明、返回值说明、异常说明等
- 字段注释：使用 Javadoc 格式，包含字段的说明

避免的坑

1. 不要使用模糊的描述

在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。应该使用具体的描述，如"请生成符合 Spring Boot 规范的代码，使用 @Service 注解，包含单元测试"。

2. 不要忽略测试要求

在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。应该在提示词中明确指定测试要求，如"每个服务实现类都需要包含单元测试，测试覆盖率不低于 80%"。

3. 不要违反项目规则

在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。应该在提示词中明确指定项目规则，如"遵循若依框架规范，使用 @RestController、@RequestMapping、@GetMapping 等注解"。

模板迭代

经过本次复盘，发现当前的提示词模板（docs/Prompt/0000-template.md）在以下方面可以改进：

需要改进的方面

  1. 代码规范要求可以更具体：特别是针对 Spring Boot 框架和 Lombok 框架的规范要求
  2. 测试要求可以更详细：特别是测试覆盖率、测试场景、测试框架等方面的要求
  3. 验证步骤可以更明确：特别是代码生成后的验证步骤，如批量验证、覆盖率验证等

模板更新计划

在下一个迭代中更新提示词模板，增加以下内容：

  1. Spring Boot 框架规范要求：

    • 包结构规范
    • 注解使用规范
    • 配置文件规范
    • 依赖注入规范

  2. Lombok 框架规范要求：

    • 注解使用规范（@Data、@Getter、@Setter、@NoArgsConstructor、@AllArgsConstructor 等）
    • 序列化规范（@Builder、@ToString、@EqualsAndHashCode 等）

  3. 测试要求详细化：

    • 测试覆盖率要求（不低于 80%）
    • 测试场景要求（正常场景、异常场景、边界场景）
    • 测试框架要求（JUnit 5、Mockito、AssertJ）
    • 测试用例命名规范（should_ExpectedBehavior_When_StateUnderTest）

  4. 验证步骤明确化：

    • 批量验证步骤（命名规范、注释规范、导入规范、异常处理规范）
    • 覆盖率验证步骤（使用 JaCoCo 生成测试覆盖率报告）
    • 集成测试步骤（验证服务间的协作）

相关文档