530 lines
13 KiB
Markdown
530 lines
13 KiB
Markdown
# API 文档
|
||
|
||
## 元数据
|
||
- 需求编号：003
|
||
- 子需求编号：003-01
|
||
- 子需求名称：连接管理
|
||
- 创建时间：2026-02-05
|
||
- 创建人：AI Assistant
|
||
- 版本号：v1.0.0
|
||
- 接口基地址：`/api/metadata/connection`
|
||
|
||
## API 概述
|
||
Metadata API 连接管理接口提供对 Salesforce Metadata API 连接的管理能力，包括连接状态的获取、连接测试、连接刷新、连接关闭、调用选项设置、连接历史记录查询和连接缓存清除等功能。
|
||
|
||
### 核心功能
|
||
1. **连接状态管理**：获取当前 Metadata API 连接的状态信息
|
||
2. **连接测试**：测试 Metadata API 连接是否可用
|
||
3. **连接刷新**：刷新 Metadata API 连接，重新创建连接实例
|
||
4. **连接关闭**：关闭 Metadata API 连接，释放资源
|
||
5. **调用选项设置**：设置 Metadata API 的调用选项（如客户端名称）
|
||
6. **连接历史记录**：查询 Metadata API 连接的历史记录
|
||
7. **连接缓存管理**：清除 Metadata API 连接缓存
|
||
|
||
### 认证方式
|
||
所有接口都需要通过认证，使用 Spring Security 进行权限控制。请求头中需要包含有效的 JWT Token。
|
||
|
||
### 权限要求
|
||
每个接口都有特定的权限要求，使用 `@PreAuthorize` 注解进行控制。
|
||
|
||
## 接口列表
|
||
|
||
### 1. 获取连接状态
|
||
|
||
**功能描述**：获取当前 Metadata API 连接的状态信息，包括连接是否有效、最后测试时间、响应时间等。
|
||
|
||
**请求方式**：GET
|
||
|
||
**请求路径**：`/api/metadata/connection/status`
|
||
|
||
**权限要求**：`metadata:connection:status`
|
||
|
||
**请求参数**：无
|
||
|
||
**响应参数**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| 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.errorMessage | String | 错误信息（如果有） |
|
||
|
||
**成功示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "获取连接状态成功",
|
||
"data": {
|
||
"success": true,
|
||
"valid": true,
|
||
"testTime": "2026-02-05 14:30:00",
|
||
"responseTime": 150,
|
||
"errorMessage": null
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "获取连接状态失败: 用户未登录或会话已过期",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误码**：
|
||
- 200：成功
|
||
- 500：服务器内部错误
|
||
- 401：未授权
|
||
- 403：权限不足
|
||
|
||
---
|
||
|
||
### 2. 测试连接
|
||
|
||
**功能描述**：测试 Metadata API 连接是否可用，会实际调用 Salesforce API 进行验证。
|
||
|
||
**请求方式**：POST
|
||
|
||
**请求路径**：`/api/metadata/connection/test`
|
||
|
||
**权限要求**：`metadata:connection:test`
|
||
|
||
**请求参数**：无
|
||
|
||
**响应参数**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 响应数据（成功时为 null） |
|
||
|
||
**成功示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "连接测试成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "连接测试失败: 无法连接到 Salesforce 服务器",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误码**：
|
||
- 200：连接测试成功
|
||
- 500：连接测试失败
|
||
|
||
**调用场景**：
|
||
- 系统启动时自动测试连接
|
||
- 用户手动测试连接状态
|
||
- 定时任务检查连接健康状态
|
||
|
||
---
|
||
|
||
### 3. 刷新连接
|
||
|
||
**功能描述**：刷新 Metadata API 连接，关闭现有连接并重新创建。适用于会话过期或需要重新建立连接的场景。
|
||
|
||
**请求方式**：POST
|
||
|
||
**请求路径**：`/api/metadata/connection/refresh`
|
||
|
||
**权限要求**：`metadata:connection:refresh`
|
||
|
||
**请求参数**：无
|
||
|
||
**响应参数**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 响应数据（成功时为 null） |
|
||
|
||
**成功示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "刷新连接成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "刷新连接失败: 会话已过期",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误码**：
|
||
- 200：刷新连接成功
|
||
- 500：刷新连接失败
|
||
|
||
**调用场景**：
|
||
- 会话过期后重新建立连接
|
||
- 连接出现异常时恢复连接
|
||
- 切换 org 类型后重新连接
|
||
|
||
---
|
||
|
||
### 4. 关闭连接
|
||
|
||
**功能描述**：关闭 Metadata API 连接，释放相关资源。关闭后需要调用刷新接口重新建立连接。
|
||
|
||
**请求方式**：POST
|
||
|
||
**请求路径**：`/api/metadata/connection/close`
|
||
|
||
**权限要求**：`metadata:connection:close`
|
||
|
||
**请求参数**：无
|
||
|
||
**响应参数**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 响应数据（成功时为 null） |
|
||
|
||
**成功示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "关闭连接成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "关闭连接失败: 连接不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误码**：
|
||
- 200：关闭连接成功
|
||
- 500：关闭连接失败
|
||
|
||
**调用场景**：
|
||
- 系统关闭时释放资源
|
||
- 切换用户时关闭旧连接
|
||
- 长时间不使用时释放连接
|
||
|
||
---
|
||
|
||
### 5. 设置调用选项
|
||
|
||
**功能描述**：设置 Metadata API 的调用选项，如客户端名称等。这些选项会影响 API 调用的行为。
|
||
|
||
**请求方式**：POST
|
||
|
||
**请求路径**：`/api/metadata/connection/call-options`
|
||
|
||
**权限要求**：`metadata:connection:callOptions`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| client | String | 是 | 客户端名称，用于标识调用来源 |
|
||
|
||
**请求示例**：
|
||
```json
|
||
{
|
||
"client": "DataiMetadataClient"
|
||
}
|
||
```
|
||
|
||
**响应参数**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 响应数据（成功时为 null） |
|
||
|
||
**成功示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "设置调用选项成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "设置调用选项失败: 客户端名称不能为空",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误码**：
|
||
- 200：设置调用选项成功
|
||
- 400：请求参数错误
|
||
- 500：设置调用选项失败
|
||
|
||
**调用场景**：
|
||
- 初始化连接时设置客户端标识
|
||
- 多客户端环境下区分调用来源
|
||
- 监控和日志记录时标识客户端
|
||
|
||
---
|
||
|
||
### 6. 获取连接历史记录
|
||
|
||
**功能描述**：获取 Metadata API 连接的历史记录，包括连接创建、测试、刷新、关闭等操作的记录。
|
||
|
||
**请求方式**：GET
|
||
|
||
**请求路径**：`/api/metadata/connection/history`
|
||
|
||
**权限要求**：`metadata:connection:history`
|
||
|
||
**请求参数**：无
|
||
|
||
**响应参数**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Array | 连接历史记录列表 |
|
||
| data[].id | Long | 记录 ID |
|
||
| data[].orgType | String | ORG 类型（source/target） |
|
||
| data[].status | String | 连接状态（connected/failed/closed） |
|
||
| data[].testTime | String | 测试时间（格式：yyyy-MM-dd HH:mm:ss） |
|
||
| data[].responseTime | Long | 响应时间（毫秒） |
|
||
| data[].errorMessage | String | 错误信息（如果有） |
|
||
| data[].createTime | String | 记录创建时间 |
|
||
| data[].updateTime | String | 记录更新时间 |
|
||
|
||
**成功示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "获取连接历史成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"orgType": "source",
|
||
"status": "connected",
|
||
"testTime": "2026-02-05 14:30:00",
|
||
"responseTime": 150,
|
||
"errorMessage": null,
|
||
"createTime": "2026-02-05 14:30:00",
|
||
"updateTime": "2026-02-05 14:30:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"orgType": "source",
|
||
"status": "failed",
|
||
"testTime": "2026-02-05 14:25:00",
|
||
"responseTime": 0,
|
||
"errorMessage": "会话已过期",
|
||
"createTime": "2026-02-05 14:25:00",
|
||
"updateTime": "2026-02-05 14:25:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "获取连接历史失败: 数据库连接错误",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误码**：
|
||
- 200：获取连接历史成功
|
||
- 500：获取连接历史失败
|
||
|
||
**调用场景**：
|
||
- 监控连接健康状态
|
||
- 排查连接问题
|
||
- 分析连接使用模式
|
||
|
||
---
|
||
|
||
### 7. 清除连接缓存
|
||
|
||
**功能描述**：清除 Metadata API 连接缓存，强制下次请求时重新创建连接。适用于连接状态异常或需要强制刷新连接的场景。
|
||
|
||
**请求方式**：DELETE
|
||
|
||
**请求路径**：`/api/metadata/connection/cache`
|
||
|
||
**权限要求**：`metadata:connection:clear`
|
||
|
||
**请求参数**：无
|
||
|
||
**响应参数**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 响应数据（成功时为 null） |
|
||
|
||
**成功示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "清除连接缓存成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "清除连接缓存失败: 缓存不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误码**：
|
||
- 200：清除连接缓存成功
|
||
- 500：清除连接缓存失败
|
||
|
||
**调用场景**：
|
||
- 连接状态异常时强制刷新
|
||
- 切换 org 配置后清除旧缓存
|
||
- 调试和测试时重置连接状态
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
### 系统错误码
|
||
|
||
| 错误码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| 200 | 操作成功 | 无需处理 |
|
||
| 400 | 请求参数错误 | 检查请求参数是否符合要求 |
|
||
| 401 | 未授权 | 检查 JWT Token 是否有效 |
|
||
| 403 | 权限不足 | 检查用户是否有该接口的权限 |
|
||
| 404 | 资源不存在 | 检查请求路径是否正确 |
|
||
| 500 | 服务器内部错误 | 查看服务器日志，联系管理员 |
|
||
|
||
### 业务错误码
|
||
|
||
| 错误码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| METADATA_CONNECTION_ERROR | Metadata API 连接错误 | 检查网络连接和 Salesforce 服务状态 |
|
||
| METADATA_AUTH_ERROR | Metadata API 认证错误 | 检查 Session 是否过期，尝试重新登录 |
|
||
| METADATA_OPERATION_ERROR | Metadata API 操作错误 | 检查操作参数是否正确 |
|
||
| SESSION_EXPIRED | 会话已过期 | 重新登录获取新的 Session |
|
||
| INVALID_SESSION | 无效的会话 | 检查 Session ID 是否正确 |
|
||
| CONNECTION_FAILED | 连接失败 | 检查网络连接和服务器地址 |
|
||
|
||
## 调用示例
|
||
|
||
### 完整调用流程
|
||
|
||
```java
|
||
// 1. 获取连接状态
|
||
GET /api/metadata/connection/status
|
||
Response: {
|
||
"code": 200,
|
||
"msg": "获取连接状态成功",
|
||
"data": {
|
||
"valid": true,
|
||
"testTime": "2026-02-05 14:30:00"
|
||
}
|
||
}
|
||
|
||
// 2. 如果连接无效，刷新连接
|
||
POST /api/metadata/connection/refresh
|
||
Response: {
|
||
"code": 200,
|
||
"msg": "刷新连接成功"
|
||
}
|
||
|
||
// 3. 测试连接
|
||
POST /api/metadata/connection/test
|
||
Response: {
|
||
"code": 200,
|
||
"msg": "连接测试成功"
|
||
}
|
||
|
||
// 4. 设置调用选项
|
||
POST /api/metadata/connection/call-options
|
||
Request Body: {
|
||
"client": "DataiMetadataClient"
|
||
}
|
||
Response: {
|
||
"code": 200,
|
||
"msg": "设置调用选项成功"
|
||
}
|
||
|
||
// 5. 执行业务操作（如部署元数据）
|
||
// ...
|
||
|
||
// 6. 关闭连接
|
||
POST /api/metadata/connection/close
|
||
Response: {
|
||
"code": 200,
|
||
"msg": "关闭连接成功"
|
||
}
|
||
```
|
||
|
||
## 性能指标
|
||
|
||
### 响应时间
|
||
- 获取连接状态：< 100ms
|
||
- 测试连接：< 2s（取决于网络状况）
|
||
- 刷新连接：< 3s（取决于网络状况）
|
||
- 关闭连接：< 100ms
|
||
- 设置调用选项：< 100ms
|
||
- 获取连接历史：< 500ms
|
||
- 清除连接缓存：< 100ms
|
||
|
||
### 并发限制
|
||
- 单个用户同时只能有一个活跃的 Metadata API 连接
|
||
- 连接缓存按 orgType 进行隔离
|
||
- 建议在高并发场景下使用连接池（后续版本支持）
|
||
|
||
## 注意事项
|
||
|
||
1. **会话管理**：所有接口都依赖有效的 Salesforce 会话，请确保在调用前先完成认证
|
||
2. **连接缓存**：连接会被缓存以提高性能，如需强制刷新请使用清除缓存接口
|
||
3. **错误处理**：建议对所有接口的错误情况进行处理，特别是认证错误和连接错误
|
||
4. **资源释放**：长时间不使用连接时，建议调用关闭连接接口释放资源
|
||
5. **历史记录**：连接历史记录会持久化到数据库，可用于监控和审计
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-003-01-连接管理.md)
|
||
- [设计文档](../design/2026-02-02-003-01-连接管理-设计.md)
|
||
- [决策记录](../decisions/2026-02-02-003-01-ADR-连接管理技术选型.md)
|
||
- [变更日志](../changelog/2026-02-05-003-01-changelog.md)
|
||
- [复盘文档](../retros/2026-02-05-003-01-retro.md)
|
||
- [会话记录](../sessions/2026-01-28-003-session.md)
|