kris/datai

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

26 KiB

Raw Permalink Blame History

datai-salesforce-tooling 模块详细文档

模块概述

datai-salesforce-tooling 是 Datai 项目中专门用于管理 Salesforce Tooling API 相关功能的模块。该模块提供了对 Salesforce Tooling API 的连接管理、元数据操作、SOQL 查询、Apex 日志、测试管理、代码覆盖率等功能的完整支持。

模块路径: d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling

创建日期: 2026-02-04

版本: 1.0.0

Java 版本: 22

技术栈

核心依赖

依赖	版本	说明
datai-file-common	1.0.0	文件通用模块
datai-salesforce-auth	-	Salesforce 认证模块
javapoet	1.13.0	Java 代码生成库
salesforce-tooling	0.0.1	Salesforce Tooling 工具包（本地 JAR）

技术框架

Spring Boot: 应用框架
MyBatis: ORM 框架
Swagger/OpenAPI: API 文档
Spring Security: 安全认证
Lombok: 简化 Java 代码
JavaPoet: 动态代码生成

模块架构

分层架构

datai-salesforce-tooling/
├── controller/          # 控制器层（16个）
├── service/            # 服务层
│   ├── I*Service.java  # 服务接口（16个）
│   └── impl/           # 服务实现（16个）
├── mapper/             # 数据访问层（15个）
├── model/              # 数据模型层
│   ├── domain/         # 领域模型（15个）
│   ├── dto/            # 数据传输对象（15个）
│   └── vo/             # 视图对象（17个）
├── enums/              # 枚举类（1个）
├── factory/            # 工厂类（1个）
└── resources/
    ├── mapper/tooling/  # MyBatis XML 映射文件（14个）
    └── lib/tooling.jar # Salesforce Tooling 工具包

功能模块

1. Tooling API 连接管理

功能描述: 管理 Salesforce Tooling API 的连接，包括连接创建、缓存清除、连接测试、调用选项设置、调试头部设置等。

相关类:

Controller: ToolingConnectionController.java
Service: IToolingConnectionService.java
Factory: ToolingConnectionFactory.java
Enum: ToolingConnectionErrorCode.java

API 端点:

GET /salesforce/tooling/connection/get - 获取 Tooling API 连接
DELETE /salesforce/tooling/connection/clear - 清除连接缓存
GET /salesforce/tooling/connection/test - 测试连接
POST /salesforce/tooling/connection/call-options - 设置调用选项
POST /salesforce/tooling/connection/debugging-header - 设置调试头部

连接错误码:

错误码	说明
TOOLING_CONN_001	Session 无效或已过期
TOOLING_CONN_002	连接创建失败
TOOLING_CONN_003	网络超时
TOOLING_CONN_004	权限不足
TOOLING_CONN_005	API 版本不支持
TOOLING_CONN_006	用户未登录
TOOLING_CONN_007	设置调用选项失败
TOOLING_CONN_008	设置调试头部失败

连接结果对象 (ToolingConnectionResult.java):

success: 是否成功
connectionId: 连接 ID
sessionId: Session ID
instanceUrl: 实例 URL
connectionTime: 连接时间
errorCode: 错误码
errorMessage: 错误消息
valid: 是否有效
testTime: 测试时间
responseTime: 响应时间（毫秒）
client: 客户端名称
debugLevel: 调试级别

2. Apex 代码覆盖率管理

功能描述: 管理 Tooling API 的 Apex 代码覆盖率数据，包括类或触发器的覆盖率信息。

相关类:

Controller: DataiToolingApexCodeCoverageController.java
Domain: DataiToolingApexCodeCoverage.java

API 端点:

GET /tooling/toolingapexcodecoverage/list - 查询覆盖率列表
POST /tooling/toolingapexcodecoverage/export - 导出覆盖率数据
GET /tooling/toolingapexcodecoverage/{id} - 获取覆盖率详情
POST /tooling/toolingapexcodecoverage - 新增覆盖率记录
PUT /tooling/toolingapexcodecoverage - 修改覆盖率记录
DELETE /tooling/toolingapexcodecoverage/{ids} - 删除覆盖率记录

数据字段:

id: 主键ID
apexClassOrTriggerId: 类或触发器ID
apexTestClassId: 测试类ID
coverage: 覆盖率百分比
numLinesCovered: 覆盖行数
numLinesUncovered: 未覆盖行数
resultTime: 结果时间
sfUserId: Salesforce用户ID

3. Apex 代码位置管理

功能描述: 管理 Apex 代码的位置信息。

相关类:

Controller: DataiToolingApexCodeLocationController.java
Domain: DataiToolingApexCodeLocation.java

API 端点:

GET /tooling/toolingapexcodelocation/list - 查询代码位置列表
POST /tooling/toolingapexcodelocation/export - 导出代码位置数据
GET /tooling/toolingapexcodelocation/{id} - 获取代码位置详情
POST /tooling/toolingapexcodelocation - 新增代码位置记录
PUT /tooling/toolingapexcodelocation - 修改代码位置记录
DELETE /tooling/toolingapexcodelocation/{ids} - 删除代码位置记录

4. Apex 日志管理

功能描述: 管理 Tooling API 的 Apex 执行日志。

相关类:

Controller: DataiToolingApexLogController.java
Domain: DataiToolingApexLog.java

API 端点:

GET /tooling/toolingapexlog/list - 查询日志列表
POST /tooling/toolingapexlog/export - 导出日志数据
GET /tooling/toolingapexlog/{id} - 获取日志详情
POST /tooling/toolingapexlog - 新增日志记录
PUT /tooling/toolingapexlog - 修改日志记录
DELETE /tooling/toolingapexlog/{ids} - 删除日志记录

数据字段:

id: 主键ID
logId: 日志ID
application: 应用程序
durationMilliseconds: 持续时间（毫秒）
location: 位置
logLength: 日志长度
operation: 操作
startTime: 开始时间
status: 状态
sfUserId: Salesforce用户ID

5. Apex 测试队列项管理

功能描述: 管理 Apex 测试队列项，包括测试类、测试方法、状态等信息。

相关类:

Controller: DataiToolingApexTestQueueItemController.java
Domain: DataiToolingApexTestQueueItem.java

API 端点:

GET /tooling/toolingapextestqueueitem/list - 查询测试队列项列表
POST /tooling/toolingapextestqueueitem/export - 导出测试队列项数据
GET /tooling/toolingapextestqueueitem/{id} - 获取测试队列项详情
POST /tooling/toolingapextestqueueitem - 新增测试队列项记录
PUT /tooling/toolingapextestqueueitem - 修改测试队列项记录
DELETE /tooling/toolingapextestqueueitem/{ids} - 删除测试队列项记录

数据字段:

id: 主键ID
queueItemId: 队列项ID
apexClassId: Apex类ID
methodNames: 方法名列表
parentJobId: 父作业ID
status: 状态
extendedStatus: 扩展状态
createdDate: 创建时间
lastModifiedDate: 最后修改时间

6. Flow 测试覆盖率管理

功能描述: 管理 Flow 测试覆盖率数据。

相关类:

Controller: DataiToolingFlowTestCoverageController.java
Domain: DataiToolingFlowTestCoverage.java

API 端点:

GET /tooling/toolingflowtestcoverage/list - 查询 Flow 测试覆盖率列表
POST /tooling/toolingflowtestcoverage/export - 导出 Flow 测试覆盖率数据
GET /tooling/toolingflowtestcoverage/{id} - 获取 Flow 测试覆盖率详情
POST /tooling/toolingflowtestcoverage - 新增 Flow 测试覆盖率记录
PUT /tooling/toolingflowtestcoverage - 修改 Flow 测试覆盖率记录
DELETE /tooling/toolingflowtestcoverage/{ids} - 删除 Flow 测试覆盖率记录

7. 元数据对象管理

功能描述: 管理 Tooling API 的元数据对象，包括元数据类型、ID、名称、版本等信息。

相关类:

Controller: DataiToolingMetadataObjectController.java
Domain: DataiToolingMetadataObject.java

API 端点:

GET /tooling/toolingmetadataobject/list - 查询元数据对象列表
POST /tooling/toolingmetadataobject/export - 导出元数据对象数据
GET /tooling/toolingmetadataobject/{id} - 获取元数据对象详情
POST /tooling/toolingmetadataobject - 新增元数据对象记录
PUT /tooling/toolingmetadataobject - 修改元数据对象记录
DELETE /tooling/toolingmetadataobject/{ids} - 删除元数据对象记录

数据字段:

id: 主键ID
metadataType: 元数据类型
metadataId: 元数据ID
metadataName: 元数据名称
apiVersion: API版本
status: 状态
bodyCrc: 代码CRC
attributes: 对象属性JSON
createdDate: 创建时间
lastModifiedDate: 最后修改时间
sfUserId: Salesforce用户ID

8. 元数据操作日志管理

功能描述: 记录 Tooling API 的元数据操作日志，包括创建、更新、删除、查询等操作。

相关类:

Controller: DataiToolingMetadataOperationLogController.java
Domain: DataiToolingMetadataOperationLog.java

API 端点:

GET /tooling/toolingmetadataoperationlog/list - 查询元数据操作日志列表
POST /tooling/toolingmetadataoperationlog/export - 导出元数据操作日志数据
GET /tooling/toolingmetadataoperationlog/{id} - 获取元数据操作日志详情
POST /tooling/toolingmetadataoperationlog - 新增元数据操作日志记录
PUT /tooling/toolingmetadataoperationlog - 修改元数据操作日志记录
DELETE /tooling/toolingmetadataoperationlog/{ids} - 删除元数据操作日志记录

数据字段:

id: 主键ID
operationType: 操作类型（create/update/delete/query）
metadataType: 元数据类型
metadataId: 元数据ID
metadataName: 元数据名称
requestData: 请求数据（JSON 格式）
responseData: 响应数据（JSON 格式）
status: 操作状态（success/failed）
errorCode: 错误码
errorMessage: 错误消息
operationTime: 操作时间
sfUserId: Salesforce用户ID

9. SOQL 查询日志管理

功能描述: 记录 SOQL 查询操作日志，包括查询字符串、结果数量、执行时间等信息。

相关类:

Controller: DataiToolingSoqlQueryLogController.java
Domain: DataiToolingSoqlQueryLog.java

API 端点:

GET /tooling/toolingsoqlquerylog/list - 查询 SOQL 查询日志列表
POST /tooling/toolingsoqlquerylog/export - 导出 SOQL 查询日志数据
GET /tooling/toolingsoqlquerylog/{id} - 获取 SOQL 查询日志详情
POST /tooling/toolingsoqlquerylog - 新增 SOQL 查询日志记录
PUT /tooling/toolingsoqlquerylog - 修改 SOQL 查询日志记录
DELETE /tooling/toolingsoqlquerylog/{ids} - 删除 SOQL 查询日志记录

数据字段:

id: 主键ID
operationType: 操作类型（execute_query/query_more/query_all）
queryString: SOQL 查询字符串
queryLocator: 查询定位器（用于 queryMore）
objectType: 查询对象类型
resultCount: 结果数量（当前批次）
totalSize: 总大小（所有批次）
isDone: 是否完成
status: 操作状态（success/failed）
errorCode: 错误码（TOOLING_SOQL_001 ~ TOOLING_SOQL_006）
errorMessage: 错误消息
executionTimeMs: 执行时间（毫秒）
operationTime: 操作时间
sfUserId: Salesforce用户ID

10. SOQL 查询结果管理

功能描述: 管理 SOQL 查询结果数据。

相关类:

Controller: DataiToolingSoqlQueryResultController.java
Domain: DataiToolingSoqlQueryResult.java

API 端点:

GET /tooling/toolingsoqlqueryresult/list - 查询 SOQL 查询结果列表
POST /tooling/toolingsoqlqueryresult/export - 导出 SOQL 查询结果数据
GET /tooling/toolingsoqlqueryresult/{id} - 获取 SOQL 查询结果详情
POST /tooling/toolingsoqlqueryresult - 新增 SOQL 查询结果记录
PUT /tooling/toolingsoqlqueryresult - 修改 SOQL 查询结果记录
DELETE /tooling/toolingsoqlqueryresult/{ids} - 删除 SOQL 查询结果记录

11. 访问安全日志管理

功能描述: 记录 Tooling API 的访问安全日志。

相关类:

Controller: DataiToolingAccessSecurityLogController.java
Domain: DataiToolingAccessSecurityLog.java

API 端点:

GET /tooling/toolingaccesssecuritylog/list - 查询访问安全日志列表
POST /tooling/toolingaccesssecuritylog/export - 导出访问安全日志数据
GET /tooling/toolingaccesssecuritylog/{id} - 获取访问安全日志详情
POST /tooling/toolingaccesssecuritylog - 新增访问安全日志记录
PUT /tooling/toolingaccesssecuritylog - 修改访问安全日志记录
DELETE /tooling/toolingaccesssecuritylog/{ids} - 删除访问安全日志记录

12. 动作自动化日志管理

功能描述: 记录动作自动化操作的日志。

相关类:

Controller: DataiToolingActionAutomationLogController.java
Domain: DataiToolingActionAutomationLog.java

API 端点:

GET /tooling/toolingactionautomationlog/list - 查询动作自动化日志列表
POST /tooling/toolingactionautomationlog/export - 导出动作自动化日志数据
GET /tooling/toolingactionautomationlog/{id} - 获取动作自动化日志详情
POST /tooling/toolingactionautomationlog - 新增动作自动化日志记录
PUT /tooling/toolingactionautomationlog - 修改动作自动化日志记录
DELETE /tooling/toolingactionautomationlog/{ids} - 删除动作自动化日志记录

13. 高级功能日志管理

功能描述: 记录高级功能操作的日志。

相关类:

Controller: DataiToolingAdvancedFeaturesLogController.java
Domain: DataiToolingAdvancedFeaturesLog.java

API 端点:

GET /tooling/toolingadvancedfeatureslog/list - 查询高级功能日志列表
POST /tooling/toolingadvancedfeatureslog/export - 导出高级功能日志数据
GET /tooling/toolingadvancedfeatureslog/{id} - 获取高级功能日志详情
POST /tooling/toolingadvancedfeatureslog - 新增高级功能日志记录
PUT /tooling/toolingadvancedfeatureslog - 修改高级功能日志记录
DELETE /tooling/toolingadvancedfeatureslog/{ids} - 删除高级功能日志记录

14. AI 操作日志管理

功能描述: 记录 AI 相关操作的日志。

相关类:

Controller: DataiToolingAiOperationLogController.java
Domain: DataiToolingAiOperationLog.java

API 端点:

GET /tooling/toolingaioperationlog/list - 查询 AI 操作日志列表
POST /tooling/toolingaioperationlog/export - 导出 AI 操作日志数据
GET /tooling/toolingaioperationlog/{id} - 获取 AI 操作日志详情
POST /tooling/toolingaioperationlog - 新增 AI 操作日志记录
PUT /tooling/toolingaioperationlog - 修改 AI 操作日志记录
DELETE /tooling/toolingaioperationlog/{ids} - 删除 AI 操作日志记录

15. 开发工具操作日志管理

功能描述: 记录开发工具操作的日志。

相关类:

Controller: DataiToolingDevtoolsOperationLogController.java
Domain: DataiToolingDevtoolsOperationLog.java

API 端点:

GET /tooling/toolingdevtoolsoperationlog/list - 查询开发工具操作日志列表
POST /tooling/toolingdevtoolsoperationlog/export - 导出开发工具操作日志数据
GET /tooling/toolingdevtoolsoperationlog/{id} - 获取开发工具操作日志详情
POST /tooling/toolingdevtoolsoperationlog - 新增开发工具操作日志记录
PUT /tooling/toolingdevtoolsoperationlog - 修改开发工具操作日志记录
DELETE /tooling/toolingdevtoolsoperationlog/{ids} - 删除开发工具操作日志记录

数据模型设计

统一基类

所有 Domain 类都继承自 BaseEntity，包含以下公共字段：

- createBy: 创建人
- createTime: 创建时间
- updateBy: 更新人
- updateTime: 更新时间
- remark: 备注

模型转换

模块采用三层模型设计：

Domain（领域模型）: 对应数据库表结构，用于持久化
DTO（数据传输对象）: 用于接收前端请求参数
VO（视图对象）: 用于返回前端响应数据

转换方法:

Dto.toObj(): DTO 转 Domain
Dto.fromObj(): Domain 转 DTO
Vo.objToVo(): Domain 转 VO

连接管理

连接工厂

ToolingConnectionFactory 继承自 AbstractConnectionFactory，提供 ToolingConnection 实例的创建和管理。

API 版本: 60.0

连接创建流程:

从 SessionManager 获取当前登录结果
验证登录状态和 Session ID
创建 ConnectorConfig 配置
设置 Service Endpoint
创建 ToolingConnection 实例
设置会话头

连接配置:

sessionId: 会话 ID
serviceEndpoint: 服务端点（{instanceUrl}/services/Soap/T/60.0）
compression: 启用压缩
traceMessage: 禁用消息跟踪

安全控制

权限注解

所有 Controller 方法都使用 @PreAuthorize 注解进行权限控制：

@PreAuthorize("@ss.hasPermi('tooling:模块:操作')")

权限格式: tooling:{模块名}:{操作}

操作类型:

list: 查询列表
query: 查询详情
add: 新增
edit: 修改
remove: 删除
export: 导出
get: 获取
clear: 清除
test: 测试
callOptions: 设置调用选项
debuggingHeader: 设置调试头部

日志记录

使用 @Log 注解记录业务操作日志：

@Log(title = "模块名称", businessType = BusinessType.INSERT/UPDATE/DELETE/EXPORT/OTHER)

API 文档

Swagger/OpenAPI

所有 API 接口都使用 Swagger 3.0 注解进行文档化：

@Tag(name = "模块名称", description = "模块描述")
@Operation(summary = "操作说明", description = "详细描述")

访问路径: /swagger-ui.html 或 /doc.html

数据库映射

MyBatis 配置

所有 Mapper XML 文件位于 src/main/resources/mapper/tooling/ 目录下。

命名规范:

Mapper 接口: DataiToolingXxxMapper.java
XML 映射文件: DataiToolingXxxMapper.xml

表命名规范: datai_tooling_xxx

结果映射

使用 <resultMap> 定义数据库字段到 Java 对象的映射：

<resultMap type="DataiToolingXxx" id="DataiToolingXxxResult">
    <result property="javaField" column="db_column" />
</resultMap>

动态 SQL

使用 MyBatis 动态 SQL 标签：

<where>: 动态 WHERE 条件
<if>: 条件判断
<trim>: 去除多余逗号
<foreach>: 批量操作

代码规范

Controller 层

继承 BaseController
使用 @RestController 注解
统一返回 AjaxResult 或 TableDataInfo
使用 Stream API 进行 DTO/VO 转换
使用 @Slf4j 进行日志记录

Service 层

定义接口 IXxxService
实现类 XxxServiceImpl
使用 @Service 注解
自动注入 Mapper

Mapper 层

定义接口 XxxMapper
使用 MyBatis 注解或 XML 映射
支持增删改查操作

模型层

Domain 使用 @Schema 注解
DTO 使用 @Data 注解（Lombok）
VO 使用 @Data 注解（Lombok）
使用 BeanUtils.copyProperties() 进行属性拷贝

工厂层

继承 AbstractConnectionFactory
使用 @Component 注解
实现 createConnection 方法
使用 @Slf4j 进行日志记录

依赖关系

外部依赖

datai-salesforce-tooling
├── datai-file-common (文件通用模块)
├── datai-salesforce-auth (Salesforce 认证模块)
├── javapoet (Java 代码生成库)
└── salesforce-tooling (Salesforce Tooling 工具包)

内部依赖

Controller → Service → Mapper → Database
     ↓          ↓
    DTO      Domain
     ↓          ↓
    VO      VO

扩展点

1. 自定义连接配置

在 ToolingConnectionFactory 中扩展连接配置逻辑。

2. 自定义错误处理

扩展 ToolingConnectionErrorCode 枚举，添加新的错误码。

3. 自定义元数据操作

扩展元数据操作日志，支持更多元数据类型。

4. 自定义 SOQL 查询

扩展 SOQL 查询日志，支持更多查询类型。

注意事项

权限控制: 所有 API 接口都需要相应的权限才能访问
数据校验: 建议在 DTO 层添加数据校验注解
事务管理: Service 层方法可根据需要添加 @Transactional 注解
异常处理: 建议统一使用全局异常处理器
日志记录: 重要操作需要记录日志
分页查询: 列表查询接口支持分页参数
连接管理: Tooling API 连接需要定期刷新
API 版本: 当前使用 API 版本 60.0，升级时需要同步更新

更新日志

2026-02-04

初始版本创建
实现 15 个功能模块的 CRUD 接口
实现 Tooling API 连接管理功能
完成数据模型设计
配置 MyBatis 映射
集成 Swagger API 文档
添加连接工厂和错误码枚举

联系方式

模块负责人: datai

创建日期: 2026-02-04

文档版本: 1.0.0

26 KiB Raw Permalink Blame History Unescape Escape

datai-salesforce-tooling 模块详细文档

模块概述

技术栈

核心依赖

技术框架

模块架构

分层架构

功能模块

1. Tooling API 连接管理

2. Apex 代码覆盖率管理

3. Apex 代码位置管理

4. Apex 日志管理

5. Apex 测试队列项管理

6. Flow 测试覆盖率管理

7. 元数据对象管理

8. 元数据操作日志管理

9. SOQL 查询日志管理

10. SOQL 查询结果管理

11. 访问安全日志管理

12. 动作自动化日志管理

13. 高级功能日志管理

14. AI 操作日志管理

15. 开发工具操作日志管理

数据模型设计

统一基类

模型转换

连接管理

连接工厂

安全控制

权限注解

日志记录

API 文档

Swagger/OpenAPI

数据库映射

MyBatis 配置

结果映射

动态 SQL

代码规范

Controller 层

Service 层

Mapper 层

模型层

工厂层

依赖关系

外部依赖

内部依赖

扩展点

1. 自定义连接配置

2. 自定义错误处理

3. 自定义元数据操作

4. 自定义 SOQL 查询

注意事项

更新日志

2026-02-04

联系方式

26 KiB

Raw Permalink Blame History