kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-02-002-01-api.md

544 lines
12 KiB
Markdown
Raw Permalink Normal View History

feat：Apex、Metadata、Partner初步
2026-02-03 16:51:09 +08:00
# API 文档 - Apex 连接管理
## 元数据
- 需求编号：002-01
- 需求名称：Apex 连接管理
- 创建时间：2026-02-02
- 创建人：AI Assistant
- 版本：v1.0.0
## API 概述
本 API 文档描述了 Salesforce Apex API 连接管理接口，提供了完整的连接管理功能，包括连接获取、会话头设置、调用选项配置、调试头部配置、字段截断头配置、包版本头配置和连接缓存清除等功能。
### 核心功能
- **连接工厂**：创建和管理 SoapConnection 实例
- **会话头管理**：设置和更新 SessionHeader
- **调用选项**：配置 CallOptions 头部
- **调试头部**：配置 DebuggingHeader 用于调试
- **字段截断头**：配置 AllowFieldTruncationHeader
- **包版本头**：配置 PackageVersionHeader
- **连接缓存**：使用 AbstractConnectionFactory 提供的缓存机制
### 技术特性
- 固定使用 source org 类型
- 继承 AbstractConnectionFactory<SoapConnection>，复用缓存机制
- 使用 Salesforce API 65.0 版本
- 连接超时 60 秒，读取超时 60 秒
- 支持连接压缩
### 安全特性
- 使用 Spring Security 进行权限控制
- 使用 @PreAuthorize 注解进行方法级权限控制
- 使用 @Valid 注解进行参数校验
- 统一的异常处理机制
## 接口列表
### 接口 1：获取连接
#### 功能描述
获取 SoapConnection 连接信息，包括会话 ID、服务器 URL、连接状态等信息。
#### 请求方式
GET
#### 请求路径
`/api/apex/connection`
#### 权限要求
`apex:connection:get`
#### 请求参数
无
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.sessionId | String | 会话 ID（前 20 位） |
| data.serverUrl | String | 服务器 URL |
| data.success | Boolean | 是否成功 |
| data.errorMessage | String | 错误信息（成功时为 null） |
#### 成功示例
```json
{
"code": 200,
"msg": "获取连接成功",
"data": {
"sessionId": "00Dxx0000001Gw2!AQ0AQH...",
"serverUrl": "https://datai-dev-ed.my.salesforce.com",
"success": true,
"errorMessage": null
}
}
```
#### 失败示例
```json
{
"code": 500,
"msg": "获取连接失败: 未找到 source org 的会话信息，请先登录"
}
```
---
### 接口 2：设置会话头
#### 功能描述
设置 SoapConnection 的会话头（SessionHeader），用于指定会话 ID。
#### 请求方式
POST
#### 请求路径
`/api/apex/connection/session-header`
#### 权限要求
`apex:connection:session`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sessionId | String | 是 | 会话 ID，长度 1-255 字符 |
#### 请求示例
```json
{
"sessionId": "00Dxx0000001Gw2!AQ0AQH..."
}
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |
#### 成功示例
```json
{
"code": 200,
"msg": "设置会话头成功",
"data": {
"success": true
}
}
```
#### 失败示例
```json
{
"code": 500,
"msg": "设置会话头失败: 未找到连接"
}
```
---
### 接口 3：设置调用选项
#### 功能描述
设置 SoapConnection 的调用选项（CallOptions），用于指定客户端名称。
#### 请求方式
POST
#### 请求路径
`/api/apex/connection/call-options`
#### 权限要求
`apex:connection:call`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| client | String | 否 | 客户端名称，长度 1-255 字符 |
#### 请求示例
```json
{
"client": "DataiSalesforceApex/1.0.0"
}
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |
#### 成功示例
```json
{
"code": 200,
"msg": "设置调用选项成功",
"data": {
"success": true
}
}
```
#### 失败示例
```json
{
"code": 500,
"msg": "设置调用选项失败: 未找到连接"
}
```
---
### 接口 4：设置调试头部
#### 功能描述
设置 SoapConnection 的调试头部（DebuggingHeader），用于调试和日志记录。
#### 请求方式
POST
#### 请求路径
`/api/apex/connection/debugging-header`
#### 权限要求
`apex:connection:debug`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| logCategories | Array | 否 | 日志分类数组 |
| logCategories[].category | String | 否 | 日志分类（如：DB、VALIDATION、WORKFLOW、CALLOUT、APEX_CODE） |
| logCategories[].level | String | 否 | 日志级别（如：FINE、FINER、FINEST、DEBUG、INFO、WARN、ERROR） |
| logType | String | 否 | 日志类型（如：PROFILING、DEBUGONLY） |
#### 请求示例
```json
{
"logCategories": [
{
"category": "DB",
"level": "FINE"
},
{
"category": "APEX_CODE",
"level": "DEBUG"
}
],
"logType": "PROFILING"
}
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |
#### 成功示例
```json
{
"code": 200,
"msg": "设置调试头部成功",
"data": {
"success": true
}
}
```
#### 失败示例
```json
{
"code": 500,
"msg": "设置调试头部失败: 未找到连接"
}
```
---
### 接口 5：设置字段截断头
#### 功能描述
设置 SoapConnection 的字段截断头（AllowFieldTruncationHeader），用于控制字段截断行为。
#### 请求方式
POST
#### 请求路径
`/api/apex/connection/field-truncation-header`
#### 权限要求
`apex:connection:truncate`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| allowFieldTruncation | Boolean | 否 | 是否允许字段截断（true：允许，false：不允许） |
#### 请求示例
```json
{
"allowFieldTruncation": true
}
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |
#### 成功示例
```json
{
"code": 200,
"msg": "设置字段截断头成功",
"data": {
"success": true
}
}
```
#### 失败示例
```json
{
"code": 500,
"msg": "设置字段截断头失败: 未找到连接"
}
```
---
### 接口 6：设置包版本头
#### 功能描述
设置 SoapConnection 的包版本头（PackageVersionHeader），用于指定包版本信息。
#### 请求方式
POST
#### 请求路径
`/api/apex/connection/package-version-header`
#### 权限要求
`apex:connection:version`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| packageVersions | Array | 否 | 包版本数组 |
| packageVersions[].namespace | String | 否 | 包命名空间 |
| packageVersions[].majorNumber | Integer | 否 | 主版本号 |
| packageVersions[].minorNumber | Integer | 否 | 次版本号 |
| packageVersions[].namespacePrefix | String | 否 | 命名空间前缀 |
#### 请求示例
```json
{
"packageVersions": [
{
"namespace": "MyPackage",
"majorNumber": 1,
"minorNumber": 0,
"namespacePrefix": "mypkg"
}
]
}
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |
#### 成功示例
```json
{
"code": 200,
"msg": "设置包版本头成功",
"data": {
"success": true
}
}
```
#### 失败示例
```json
{
"code": 500,
"msg": "设置包版本头失败: 未找到连接"
}
```
---
### 接口 7：清除连接缓存
#### 功能描述
清除 Apex 连接缓存，强制重新创建连接。
#### 请求方式
DELETE
#### 请求路径
`/api/apex/connection/cache`
#### 权限要求
`apex:connection:clear`
#### 请求参数
无
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |
#### 成功示例
```json
{
"code": 200,
"msg": "清除连接缓存成功",
"data": {
"success": true
}
}
```
#### 失败示例
```json
{
"code": 500,
"msg": "清除连接缓存失败: 清除缓存失败"
}
```
## 错误码
### 通用错误码
| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 200 | 操作成功 | 请求处理成功 |
| 400 | 请求参数错误 | 请求参数格式错误或缺少必填参数 |
| 401 | 未授权 | 用户未登录或登录已过期 |
| 403 | 无权限 | 用户没有访问该接口的权限 |
| 500 | 服务器内部错误 | 服务器处理请求时发生错误 |
### 业务错误码
| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 501 | 未找到 source org 的会话信息 | 请先登录 source org |
| 502 | 未找到连接 | 连接不存在或已失效 |
| 503 | 创建连接失败 | 创建连接时发生错误 |
| 504 | 设置会话头失败 | 设置会话头时发生错误 |
| 505 | 设置调用选项失败 | 设置调用选项时发生错误 |
| 506 | 设置调试头部失败 | 设置调试头部时发生错误 |
| 507 | 设置字段截断头失败 | 设置字段截断头时发生错误 |
| 508 | 设置包版本头失败 | 设置包版本头时发生错误 |
| 509 | 清除连接缓存失败 | 清除连接缓存时发生错误 |
### 参数校验错误码
| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 601 | 会话ID不能为空 | 设置会话头时，会话 ID 参数为空 |
## 相关文档
### 需求文档
- [Apex 连接管理需求](../requirements/sub/2026-01-28-002-01-连接管理.md)
### 设计文档
- [Apex 连接管理设计](../design/2026-02-02-002-01-连接管理-设计.md)
### 决策记录
- [Apex 连接管理技术选型](../decisions/2026-02-02-002-01-ADR-Apex连接管理技术选型.md)
### 复盘文档
- [Apex 连接管理复盘](../retros/2026-02-02-002-01-retro.md)
## 附录
### Swagger 文档访问
启动应用后，可以通过以下 URL 访问 Swagger UI：
- Swagger UI: `http://localhost:8080/swagger-ui.html`
- API JSON: `http://localhost:8080/v3/api-docs`
### Postman 集合
可以使用 Postman 导入以下集合进行 API 测试：
```json
{
"info": {
"name": "Apex Connection Management",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "获取连接",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/apex/connection",
"host": ["{{baseUrl}}"],
"path": ["api", "apex", "connection"]
}
}
},
{
"name": "设置会话头",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"sessionId\": \"00Dxx0000001Gw2!AQ0AQH...\"\n}"
},
"url": {
"raw": "{{baseUrl}}/api/apex/connection/session-header",
"host": ["{{baseUrl}}"],
"path": ["api", "apex", "connection", "session-header"]
}
}
}
]
}
```
### 权限配置
在使用这些 API 接口之前，需要在系统中配置相应的权限：
- `apex:connection:get` - 获取连接权限
- `apex:connection:session` - 设置会话头权限
- `apex:connection:call` - 设置调用选项权限
- `apex:connection:debug` - 设置调试头部权限
- `apex:connection:truncate` - 设置字段截断头权限
- `apex:connection:version` - 设置包版本头权限
- `apex:connection:clear` - 清除连接缓存权限
### 认证说明
所有 API 接口都需要进行身份认证，请在请求头中添加以下认证信息：
```
Authorization: Bearer {token}
```
其中 `{token}` 为登录后获取的 JWT 令牌。
Reference in New Issue Copy Permalink