122 lines
7.1 KiB
Markdown
122 lines
7.1 KiB
Markdown
# Apex 动态代码执行与日志管理需求
|
||
|
||
## 元数据
|
||
- 需求编号：013-2
|
||
- 父需求：013
|
||
- 创建时间：2026-01-26
|
||
- 创建人：SSOT 架构师
|
||
- 状态：进行中
|
||
- 优先级：高
|
||
- 关联代码：
|
||
- `com.sforce.soap.apex.ExecuteAnonymousResult`
|
||
- `com.sforce.soap.apex.DebuggingHeader_element`
|
||
- `com.sforce.soap.apex.LogCategory`
|
||
- `com.sforce.soap.apex.LogCategoryLevel`
|
||
- `com.sforce.soap.apex.DebuggingInfo_element`
|
||
|
||
## 需求概述
|
||
实现 `executeAnonymous` 的封装，允许用户执行任意 Apex 代码片段，并能够灵活控制和获取执行过程中的调试日志。通过封装 `DebuggingHeader` 实现细粒度的日志级别控制，并解析 `DebuggingInfo` 获取执行结果。
|
||
|
||
## 目标
|
||
1. **统一执行接口**：封装底层的 SOAP 调用，提供友好的 Java 接口。
|
||
2. **精确日志控制**：支持基于 `LogCategory` 和 `LogCategoryLevel` 的细粒度日志配置。
|
||
3. **结果结构化**：将 SOAP 的 `ExecuteAnonymousResult` 转换为结构化的 Java 对象，区分编译错误和运行时异常。
|
||
4. **日志内容提取**：自动从 SOAP Header 中提取并（可选）解析日志内容。
|
||
|
||
## 功能需求
|
||
|
||
### 1. 动态代码执行 (Anonymous Execution)
|
||
- **功能描述**：封装 `SoapConnection.executeAnonymous` 方法。
|
||
- **接口定义**：
|
||
```java
|
||
ExecuteResult execute(String apexCode, DebuggingOptions options);
|
||
```
|
||
- **输入参数**：
|
||
- `apexCode`: 待执行的 Apex 代码字符串。
|
||
- `options`: 包含日志级别配置、模拟模式等选项。
|
||
- **处理逻辑**：
|
||
1. 构建 `DebuggingHeader_element`，根据 `options` 设置日志级别。
|
||
2. 调用 `connection.executeAnonymous(apexCode)`。
|
||
3. 获取响应头中的 `DebuggingInfo_element`，提取 `debugLog`。
|
||
4. 处理 `ExecuteAnonymousResult` 返回值：
|
||
- **编译检查**：检查 `isCompiled()`。
|
||
- 若为 `false`，读取 `compileProblem`, `line`, `column`。
|
||
- 抛出 `ApexCompilationException` (引用 REQ-013-1 定义)。
|
||
- **执行检查**：检查 `isSuccess()`。
|
||
- 若为 `false`，读取 `exceptionMessage`, `exceptionStackTrace`。
|
||
- 封装到 `ExecuteResult` 中作为运行时错误返回。
|
||
- **成功**：封装执行结果。
|
||
- **输出对象 (`ExecuteResult`)**：
|
||
- `boolean success`: 执行是否成功。
|
||
- `boolean compiled`: 代码是否编译成功。
|
||
- `String debugLog`: 完整的调试日志内容。
|
||
- `String exceptionMessage`: 运行时异常信息（如有）。
|
||
- `String exceptionStackTrace`: 运行时堆栈跟踪（如有）。
|
||
- `String compileProblem`: 编译错误描述（如有）。
|
||
- `int compileLine`: 编译错误行号（如有）。
|
||
- `int compileColumn`: 编译错误列号（如有）。
|
||
- `long executionTime`: (可选) 从日志或响应时间估算的执行耗时。
|
||
|
||
### 2. 日志级别配置 (Logging Configuration)
|
||
- **功能描述**：构建 `DebuggingHeader`，支持两种日志配置模式。
|
||
- **配置模式**：
|
||
- **细粒度模式**：使用 `categories` 字段，基于 `LogCategory` 和 `LogCategoryLevel` 的精确配置。
|
||
- **预设模式**：使用 `debugLevel` 字段，基于 `LogType` 的快速配置。
|
||
- **枚举定义**：
|
||
- **`LogCategory`** (对应 `com.sforce.soap.apex.LogCategory`):
|
||
- `Db`, `Workflow`, `Validation`, `Callout`, `Apex_code`, `Apex_profiling`, `Visualforce`, `System`
|
||
- `Wave`, `Nba`, `Data_access`, `All`
|
||
- **`LogCategoryLevel`** (对应 `com.sforce.soap.apex.LogCategoryLevel`):
|
||
- `None`, `Finest`, `Finer`, `Fine`, `Debug`, `Info`, `Warn`, `Error`
|
||
- **`LogType`** (对应 `com.sforce.soap.apex.LogType`):
|
||
- `None`, `Debugonly`, `Db`, `Profiling`, `Callout`, `Detail`
|
||
- **配置模板**：
|
||
- **细粒度模板**：
|
||
- `DEBUG_ONLY`: `Apex_code`=DEBUG, `System`=DEBUG, 其他=INFO
|
||
- `DB_ANALYSIS`: `Db`=FINEST, `Apex_profiling`=FINEST, 其他=INFO
|
||
- **预设模板**：
|
||
- `DEBUGONLY`: 使用 `LogType.Debugonly`
|
||
- `DB`: 使用 `LogType.Db`
|
||
- `PROFILING`: 使用 `LogType.Profiling`
|
||
|
||
### 3. 日志获取与解析 (Log Retrieval & Parsing)
|
||
- **功能描述**：处理 `DebuggingInfo_element`。
|
||
- **详细要求**：
|
||
- **自动提取**：每次执行后，自动检查 SOAP 响应头，提取 `debugLog` 字符串。
|
||
- **日志解析器 (LogParser)** (可选组件):
|
||
- `List<String> getUserDebugs(String log)`: 提取所有 `USER_DEBUG` 行。
|
||
- `Map<String, String> getLimits(String log)`: 提取 `LIMIT_USAGE` 部分（如 "Number of SOQL queries: 2 out of 100"）。
|
||
|
||
## 关键代码映射 (Source Code Mapping)
|
||
|
||
### SOAP 对象映射
|
||
| 逻辑概念 | SOAP 类名 | 关键字段 |
|
||
| :--- | :--- | :--- |
|
||
| 执行结果 | `ExecuteAnonymousResult` | `compiled`, `compileProblem`, `line`, `column`, `success`, `exceptionMessage`, `exceptionStackTrace` |
|
||
| 调试头 | `DebuggingHeader_element` | `categories` (`LogInfo[]`), `debugLevel` (`LogType`) |
|
||
| 日志信息配置 | `LogInfo` | `category` (`LogCategory`), `level` (`LogCategoryLevel`) |
|
||
| 调试信息返回 | `DebuggingInfo_element` | `debugLog` |
|
||
|
||
### 枚举值对应
|
||
- **LogCategory**: 严格匹配 `com.sforce.soap.apex.LogCategory` 的枚举值（12个值：Db, Workflow, Validation, Callout, Apex_code, Apex_profiling, Visualforce, System, Wave, Nba, Data_access, All）。
|
||
- **LogCategoryLevel**: 严格匹配 `com.sforce.soap.apex.LogCategoryLevel` 的枚举值（8个值：None, Finest, Finer, Fine, Debug, Info, Warn, Error）。
|
||
- **LogType**: 严格匹配 `com.sforce.soap.apex.LogType` 的枚举值（6个值：None, Debugonly, Db, Profiling, Callout, Detail）。
|
||
|
||
## 异常处理规范
|
||
1. **编译异常**：当 `ExecuteAnonymousResult.compiled == false` 时，必须阻断流程，抛出受检异常 `ApexCompilationException`，包含具体的行列号和错误信息。
|
||
2. **运行时异常**：当 `ExecuteAnonymousResult.success == false` 时，不抛出异常，而是将错误信息封装在 `ExecuteResult` 中返回，因为这属于代码执行的预期结果之一（例如代码逻辑抛出异常）。
|
||
3. **SOAP 故障**：网络或认证错误抛出 `ConnectionException` 或运行时异常。
|
||
|
||
## 验证与测试
|
||
1. **基础执行**：执行 `System.debug('Hello');`，断言 `success=true` 且 `debugLog` 包含 'Hello'。
|
||
2. **编译错误**：执行 `In valid Code;`，断言抛出 `ApexCompilationException` 且包含行号。
|
||
3. **运行时错误**：执行 `throw new MyException('Test');`，断言 `success=false` 且 `exceptionMessage` 包含 'Test'。
|
||
4. **日志级别**：设置 `Apex_code=FINEST`，执行代码，断言日志长度或内容详细程度增加。
|
||
|
||
## 相关文档
|
||
- [设计文档](../design/2026-01-28-013-2-Apex动态代码执行与日志管理设计.md)
|
||
- [提示词文档](../prompts/2026-01-27-013-2-prompt-Apex动态代码执行与日志管理.md)
|
||
- [变更日志](../changelog/2026-01-27-013-2-changelog.md)
|
||
- [复盘文档](../retros/2026-01-27-013-2-retro.md)
|
||
- [API 文档](../api-docs/apex/2026-01-27-013-2-api.md)
|