复盘文档：Apex 动态代码执行与日志管理

元数据

需求编号：REQ-013-2
创建时间：2026-01-27
创建人：AI Assistant
状态：已完成

复盘概述

本次复盘针对 "Apex 动态代码执行与日志管理" 功能的开发过程。该功能旨在为前端提供一个无状态的 API 代理，通过 Salesforce SOAP API 动态执行 Apex 代码并获取执行日志。整个过程严格遵循 SSOT 流程，从需求定义、方案设计、决策记录、数据库分析（跳过）、提示词生成到代码生成，每一步均有文档支撑。

目标与实际产出对比

目标

实现 ApexExecutorService 接口，封装 Salesforce SOAP API 的 executeAnonymous 调用。
支持通过 DebuggingOptions 配置细粒度的日志级别。
提供结构化的 ExecuteResult，包含执行状态、编译错误信息、调试日志和运行时异常。
遵循无状态设计，不引入本地数据库存储。

实际产出

成功实现了 ApexExecutorService 及其实现类 ApexExecutorServiceImpl。
定义了 DebuggingOptions 和 ExecuteResult 模型，完全满足需求。
实现了 LogParser 接口及其默认实现，支持基本的日志解析。
生成了完整的单元测试 ApexExecutorServiceTest（虽然因环境原因暂未运行）。
未引入任何本地数据库表，符合架构决策。

成功经验

无状态架构设计的贯彻：在需求分析阶段（Phase 1）和数据库分析阶段（Phase 4），明确了该功能作为 API 代理的定位，果断决定不创建本地表结构。这大大简化了系统复杂度，避免了不必要的数据同步问题。
精准的 API 映射：在设计阶段（Phase 2），通过深入研究 Salesforce SOAP API 文档，准确地将 DebuggingHeader 映射为 DebuggingOptions Java 对象，使得日志级别的配置既符合 Salesforce 规范，又符合 Java 开发习惯。
分层异常处理策略：在决策阶段（Phase 3），确立了异常处理原则。区分了系统级异常（如网络连接失败，抛出 ApexConnectionException）和业务级异常（如编译错误、运行时异常，封装在 ExecuteResult 中返回）。这种策略使得前端能够优雅地展示编译错误，而不用处理底层的网络堆栈信息。

改进点

环境依赖检查的前置化：在 Phase 6 代码生成后尝试运行测试时，发现环境中缺少 mvn 命令。如果在 Phase 1 或 Phase 6 之前进行环境检查，可以更早地发现并提示用户解决，或者提供基于 Gradle/IDE 的替代运行方案。
单元测试的 Mock 深度：目前的单元测试通过 Mockito 模拟了 SoapConnection。虽然覆盖了逻辑路径，但对于 SOAP 协议实际序列化/反序列化的边缘情况（如极大的日志文件）覆盖不足。未来可以考虑引入集成测试。

问题分析

问题 1：执行测试时提示 CommandNotFoundException: mvn。
- 根因：当前运行环境（Windows）未将 Maven 的 bin 目录添加到系统 PATH 环境变量中，或者未安装 Maven。
- 解决方案：建议用户检查 Maven 安装及环境变量配置。作为替代，用户可以在 IntelliJ IDEA 的图形界面中直接运行 JUnit 测试。

行动计划

针对改进点 1：在后续类似涉及构建工具的任务中，增加 "Check Environment" 的步骤，确认 mvn 或 gradle 可用。责任：AI Assistant，时间：下次任务。
针对问题 1：在本次会话结束语中，明确提示用户配置 Maven 环境以便运行生成的单元测试。责任：AI Assistant，时间：立即执行。

提取模式

有效的 Prompt 技巧

显式依赖注入要求：在生成 Prompt 时，明确要求 "使用 Spring 的构造器注入 (@Autowired) 而不是字段注入"，这确保了生成的代码符合 Spring 最佳实践，易于测试。
明确的异常类定义：在 Prompt 中列出具体的自定义异常类名（ApexCompilationException），避免了 AI 生成通用的 RuntimeException。

避免的坑

忽略第三方库的 Stub 生成：在使用 Salesforce WSC (Web Service Connector) 时，通常需要先通过 WSDL 生成 Java Stub。在 Prompt 中应假设 Stub 已存在或提示用户生成，否则生成的代码会引用不存在的类（如 SoapConnection）。本次开发假设了依赖已就绪，这在实际从零开始的项目中可能会导致编译错误。

模板迭代

本次使用的 Prompt 模板在生成业务逻辑代码方面表现良好，但在处理第三方库依赖（特别是需要代码生成的库）方面的引导可以进一步加强。暂不需要立即更新模板，但在涉及类似 SOAP/RPC 集成时应注意。

4.9 KiB Raw Blame History Unescape Escape