# 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 编译器接口与错误处理会话记录