# API 文档 - Tooling 连接管理

## 元数据
- **需求编号**: 004-01
- **子需求名称**: 连接管理
- **版本号**: v1.0.0
- **创建时间**: 2026-02-05
- **创建人**: AI Assistant
- **状态**: 已完成

## API 概述
Tooling 连接管理 API 提供对 Salesforce Tooling API 连接的管理功能，包括获取连接、清除缓存、测试连接、设置调用选项、设置调试头部等。这些 API 是 Tooling API 模块的基础组件，为后续元数据操作、开发工具功能等提供连接管理能力。

### 基础信息
- **基础路径**: `/salesforce/tooling/connection`
- **认证方式**: JWT Token + 权限校验
- **Content-Type**: `application/json`
- **API 版本**: v1.0.0

### 权限要求
所有接口都需要以下权限：
- `tooling:connection:get` - 获取连接
- `tooling:connection:clear` - 清除缓存
- `tooling:connection:test` - 测试连接
- `tooling:connection:callOptions` - 设置调用选项
- `tooling:connection:debuggingHeader` - 设置调试头部

## 接口列表

### 1. 获取连接

#### 接口说明
获取 Tooling API 连接。如果缓存中没有有效连接，则创建新连接并缓存。连接创建时会验证 Session 有效性。

#### 请求信息
- **请求方式**: GET
- **请求路径**: `/salesforce/tooling/connection/get`
- **权限要求**: `tooling:connection:get`

#### 请求参数
无

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 连接结果对象 |
| data.success | Boolean | 是否成功 |
| data.valid | Boolean | 连接是否有效 |
| data.testTime | String | 测试时间（格式：yyyy-MM-dd HH:mm:ss） |
| data.responseTime | Long | 响应时间（毫秒） |
| data.errorCode | String | 错误码（失败时返回） |
| data.errorMessage | String | 错误消息（失败时返回） |

#### 成功示例
```json
{
  "code": 200,
  "msg": "获取连接成功",
  "data": {
    "success": true,
    "valid": true,
    "testTime": "2026-02-05 14:30:25",
    "responseTime": 156
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "操作失败",
  "data": {
    "success": false,
    "valid": false,
    "errorCode": "TOOLING_CONN_006",
    "errorMessage": "用户未登录或会话已过期"
  }
}
```

#### 错误码
- `TOOLING_CONN_001`: Session 无效或已过期
- `TOOLING_CONN_002`: 连接创建失败
- `TOOLING_CONN_006`: 用户未登录或会话已过期

---

### 2. 清除连接缓存

#### 接口说明
清除缓存的 Tooling API 连接。下次获取连接时将创建新连接。

#### 请求信息
- **请求方式**: DELETE
- **请求路径**: `/salesforce/tooling/connection/clear`
- **权限要求**: `tooling:connection:clear`

#### 请求参数
无

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 无数据返回 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "清除连接缓存成功",
  "data": null
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "清除连接缓存失败: 清除缓存时发生错误",
  "data": null
}
```

#### 错误码
- `TOOLING_CONN_003`: 网络超时
- `TOOLING_CONN_008`: 未知错误

---

### 3. 测试连接

#### 接口说明
测试 Tooling API 连接是否有效。通过执行简单的 SOQL 查询来验证连接。

#### 请求信息
- **请求方式**: GET
- **请求路径**: `/salesforce/tooling/connection/test`
- **权限要求**: `tooling:connection:test`

#### 请求参数
无

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 测试结果对象 |
| data.success | Boolean | 是否成功 |
| data.valid | Boolean | 连接是否有效 |
| data.testTime | String | 测试时间（格式：yyyy-MM-dd HH:mm:ss） |
| data.responseTime | Long | 响应时间（毫秒） |
| data.errorCode | String | 错误码（失败时返回） |
| data.errorMessage | String | 错误消息（失败时返回） |

#### 成功示例
```json
{
  "code": 200,
  "msg": "测试连接成功",
  "data": {
    "success": true,
    "valid": true,
    "testTime": "2026-02-05 14:30:25",
    "responseTime": 234
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "操作失败",
  "data": {
    "success": false,
    "valid": false,
    "errorCode": "TOOLING_CONN_001",
    "errorMessage": "Session 无效或已过期"
  }
}
```

#### 错误码
- `TOOLING_CONN_001`: Session 无效或已过期
- `TOOLING_CONN_002`: 连接创建失败
- `TOOLING_CONN_003`: 网络超时

---

### 4. 设置调用选项

#### 接口说明
设置 Tooling API 连接的调用选项，如客户端名称等。

#### 请求信息
- **请求方式**: POST
- **请求路径**: `/salesforce/tooling/connection/call-options`
- **权限要求**: `tooling:connection:callOptions`
- **Content-Type**: `application/json`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| client | String | 否 | 客户端名称，用于标识调用来源 |
| defaultNamespace | String | 否 | 默认命名空间 |
| clientId | String | 否 | 客户端 ID |

#### 请求示例
```json
{
  "client": "DataI-Tooling-Client",
  "defaultNamespace": "",
  "clientId": "datai-tooling-001"
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 设置结果对象 |
| data.success | Boolean | 是否成功 |
| data.errorCode | String | 错误码（失败时返回） |
| data.errorMessage | String | 错误消息（失败时返回） |

#### 成功示例
```json
{
  "code": 200,
  "msg": "设置调用选项成功",
  "data": {
    "success": true
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "操作失败",
  "data": {
    "success": false,
    "errorCode": "TOOLING_CONN_007",
    "errorMessage": "设置调用选项失败"
  }
}
```

#### 错误码
- `TOOLING_CONN_007`: 设置调用选项失败

---

### 5. 设置调试头部

#### 接口说明
设置 Tooling API 连接的调试头部，用于控制调试信息的输出级别。

#### 请求信息
- **请求方式**: POST
- **请求路径**: `/salesforce/tooling/connection/debugging-header`
- **权限要求**: `tooling:connection:debuggingHeader`
- **Content-Type**: `application/json`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| debugLevel | String | 是 | 调试级别，可选值：NONE、DEBUG_ONLY、DB、PROFILING、CALLOUT、DETAIL |
| categories | Array | 否 | 调试类别列表 |

#### 调试级别说明
| 级别 | 说明 |
|------|------|
| NONE | 不输出调试信息 |
| DEBUG_ONLY | 仅输出调试日志 |
| DB | 输出数据库操作信息 |
| PROFILING | 输出性能分析信息 |
| CALLOUT | 输出外部调用信息 |
| DETAIL | 输出详细信息 |

#### 请求示例
```json
{
  "debugLevel": "DEBUG_ONLY",
  "categories": ["Apex", "Visualforce"]
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 设置结果对象 |
| data.success | Boolean | 是否成功 |
| data.errorCode | String | 错误码（失败时返回） |
| data.errorMessage | String | 错误消息（失败时返回） |

#### 成功示例
```json
{
  "code": 200,
  "msg": "设置调试头部成功",
  "data": {
    "success": true
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "操作失败",
  "data": {
    "success": false,
    "errorCode": "TOOLING_CONN_008",
    "errorMessage": "设置调试头部失败"
  }
}
```

#### 错误码
- `TOOLING_CONN_008`: 设置调试头部失败

---

## 错误码汇总

| 错误码 | 错误消息 | 说明 |
|--------|----------|------|
| TOOLING_CONN_001 | Session 无效或已过期 | Session 已过期或无效，需要重新登录 |
| TOOLING_CONN_002 | 连接创建失败 | 创建 ToolingConnection 时发生错误 |
| TOOLING_CONN_003 | 网络超时 | 连接 Salesforce API 超时 |
| TOOLING_CONN_004 | 权限不足 | 当前用户没有执行该操作的权限 |
| TOOLING_CONN_005 | API 版本不支持 | 当前 API 版本不支持该操作 |
| TOOLING_CONN_006 | 用户未登录 | 用户未登录或会话已过期 |
| TOOLING_CONN_007 | 设置调用选项失败 | 设置调用选项时发生错误 |
| TOOLING_CONN_008 | 设置调试头部失败 | 设置调试头部时发生错误 |

## 接口调用场景

### 场景 1: 初始化连接
在需要使用 Tooling API 之前，先调用"获取连接"接口确保连接可用。

```
1. 调用 GET /salesforce/tooling/connection/get
2. 如果返回成功，连接已准备好
3. 如果返回失败（如 Session 过期），需要先登录
```

### 场景 2: 定期测试连接
可以定期调用"测试连接"接口检查连接状态，及时发现连接问题。

```
1. 定时调用 GET /salesforce/tooling/connection/test
2. 如果返回失败，调用 GET /salesforce/tooling/connection/get 重新获取连接
```

### 场景 3: 切换环境
在需要切换到不同的 Salesforce 环境时，先清除缓存再获取新连接。

```
1. 调用 DELETE /salesforce/tooling/connection/clear 清除缓存
2. 调用 GET /salesforce/tooling/connection/get 获取新连接
```

### 场景 4: 调试问题
在排查问题时，可以设置调试头部获取更多调试信息。

```
1. 调用 POST /salesforce/tooling/connection/debugging-header 设置调试级别为 DETAIL
2. 执行需要调试的操作
3. 查看调试日志
4. 调用 POST /salesforce/tooling/connection/debugging-header 恢复调试级别为 NONE
```

## 注意事项

1. **连接缓存**: 连接会被缓存以提高性能，但在 Session 过期或需要切换环境时需要清除缓存。

2. **Session 有效性**: 获取连接时会自动验证 Session 有效性，如果 Session 过期会返回错误。

3. **线程安全**: 连接缓存使用 ConcurrentHashMap 实现，线程安全。

4. **异常处理**: 所有接口都遵循统一的异常处理规范，返回标准的 AjaxResult 格式。

5. **权限控制**: 所有接口都需要相应的权限，确保安全性。

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-004-01-连接管理.md)
- [设计文档](../design/2026-02-03-004-01-连接管理-设计.md)
- [决策记录](../decisions/2026-02-03-004-01-ADR-连接管理技术选型.md)
- [提示词](../prompts/2026-02-03-004-01-prompt-Tooling连接管理.md)
- [变更日志](../changelog/2026-02-05-004-01-changelog.md)
- [复盘文档](../retros/2026-02-05-004-01-retro.md)