kris/datai

Fork 0

Kris 6357f1c579 feat：提交所有模块基础搭建完成

2026-02-06 09:58:58 +08:00

12 KiB

Raw Blame History

API 文档 - Apex 连接管理

元数据

需求编号：002-01
需求名称：Apex 连接管理
创建时间：2026-02-02
创建人：AI Assistant
版本：v1.1.0（2026-02-04 更新）

API 概述

本 API 文档描述了 Salesforce Apex API 连接管理接口，提供了完整的连接管理功能，包括连接获取、会话头设置、调用选项配置、调试头部配置、字段截断头配置、包版本头配置和连接缓存清除等功能。

核心功能

连接工厂：创建和管理 SoapConnection 实例
会话头管理：设置和更新 SessionHeader
调用选项：配置 CallOptions 头部
调试头部：配置 DebuggingHeader 用于调试
字段截断头：配置 AllowFieldTruncationHeader
包版本头：配置 PackageVersionHeader
连接缓存：使用 AbstractConnectionFactory 提供的缓存机制

技术特性

固定使用 source org 类型
继承 AbstractConnectionFactory，复用缓存机制
使用 Salesforce API 65.0 版本
连接超时 60 秒，读取超时 60 秒
支持连接压缩

安全特性

使用 Spring Security 进行权限控制
使用 @PreAuthorize 注解进行方法级权限控制
使用 @Valid 注解进行参数校验
统一的异常处理机制

接口列表

接口 1：获取连接

功能描述

获取 SoapConnection 连接信息，包括会话 ID、服务器 URL、连接状态等信息。

请求方式

GET

请求路径

/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）

成功示例

{
  "code": 200,
  "msg": "获取连接成功",
  "data": {
    "sessionId": "00Dxx0000001Gw2!AQ0AQH...",
    "serverUrl": "https://datai-dev-ed.my.salesforce.com",
    "success": true,
    "errorMessage": null
  }
}

失败示例

{
  "code": 500,
  "msg": "获取连接失败: 未找到 source org 的会话信息，请先登录"
}

接口 2：设置会话头

功能描述

设置 SoapConnection 的会话头（SessionHeader），用于指定会话 ID。

请求方式

POST

请求路径

/apex/connection/session-header

权限要求

apex:connection:session

请求参数

参数名	类型	必填	说明
sessionId	String	是	会话 ID，长度 1-255 字符

请求示例

{
  "sessionId": "00Dxx0000001Gw2!AQ0AQH..."
}

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	响应数据
data.success	Boolean	是否成功

成功示例

{
  "code": 200,
  "msg": "设置会话头成功",
  "data": {
    "success": true
  }
}

失败示例

{
  "code": 500,
  "msg": "设置会话头失败: 未找到连接"
}

接口 3：设置调用选项

功能描述

设置 SoapConnection 的调用选项（CallOptions），用于指定客户端名称。

请求方式

POST

请求路径

/apex/connection/call-options

权限要求

apex:connection:call

请求参数

参数名	类型	必填	说明
client	String	否	客户端名称，长度 1-255 字符

请求示例

{
  "client": "DataiSalesforceApex/1.0.0"
}

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	响应数据
data.success	Boolean	是否成功

成功示例

{
  "code": 200,
  "msg": "设置调用选项成功",
  "data": {
    "success": true
  }
}

失败示例

{
  "code": 500,
  "msg": "设置调用选项失败: 未找到连接"
}

接口 4：设置调试头部

功能描述

设置 SoapConnection 的调试头部（DebuggingHeader），用于调试和日志记录。

请求方式

POST

请求路径

/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）

请求示例

{
  "logCategories": [
    {
      "category": "DB",
      "level": "FINE"
    },
    {
      "category": "APEX_CODE",
      "level": "DEBUG"
    }
  ],
  "logType": "PROFILING"
}

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	响应数据
data.success	Boolean	是否成功

成功示例

{
  "code": 200,
  "msg": "设置调试头部成功",
  "data": {
    "success": true
  }
}

失败示例

{
  "code": 500,
  "msg": "设置调试头部失败: 未找到连接"
}

接口 5：设置字段截断头

功能描述

设置 SoapConnection 的字段截断头（AllowFieldTruncationHeader），用于控制字段截断行为。

请求方式

POST

请求路径

/apex/connection/field-truncation-header

权限要求

apex:connection:truncate

请求参数

参数名	类型	必填	说明
allowFieldTruncation	Boolean	否	是否允许字段截断（true：允许，false：不允许）

请求示例

{
  "allowFieldTruncation": true
}

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	响应数据
data.success	Boolean	是否成功

成功示例

{
  "code": 200,
  "msg": "设置字段截断头成功",
  "data": {
    "success": true
  }
}

失败示例

{
  "code": 500,
  "msg": "设置字段截断头失败: 未找到连接"
}

接口 6：设置包版本头

功能描述

设置 SoapConnection 的包版本头（PackageVersionHeader），用于指定包版本信息。

请求方式

POST

请求路径

/apex/connection/package-version-header

权限要求

apex:connection:version

请求参数

参数名	类型	必填	说明
packageVersions	Array	否	包版本数组
packageVersions[].namespace	String	否	包命名空间
packageVersions[].majorNumber	Integer	否	主版本号
packageVersions[].minorNumber	Integer	否	次版本号
packageVersions[].namespacePrefix	String	否	命名空间前缀

请求示例

{
  "packageVersions": [
    {
      "namespace": "MyPackage",
      "majorNumber": 1,
      "minorNumber": 0,
      "namespacePrefix": "mypkg"
    }
  ]
}

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	响应数据
data.success	Boolean	是否成功

成功示例

{
  "code": 200,
  "msg": "设置包版本头成功",
  "data": {
    "success": true
  }
}

失败示例

{
  "code": 500,
  "msg": "设置包版本头失败: 未找到连接"
}

接口 7：清除连接缓存

功能描述

清除 Apex 连接缓存，强制重新创建连接。

请求方式

DELETE

请求路径

/apex/connection/cache

权限要求

apex:connection:clear

请求参数

无

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	响应数据
data.success	Boolean	是否成功

成功示例

{
  "code": 200,
  "msg": "清除连接缓存成功",
  "data": {
    "success": true
  }
}

失败示例

{
  "code": 500,
  "msg": "清除连接缓存失败: 清除缓存失败"
}

错误码

通用错误码

错误码	错误信息	说明
200	操作成功	请求处理成功
400	请求参数错误	请求参数格式错误或缺少必填参数
401	未授权	用户未登录或登录已过期
403	无权限	用户没有访问该接口的权限
500	服务器内部错误	服务器处理请求时发生错误

业务错误码

错误码	错误信息	说明
501	未找到 source org 的会话信息	请先登录 source org
502	未找到连接	连接不存在或已失效
503	创建连接失败	创建连接时发生错误
504	设置会话头失败	设置会话头时发生错误
505	设置调用选项失败	设置调用选项时发生错误
506	设置调试头部失败	设置调试头部时发生错误
507	设置字段截断头失败	设置字段截断头时发生错误
508	设置包版本头失败	设置包版本头时发生错误
509	清除连接缓存失败	清除连接缓存时发生错误

参数校验错误码

错误码	错误信息	说明
601	会话ID不能为空	设置会话头时，会话 ID 参数为空

附录

Swagger 文档访问

启动应用后，可以通过以下 URL 访问 Swagger UI：

Swagger UI: http://localhost:8080/swagger-ui.html
API JSON: http://localhost:8080/v3/api-docs

Postman 集合

可以使用 Postman 导入以下集合进行 API 测试：

{
  "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 令牌。

12 KiB Raw Blame History Unescape Escape

API 文档 - Apex 连接管理

元数据

API 概述

核心功能

技术特性

安全特性

接口列表

接口 1：获取连接

功能描述

请求方式

请求路径

权限要求

请求参数

响应参数

成功示例

失败示例

接口 2：设置会话头

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应参数

成功示例

失败示例

接口 3：设置调用选项

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应参数

成功示例

失败示例

接口 4：设置调试头部

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应参数

成功示例

失败示例

接口 5：设置字段截断头

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应参数

成功示例

失败示例

接口 6：设置包版本头

功能描述

请求方式

请求路径

权限要求

请求参数

请求示例

响应参数

成功示例

失败示例

接口 7：清除连接缓存

功能描述

请求方式

请求路径

权限要求

请求参数

响应参数

成功示例

失败示例

错误码

通用错误码

业务错误码

参数校验错误码

12 KiB

Raw Blame History