# 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)