326 lines
9.8 KiB
Markdown
326 lines
9.8 KiB
Markdown
# Apex 编译器接口与错误处理 - API 文档
|
||
|
||
## 元数据
|
||
- 需求编号：013-1
|
||
- 创建时间：2026-01-28
|
||
- 创建人：AI Assistant
|
||
- 状态：已完成
|
||
|
||
## API 概述
|
||
|
||
本文档描述 Apex 编译器接口与错误处理功能的服务接口定义和使用方法。该功能提供了 Apex 代码编译和 WSDL 转 Apex 的核心服务接口，支持 Apex 类、触发器的编译以及 WSDL 文件到 Apex 代码的转换。
|
||
|
||
### 核心功能
|
||
1. **Apex 类编译**：支持批量编译 Apex 类代码
|
||
2. **Apex 触发器编译**：支持批量编译 Apex 触发器代码
|
||
3. **WSDL 转 Apex**：支持将 WSDL 文件转换为 Apex 代码
|
||
|
||
### 技术栈
|
||
- **框架**：Spring Boot
|
||
- **SOAP 客户端**：force-wsc
|
||
- **简化工具**：Lombok
|
||
- **测试框架**：JUnit 5、Mockito
|
||
|
||
## 接口列表
|
||
|
||
### 1. ApexCompilerService 接口
|
||
|
||
#### 1.1 编译 Apex 类
|
||
|
||
**接口名称**：`compileClasses`
|
||
|
||
**功能描述**：批量编译 Apex 类代码，返回编译结果列表
|
||
|
||
**方法签名**：
|
||
```java
|
||
List<CompileResult> compileClasses(List<String> classSources)
|
||
```
|
||
|
||
**参数说明**：
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| classSources | List<String> | 是 | Apex 类源代码列表，每个元素是一个完整的 Apex 类源代码字符串 |
|
||
|
||
**返回值**：
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| List<CompileResult> | 编译结果列表，每个 CompileResult 对应一个 Apex 类的编译结果 |
|
||
|
||
**CompileResult 对象说明**：
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| success | Boolean | 编译是否成功 |
|
||
| id | String | 元数据 ID（成功时） |
|
||
| name | String | 类名（成功时） |
|
||
| bodyCrc | Integer | 内容校验码（成功时） |
|
||
| line | Integer | 错误行号（失败时） |
|
||
| column | Integer | 错误列号（失败时） |
|
||
| problem | String | 错误描述（失败时） |
|
||
| problems | List<ApexCompileIssue> | 错误列表 |
|
||
| warnings | List<ApexCompileIssue> | 警告列表 |
|
||
|
||
**ApexCompileIssue 对象说明**：
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| line | Integer | 行号 |
|
||
| column | Integer | 列号 |
|
||
| problem | String | 问题描述 |
|
||
| className | String | 类名/文件名 |
|
||
|
||
**使用示例**：
|
||
```java
|
||
@Autowired
|
||
private ApexCompilerService apexCompilerService;
|
||
|
||
public void compileApexClasses() {
|
||
List<String> classSources = new ArrayList<>();
|
||
classSources.add("public class MyClass {\n public void myMethod() {\n System.debug('Hello World');\n }\n}");
|
||
|
||
List<CompileResult> results = apexCompilerService.compileClasses(classSources);
|
||
|
||
for (CompileResult result : results) {
|
||
if (result.getSuccess()) {
|
||
System.out.println("编译成功：" + result.getName());
|
||
} else {
|
||
System.out.println("编译失败：" + result.getProblem());
|
||
for (ApexCompileIssue issue : result.getProblems()) {
|
||
System.out.println(" 错误：" + issue.getProblem() + " (行：" + issue.getLine() + ")");
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**异常说明**：
|
||
- **ApexConnectionException**：连接 Salesforce API 失败时抛出
|
||
- **ApexCompilationException**：编译过程中发生严重错误时抛出
|
||
|
||
---
|
||
|
||
#### 1.2 编译 Apex 触发器
|
||
|
||
**接口名称**：`compileTriggers`
|
||
|
||
**功能描述**：批量编译 Apex 触发器代码，返回编译结果列表
|
||
|
||
**方法签名**：
|
||
```java
|
||
List<CompileResult> compileTriggers(List<String> triggerSources)
|
||
```
|
||
|
||
**参数说明**：
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| triggerSources | List<String> | 是 | Apex 触发器源代码列表，每个元素是一个完整的 Apex 触发器源代码字符串 |
|
||
|
||
**返回值**：
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| List<CompileResult> | 编译结果列表，每个 CompileResult 对应一个 Apex 触发器的编译结果 |
|
||
|
||
**CompileResult 对象说明**：
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| success | Boolean | 编译是否成功 |
|
||
| id | String | 元数据 ID（成功时） |
|
||
| name | String | 触发器名（成功时） |
|
||
| bodyCrc | Integer | 内容校验码（成功时） |
|
||
| line | Integer | 错误行号（失败时） |
|
||
| column | Integer | 错误列号（失败时） |
|
||
| problem | String | 错误描述（失败时） |
|
||
| problems | List<ApexCompileIssue> | 错误列表 |
|
||
| warnings | List<ApexCompileIssue> | 警告列表 |
|
||
|
||
**使用示例**：
|
||
```java
|
||
@Autowired
|
||
private ApexCompilerService apexCompilerService;
|
||
|
||
public void compileApexTriggers() {
|
||
List<String> triggerSources = new ArrayList<>();
|
||
triggerSources.add("trigger MyTrigger on Account (before insert) {\n System.debug('Account inserted');\n}");
|
||
|
||
List<CompileResult> results = apexCompilerService.compileTriggers(triggerSources);
|
||
|
||
for (CompileResult result : results) {
|
||
if (result.getSuccess()) {
|
||
System.out.println("编译成功：" + result.getName());
|
||
} else {
|
||
System.out.println("编译失败：" + result.getProblem());
|
||
for (ApexCompileIssue issue : result.getProblems()) {
|
||
System.out.println(" 错误：" + issue.getProblem() + " (行：" + issue.getLine() + ")");
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**异常说明**：
|
||
- **ApexConnectionException**：连接 Salesforce API 失败时抛出
|
||
- **ApexCompilationException**：编译过程中发生严重错误时抛出
|
||
|
||
---
|
||
|
||
### 2. WsdlConverterService 接口
|
||
|
||
#### 2.1 转换 WSDL 为 Apex 代码
|
||
|
||
**接口名称**：`convertWsdl`
|
||
|
||
**功能描述**：将 WSDL 文件内容转换为 Apex 代码，返回转换结果
|
||
|
||
**方法签名**：
|
||
```java
|
||
WsdlToApexResult convertWsdl(String wsdlContent)
|
||
```
|
||
|
||
**参数说明**：
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| wsdlContent | String | 是 | WSDL 文件内容字符串 |
|
||
|
||
**返回值**：
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| WsdlToApexResult | WSDL 转换结果 |
|
||
|
||
**WsdlToApexResult 对象说明**：
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| success | Boolean | 转换是否成功 |
|
||
| apexScripts | List<String> | 生成的 Apex 代码列表 |
|
||
| errors | List<String> | 错误信息列表 |
|
||
|
||
**使用示例**：
|
||
```java
|
||
@Autowired
|
||
private WsdlConverterService wsdlConverterService;
|
||
|
||
public void convertWsdlToApex() {
|
||
String wsdlContent = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" +
|
||
"<definitions xmlns=\"http://schemas.xmlsoap.org/wsdl/\" ...>\n" +
|
||
" ...\n" +
|
||
"</definitions>";
|
||
|
||
WsdlToApexResult result = wsdlConverterService.convertWsdl(wsdlContent);
|
||
|
||
if (result.getSuccess()) {
|
||
System.out.println("转换成功，生成了 " + result.getApexScripts().size() + " 个 Apex 文件");
|
||
for (String apexScript : result.getApexScripts()) {
|
||
System.out.println(apexScript);
|
||
}
|
||
} else {
|
||
System.out.println("转换失败：");
|
||
for (String error : result.getErrors()) {
|
||
System.out.println(" 错误：" + error);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**异常说明**：
|
||
- **ApexConnectionException**：连接 Salesforce API 失败时抛出
|
||
- **ApexCompilationException**：转换过程中发生严重错误时抛出
|
||
|
||
---
|
||
|
||
## 异常体系
|
||
|
||
### ApexException（基类异常）
|
||
|
||
**描述**：所有 Apex 相关异常的基类
|
||
|
||
**子类**：
|
||
- ApexCompilationException
|
||
- ApexRuntimeException
|
||
- ApexConnectionException
|
||
|
||
---
|
||
|
||
### ApexCompilationException（编译异常）
|
||
|
||
**描述**：Apex 代码编译过程中发生的异常
|
||
|
||
**字段**：
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| issues | List<ApexCompileIssue> | 编译问题列表 |
|
||
|
||
**使用场景**：
|
||
- Apex 类编译失败
|
||
- Apex 触发器编译失败
|
||
- WSDL 转 Apex 失败
|
||
|
||
---
|
||
|
||
### ApexRuntimeException（运行时异常）
|
||
|
||
**描述**：Apex 代码运行过程中发生的异常
|
||
|
||
**使用场景**：
|
||
- Apex 代码执行失败
|
||
- Apex 代码运行时错误
|
||
|
||
---
|
||
|
||
### ApexConnectionException（连接异常）
|
||
|
||
**描述**：连接 Salesforce API 时发生的异常
|
||
|
||
**使用场景**：
|
||
- 连接 Salesforce API 失败
|
||
- 网络错误
|
||
- 认证失败
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
### 编译错误码
|
||
|
||
| 错误码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| COMPILE_ERROR | 编译错误 | 检查代码语法，修正错误 |
|
||
| COMPILE_WARNING | 编译警告 | 检查代码规范，优化代码 |
|
||
| BODY_CRC_MISMATCH | 内容校验失败 | 检查代码内容是否被修改 |
|
||
|
||
### 连接错误码
|
||
|
||
| 错误码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| CONNECTION_FAILED | 连接失败 | 检查网络连接，重试 |
|
||
| AUTHENTICATION_FAILED | 认证失败 | 检查认证信息，重新认证 |
|
||
| TIMEOUT | 超时 | 检查网络状态，增加超时时间 |
|
||
|
||
### 转换错误码
|
||
|
||
| 错误码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| WSDL_PARSE_ERROR | WSDL 解析错误 | 检查 WSDL 文件格式 |
|
||
| WSDL_GENERATE_ERROR | Apex 代码生成错误 | 检查 WSDL 文件内容 |
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
### 需求文档
|
||
- [REQ-013-1.md](../requirements/REQ-013-1.md) - Apex 编译器接口与错误处理需求
|
||
|
||
### 设计文档
|
||
- [2026-01-28-013-1-Apex编译器接口设计.md](../design/2026-01-28-013-1-Apex编译器接口设计.md) - Apex 编译器接口设计
|
||
|
||
### 决策记录
|
||
- [2026-01-28-013-1-ADR-Apex编译器接口技术选型.md](../decisions/2026-01-28-013-1-ADR-Apex编译器接口技术选型.md) - Apex 编译器接口技术选型
|
||
|
||
### 提示词文档
|
||
- [2026-01-28-013-1-prompt-Apex编译器接口与错误处理.md](../prompts/2026-01-28-013-1-prompt-Apex编译器接口与错误处理.md) - Apex 编译器接口与错误处理提示词
|
||
|
||
### 变更日志
|
||
- [2026-01-28-013-1-changelog.md](../changelog/2026-01-28-013-1-changelog.md) - Apex 编译器接口与错误处理变更日志
|
||
|
||
### 复盘文档
|
||
- [2026-01-28-013-1-retro.md](../retros/2026-01-28-013-1-retro.md) - Apex 编译器接口与错误处理复盘文档
|
||
|
||
### 会话记录
|
||
- [2026-01-28-013-1-session.md](../sessions/2026-01-28-013-1-session.md) - Apex 编译器接口与错误处理会话记录
|