468 lines
11 KiB
Markdown
468 lines
11 KiB
Markdown
# API 文档：003-04 异步操作
|
||
|
||
## 元数据
|
||
- **需求编号**: 003-04
|
||
- **需求名称**: 异步操作
|
||
- **创建时间**: 2026-02-06
|
||
- **创建人**: AI Assistant
|
||
- **版本号**: v1.0.0
|
||
- **状态**: 已完成
|
||
|
||
---
|
||
|
||
## API 概述
|
||
|
||
本文档描述了 Metadata API 异步操作管理模块的 REST API 接口，提供异步操作状态查询、服务端同步轮询、异步操作取消、操作历史记录等功能。
|
||
|
||
### 基础信息
|
||
- **基础路径**: `/salesforce/metadata/async`
|
||
- **权限前缀**: `salesforce:metadata:async`
|
||
- **内容类型**: `application/json`
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. 获取异步操作状态
|
||
|
||
**功能描述**: 查询指定异步操作的当前状态，立即返回当前状态信息。
|
||
|
||
**请求方式**: GET
|
||
|
||
**请求路径**: `/salesforce/metadata/async/status/{asyncId}`
|
||
|
||
**权限要求**: `salesforce:metadata:async:query`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 位置 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| asyncId | String | 是 | Path | 异步操作 ID，Salesforce 返回的 ID，如 `0Afxx0000000001CAA` |
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码，200 表示成功 |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 异步操作结果 |
|
||
| data.id | String | 异步操作 ID |
|
||
| data.done | Boolean | 操作是否完成 |
|
||
| data.message | String | 操作消息 |
|
||
| data.state | String | 操作状态，可选值：Queued、InProgress、Completed、Failed、Canceled |
|
||
| data.checkTime | String | 状态检查时间，ISO 8601 格式 |
|
||
|
||
#### 成功示例
|
||
|
||
**请求**:
|
||
```http
|
||
GET /salesforce/metadata/async/status/0Afxx0000000001CAA
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"id": "0Afxx0000000001CAA",
|
||
"done": true,
|
||
"message": "部署成功",
|
||
"state": "Completed",
|
||
"checkTime": "2026-02-06T14:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败示例
|
||
|
||
**请求**:
|
||
```http
|
||
GET /salesforce/metadata/async/status/invalid-id
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "获取异步操作状态失败: 无效的异步操作 ID"
|
||
}
|
||
```
|
||
|
||
#### 使用场景
|
||
- 前端需要立即获取异步操作的当前状态
|
||
- 用户主动刷新状态
|
||
- 轮询前的初始状态查询
|
||
|
||
---
|
||
|
||
### 2. 同步轮询异步操作状态
|
||
|
||
**功能描述**: 服务端轮询直到异步操作完成（成功、失败或取消），最多轮询 60 次，每 5 秒一次，5 分钟超时。**注意：此接口会阻塞直到操作完成或超时。**
|
||
|
||
**请求方式**: GET
|
||
|
||
**请求路径**: `/salesforce/metadata/async/poll/{asyncId}`
|
||
|
||
**权限要求**: `salesforce:metadata:async:query`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 位置 | 默认值 | 说明 |
|
||
|--------|------|------|------|--------|------|
|
||
| asyncId | String | 是 | Path | - | 异步操作 ID |
|
||
| interval | Long | 否 | Query | 5000 | 轮询间隔（毫秒），最小 1000 |
|
||
| timeout | Long | 否 | Query | 300000 | 超时时间（毫秒），最大 600000 |
|
||
|
||
#### 响应参数
|
||
|
||
与"获取异步操作状态"接口相同。
|
||
|
||
#### 成功示例
|
||
|
||
**请求**:
|
||
```http
|
||
GET /salesforce/metadata/async/poll/0Afxx0000000001CAA?interval=5000&timeout=300000
|
||
```
|
||
|
||
**响应**（操作完成）:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"id": "0Afxx0000000001CAA",
|
||
"done": true,
|
||
"message": "部署成功",
|
||
"state": "Completed",
|
||
"checkTime": "2026-02-06T14:35:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 超时示例
|
||
|
||
**请求**:
|
||
```http
|
||
GET /salesforce/metadata/async/poll/0Afxx0000000001CAA?timeout=10000
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "同步轮询异步操作状态失败: 异步操作轮询超时，已等待 10 秒"
|
||
}
|
||
```
|
||
|
||
#### 使用场景
|
||
- 前端需要等待异步操作完成后再进行下一步操作
|
||
- 部署操作后等待部署完成
|
||
- 需要确保操作完成后再返回给用户的场景
|
||
|
||
---
|
||
|
||
### 3. 取消异步操作
|
||
|
||
**功能描述**: 尝试取消指定的异步操作。**注意：已完成的操作无法取消。**
|
||
|
||
**请求方式**: POST
|
||
|
||
**请求路径**: `/salesforce/metadata/async/cancel/{asyncId}`
|
||
|
||
**权限要求**: `salesforce:metadata:async:cancel`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 位置 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| asyncId | String | 是 | Path | 异步操作 ID |
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码，200 表示成功 |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 取消结果 |
|
||
| data.asyncId | String | 异步操作 ID |
|
||
| data.success | Boolean | 是否成功取消 |
|
||
| data.cancelTime | String | 取消操作时间，ISO 8601 格式 |
|
||
| data.message | String | 消息说明 |
|
||
|
||
#### 成功示例
|
||
|
||
**请求**:
|
||
```http
|
||
POST /salesforce/metadata/async/cancel/0Afxx0000000001CAA
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"asyncId": "0Afxx0000000001CAA",
|
||
"success": true,
|
||
"cancelTime": "2026-02-06T14:30:00",
|
||
"message": "异步操作已成功取消"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败示例
|
||
|
||
**请求**:
|
||
```http
|
||
POST /salesforce/metadata/async/cancel/0Afxx0000000001CAA
|
||
```
|
||
|
||
**响应**（操作已完成）:
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "取消异步操作失败: 操作可能已完成或无法取消"
|
||
}
|
||
```
|
||
|
||
#### 使用场景
|
||
- 用户需要取消正在进行的部署操作
|
||
- 发现操作配置错误，需要立即停止
|
||
- 系统需要自动取消超时的操作
|
||
|
||
---
|
||
|
||
### 4. 获取异步操作历史
|
||
|
||
**功能描述**: 查询最近的异步操作历史记录。
|
||
|
||
**请求方式**: GET
|
||
|
||
**请求路径**: `/salesforce/metadata/async/history`
|
||
|
||
**权限要求**: `salesforce:metadata:async:query`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 位置 | 默认值 | 说明 |
|
||
|--------|------|------|------|--------|------|
|
||
| limit | Integer | 否 | Query | 10 | 返回数量限制，最大 100 |
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码，200 表示成功 |
|
||
| msg | String | 提示信息 |
|
||
| data | Array | 异步操作历史列表 |
|
||
| data[].id | Long | 记录 ID |
|
||
| data[].asyncId | String | 异步操作 ID |
|
||
| data[].status | String | 操作状态 |
|
||
| data[].done | Boolean | 是否完成 |
|
||
| data[].message | String | 操作消息 |
|
||
| data[].errorMessage | String | 错误消息 |
|
||
| data[].createTime | String | 创建时间 |
|
||
| data[].updateTime | String | 更新时间 |
|
||
| data[].createBy | String | 创建人 |
|
||
|
||
#### 成功示例
|
||
|
||
**请求**:
|
||
```http
|
||
GET /salesforce/metadata/async/history?limit=5
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"asyncId": "0Afxx0000000001CAA",
|
||
"status": "Completed",
|
||
"done": true,
|
||
"message": "部署成功",
|
||
"errorMessage": null,
|
||
"createTime": "2026-02-06T14:00:00",
|
||
"updateTime": "2026-02-06T14:30:00",
|
||
"createBy": "admin"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"asyncId": "0Afxx0000000002CAA",
|
||
"status": "Failed",
|
||
"done": true,
|
||
"message": "部署失败",
|
||
"errorMessage": "Invalid metadata",
|
||
"createTime": "2026-02-06T13:00:00",
|
||
"updateTime": "2026-02-06T13:05:00",
|
||
"createBy": "admin"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 使用场景
|
||
- 查看最近的异步操作记录
|
||
- 审计和监控异步操作
|
||
- 排查问题
|
||
|
||
---
|
||
|
||
### 5. 根据 asyncId 查询异步操作记录
|
||
|
||
**功能描述**: 根据 Salesforce 返回的异步操作 ID 查询本地记录。
|
||
|
||
**请求方式**: GET
|
||
|
||
**请求路径**: `/salesforce/metadata/async/record/{asyncId}`
|
||
|
||
**权限要求**: `salesforce:metadata:async:query`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 位置 | 说明 |
|
||
|--------|------|------|------|------|
|
||
| asyncId | String | 是 | Path | 异步操作 ID |
|
||
|
||
#### 响应参数
|
||
|
||
与"获取异步操作历史"接口中的单条记录格式相同。
|
||
|
||
#### 成功示例
|
||
|
||
**请求**:
|
||
```http
|
||
GET /salesforce/metadata/async/record/0Afxx0000000001CAA
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"id": 1,
|
||
"asyncId": "0Afxx0000000001CAA",
|
||
"status": "Completed",
|
||
"done": true,
|
||
"message": "部署成功",
|
||
"errorMessage": null,
|
||
"createTime": "2026-02-06T14:00:00",
|
||
"updateTime": "2026-02-06T14:30:00",
|
||
"createBy": "admin"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败示例
|
||
|
||
**请求**:
|
||
```http
|
||
GET /salesforce/metadata/async/record/invalid-id
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "未找到异步操作记录: invalid-id"
|
||
}
|
||
```
|
||
|
||
#### 使用场景
|
||
- 根据 asyncId 查询特定操作的详细记录
|
||
- 查看操作的历史状态变化
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
### 业务错误码
|
||
|
||
| 错误码 | 错误信息 | 说明 |
|
||
|--------|----------|------|
|
||
| 200 | 操作成功 | 请求处理成功 |
|
||
| 500 | 操作失败 | 通用错误，具体信息见 msg 字段 |
|
||
|
||
### 异常类型
|
||
|
||
| 异常类型 | 触发条件 | HTTP 状态码 |
|
||
|----------|----------|-------------|
|
||
| SalesforceAuthException | 会话过期、未授权 | 401 |
|
||
| SalesforceOperationException | 无效的操作 ID、操作失败 | 500 |
|
||
| IllegalArgumentException | 参数校验失败 | 400 |
|
||
|
||
### 常见错误场景
|
||
|
||
| 场景 | 错误信息 | 解决方案 |
|
||
|------|----------|----------|
|
||
| 会话过期 | "Salesforce 会话已过期，请重新连接" | 重新连接 Salesforce |
|
||
| 无效的操作 ID | "无效的异步操作 ID" | 检查 asyncId 是否正确 |
|
||
| 操作已完成 | "取消异步操作失败，操作可能已完成或无法取消" | 无法取消已完成的操作 |
|
||
| 轮询超时 | "异步操作轮询超时，已等待 X 秒" | 增加超时时间或检查操作状态 |
|
||
| 轮询被中断 | "异步操作轮询被中断" | 重新发起轮询请求 |
|
||
|
||
---
|
||
|
||
## 状态说明
|
||
|
||
### 异步操作状态
|
||
|
||
| 状态 | 说明 | 是否可取消 |
|
||
|------|------|------------|
|
||
| Queued | 已排队，等待执行 | 是 |
|
||
| InProgress | 正在进行中 | 是 |
|
||
| Completed | 已完成 | 否 |
|
||
| Failed | 失败 | 否 |
|
||
| Canceled | 已取消 | 否 |
|
||
|
||
### 状态流转
|
||
|
||
```
|
||
Queued → InProgress → Completed
|
||
↓ ↓ ↓
|
||
Canceled Failed (结束)
|
||
```
|
||
|
||
---
|
||
|
||
## 使用建议
|
||
|
||
### 1. 状态查询 vs 轮询
|
||
|
||
- **状态查询**: 适用于需要立即获取当前状态的场景，不阻塞
|
||
- **轮询**: 适用于需要等待操作完成的场景，会阻塞直到完成或超时
|
||
|
||
### 2. 超时设置
|
||
|
||
- 默认超时 5 分钟（300 秒）适用于大多数部署操作
|
||
- 对于大型部署，可以适当增加超时时间
|
||
- 不建议设置过长的超时时间，以免占用过多服务器资源
|
||
|
||
### 3. 错误处理
|
||
|
||
- 对于会话过期错误，应提示用户重新连接
|
||
- 对于无效的操作 ID，应检查 ID 是否正确
|
||
- 对于超时错误，可以再次发起轮询或查询状态
|
||
|
||
### 4. 权限控制
|
||
|
||
- 查询操作需要 `salesforce:metadata:async:query` 权限
|
||
- 取消操作需要 `salesforce:metadata:async:cancel` 权限
|
||
- 建议将取消权限授予更高级别的用户
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](../requirements/sub/2026-01-28-003-04-异步操作.md)
|
||
- [设计文档](../design/2026-02-03-003-04-异步操作-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-003-04-ADR-异步操作轮询策略.md)
|
||
- [复盘文档](../retros/2026-02-06-003-04-retro.md)
|
||
- [变更日志](../changelog/2026-02-06-003-04-changelog.md)
|
||
- [会话记录](../sessions/2026-02-06-003-04-session.md)
|