540 lines
16 KiB
Markdown
540 lines
16 KiB
Markdown
# ModelRT 异步任务 API 文档
|
||
|
||
## 1. 概述
|
||
|
||
ModelRT 异步任务系统基于 RabbitMQ 消息驱动，提供完整的任务生命周期管理。任务创建后进入队列，由后台 Worker 消费并执行，调用方可通过轮询接口获取进度和结果。
|
||
|
||
**Base URL**: `http://{host}:{port}`（默认 `localhost:8080`）
|
||
|
||
**鉴权**: 公开接口需在 Header 中携带 `X-Service-Token`（由服务端启动时生成）。
|
||
|
||
---
|
||
|
||
## 2. API 端点总览
|
||
|
||
| 方法 | 路径 | 描述 | 权限 |
|
||
| :----- | :--------------------------------- | :--------------- | :----- |
|
||
| POST | `/task/async` | 创建异步任务 | 公开 |
|
||
| GET | `/task/async/results` | 批量查询任务结果 | 公开 |
|
||
| GET | `/task/async/{task_id}` | 查询单个任务详情 | 公开 |
|
||
| POST | `/task/async/{task_id}/cancel` | 取消异步任务 | 公开 |
|
||
| POST | `/task/internal/async/progress` | 更新任务进度 | 内部 |
|
||
| POST | `/task/internal/async/status` | 更新任务状态 | 内部 |
|
||
|
||
---
|
||
|
||
## 3. 通用响应结构
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 2000,
|
||
"msg": "success message",
|
||
"payload": {}
|
||
}
|
||
```
|
||
|
||
### 失败响应
|
||
|
||
```json
|
||
{
|
||
"code": 4001,
|
||
"msg": "error description",
|
||
"payload": null
|
||
}
|
||
```
|
||
|
||
### 响应码说明
|
||
|
||
| code | 含义 |
|
||
| :--- | :--------------------- |
|
||
| 2000 | 成功 |
|
||
| 3000 | 处理失败 |
|
||
| 4001 | 请求参数无效 |
|
||
| 4002 | 未授权（Token 无效） |
|
||
| 5000 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 4. 详细接口说明
|
||
|
||
### 4.1 创建异步任务
|
||
|
||
**POST** `/task/async`
|
||
|
||
创建新的异步任务，任务进入队列等待 Worker 消费。返回 `task_id` 用于后续查询。
|
||
|
||
**请求头**
|
||
|
||
```
|
||
Content-Type: application/json
|
||
X-Service-Token: <token>
|
||
```
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{
|
||
"task_type": "TOPOLOGY_ANALYSIS",
|
||
"params": { }
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| :---------- | :----- | :--- | :-------------------------------------------------------------------------------- |
|
||
| `task_type` | string | 是 | 任务类型，枚举值见 §5.1 |
|
||
| `params` | object | 是 | 任务参数，不同任务类型的参数结构见 §5.3 |
|
||
|
||
**成功响应** `200`
|
||
|
||
```json
|
||
{
|
||
"code": 2000,
|
||
"msg": "task created successfully",
|
||
"payload": {
|
||
"task_id": "123e4567-e89b-12d3-a456-426614174000"
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应**
|
||
|
||
| 场景 | code | msg |
|
||
| :----------------- | :--- | :-------------------------- |
|
||
| 参数格式错误 | 4001 | invalid request parameters |
|
||
| task_type 不合法 | 4001 | invalid task type |
|
||
| params 内容不合法 | 4001 | invalid task parameters |
|
||
| 数据库连接失败 | 5000 | database connection error |
|
||
| 任务写库失败 | 5000 | failed to create task |
|
||
|
||
**curl 示例**
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8080/task/async" \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-Service-Token: <token>" \
|
||
-d '{
|
||
"task_type": "TOPOLOGY_ANALYSIS",
|
||
"params": {
|
||
"start_component_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
||
"end_component_uuid": "550e8400-e29b-41d4-a716-446655440001",
|
||
"check_in_service": true
|
||
}
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 批量查询任务结果
|
||
|
||
**GET** `/task/async/results`
|
||
|
||
根据一组任务 ID 批量查询状态和结果，适用于轮询多个任务。
|
||
|
||
**Query 参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| :--------- | :----- | :--- | :----------------------------------- |
|
||
| `task_ids` | string | 是 | 逗号分隔的 UUID 列表，最少 1 个 |
|
||
|
||
**请求示例**
|
||
|
||
```
|
||
GET /task/async/results?task_ids=123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001
|
||
```
|
||
|
||
**成功响应** `200`
|
||
|
||
```json
|
||
{
|
||
"code": 2000,
|
||
"msg": "query completed",
|
||
"payload": {
|
||
"total": 2,
|
||
"tasks": [
|
||
{
|
||
"task_id": "123e4567-e89b-12d3-a456-426614174000",
|
||
"task_type": "TOPOLOGY_ANALYSIS",
|
||
"status": "RUNNING",
|
||
"progress": 50,
|
||
"created_at": 1741846200
|
||
},
|
||
{
|
||
"task_id": "223e4567-e89b-12d3-a456-426614174001",
|
||
"task_type": "PERFORMANCE_ANALYSIS",
|
||
"status": "COMPLETED",
|
||
"progress": 100,
|
||
"created_at": 1741846200,
|
||
"finished_at": 1741846260,
|
||
"result": {
|
||
"components_analyzed": 5
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应**
|
||
|
||
| 场景 | code | msg |
|
||
| :----------------- | :--- | :-------------------------- |
|
||
| 缺少 task_ids | 4001 | task_ids parameter is required |
|
||
| UUID 格式不合法 | 4001 | invalid task ID format |
|
||
| 数据库连接失败 | 5000 | database connection error |
|
||
| 查询失败 | 5000 | failed to query tasks |
|
||
|
||
**curl 示例**
|
||
|
||
```bash
|
||
curl "http://localhost:8080/task/async/results?task_ids=123e4567-e89b-12d3-a456-426614174000"
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 查询单个任务详情
|
||
|
||
**GET** `/task/async/{task_id}`
|
||
|
||
查询单个任务的完整信息，包含结果或错误详情。
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| :-------- | :----- | :--- | :-------------- |
|
||
| `task_id` | string | 是 | 任务 UUID |
|
||
|
||
**成功响应** `200`
|
||
|
||
```json
|
||
{
|
||
"code": 2000,
|
||
"msg": "query completed",
|
||
"payload": {
|
||
"task_id": "123e4567-e89b-12d3-a456-426614174000",
|
||
"task_type": "TOPOLOGY_ANALYSIS",
|
||
"status": "COMPLETED",
|
||
"progress": 100,
|
||
"created_at": 1741846200,
|
||
"finished_at": 1741846260,
|
||
"result": {
|
||
"path_exists": true,
|
||
"path_length": 3,
|
||
"path_nodes": ["comp-001", "comp-005", "comp-999"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
任务失败时 payload 附带错误信息：
|
||
|
||
```json
|
||
{
|
||
"code": 2000,
|
||
"msg": "query completed",
|
||
"payload": {
|
||
"task_id": "123e4567-e89b-12d3-a456-426614174000",
|
||
"task_type": "TOPOLOGY_ANALYSIS",
|
||
"status": "FAILED",
|
||
"created_at": 1741846200,
|
||
"finished_at": 1741846210,
|
||
"error_code": 400102,
|
||
"error_message": "Component UUID not found",
|
||
"error_detail": {
|
||
"component_uuid": "550e8400-0000-0000-0000-000000000000"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应**
|
||
|
||
| 场景 | code | msg |
|
||
| :----------------- | :--- | :-------------------------- |
|
||
| 缺少 task_id | 4001 | task_id parameter is required |
|
||
| UUID 格式不合法 | 4001 | invalid task ID format |
|
||
| 任务不存在 | 404 | task not found |
|
||
| 数据库连接失败 | 5000 | database connection error |
|
||
|
||
**curl 示例**
|
||
|
||
```bash
|
||
curl "http://localhost:8080/task/async/123e4567-e89b-12d3-a456-426614174000"
|
||
```
|
||
|
||
---
|
||
|
||
### 4.4 取消异步任务
|
||
|
||
**POST** `/task/async/{task_id}/cancel`
|
||
|
||
取消指定任务。**仅 `SUBMITTED`（排队中）状态的任务可以被取消**，已开始执行（`RUNNING`）或已结束的任务无法取消。
|
||
|
||
取消后任务状态变为 `FAILED`，错误码 `40003`，错误信息 `task cancelled by user`。
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| :-------- | :----- | :--- | :-------- |
|
||
| `task_id` | string | 是 | 任务 UUID |
|
||
|
||
**成功响应** `200`
|
||
|
||
```json
|
||
{
|
||
"code": 2000,
|
||
"msg": "task cancelled successfully"
|
||
}
|
||
```
|
||
|
||
**失败响应**
|
||
|
||
| 场景 | code | msg |
|
||
| :----------------------- | :--- | :--------------------------------------------------------- |
|
||
| 缺少 task_id | 400 | task_id parameter is required |
|
||
| UUID 格式不合法 | 400 | invalid task ID format |
|
||
| 任务不存在 | 404 | task not found |
|
||
| 任务已执行或已完成 | 400 | task cannot be cancelled (already running or completed) |
|
||
| 数据库连接失败 | 500 | database connection error |
|
||
| 取消操作失败 | 500 | failed to cancel task |
|
||
|
||
**curl 示例**
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8080/task/async/123e4567-e89b-12d3-a456-426614174000/cancel"
|
||
```
|
||
|
||
---
|
||
|
||
### 4.5 内部接口：更新任务进度
|
||
|
||
**POST** `/task/internal/async/progress`
|
||
|
||
由 Worker 内部调用，更新任务执行进度（0-100）。
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{
|
||
"task_id": "123e4567-e89b-12d3-a456-426614174000",
|
||
"progress": 75
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| :--------- | :----- | :--- | :---------------- |
|
||
| `task_id` | string | 是 | 任务 UUID |
|
||
| `progress` | int | 是 | 进度值，范围 0-100 |
|
||
|
||
**成功响应** `200`
|
||
|
||
```json
|
||
{
|
||
"code": 2000,
|
||
"msg": "task progress updated successfully",
|
||
"payload": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.6 内部接口：更新任务状态
|
||
|
||
**POST** `/task/internal/async/status`
|
||
|
||
由 Worker 内部调用，更新任务状态。当状态更新为 `COMPLETED` 或 `FAILED` 时，同步写入 `finished_at` 时间戳。
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{
|
||
"task_id": "123e4567-e89b-12d3-a456-426614174000",
|
||
"status": "RUNNING",
|
||
"timestamp": 1741846205
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| :---------- | :----- | :--- | :--------------------------------------- |
|
||
| `task_id` | string | 是 | 任务 UUID |
|
||
| `status` | string | 是 | 目标状态，枚举值见 §5.2 |
|
||
| `timestamp` | int64 | 是 | 状态变更时间戳（Unix 秒） |
|
||
|
||
**成功响应** `200`
|
||
|
||
```json
|
||
{
|
||
"code": 2000,
|
||
"msg": "task status updated successfully",
|
||
"payload": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 数据结构参考
|
||
|
||
### 5.1 任务类型（task_type）
|
||
|
||
| 枚举值 | 描述 |
|
||
| :--------------------- | :----------- |
|
||
| `TOPOLOGY_ANALYSIS` | 拓扑连通性分析 |
|
||
| `PERFORMANCE_ANALYSIS` | 性能分析 |
|
||
| `EVENT_ANALYSIS` | 事件分析 |
|
||
| `BATCH_IMPORT` | 批量数据导入 |
|
||
| `TEST` | 测试任务（系统验证用） |
|
||
|
||
### 5.2 任务状态（status）
|
||
|
||
| 枚举值 | 描述 | 可转换至 |
|
||
| :---------- | :----------------- | :------------------------------ |
|
||
| `SUBMITTED` | 已提交至队列 | `RUNNING`, `FAILED`（取消） |
|
||
| `RUNNING` | 正在执行 | `COMPLETED`, `FAILED` |
|
||
| `COMPLETED` | 执行成功 | — |
|
||
| `FAILED` | 执行失败或被取消 | — |
|
||
|
||
### 5.3 各任务类型的 params 结构
|
||
|
||
#### TOPOLOGY_ANALYSIS — 拓扑连通性分析
|
||
|
||
分析两个元件之间是否存在连通路径。
|
||
|
||
```json
|
||
{
|
||
"start_component_uuid": "550e8400-e29b-41d4-a716-446655440000",
|
||
"end_component_uuid": "550e8400-e29b-41d4-a716-446655440001",
|
||
"check_in_service": true
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| :--------------------- | :------ | :--- | :------------------------------------- |
|
||
| `start_component_uuid` | string | 是 | 起始元件 UUID |
|
||
| `end_component_uuid` | string | 是 | 目标元件 UUID |
|
||
| `check_in_service` | boolean | 否 | 是否只检查投运状态元件，默认 `true` |
|
||
|
||
#### PERFORMANCE_ANALYSIS — 性能分析
|
||
|
||
```json
|
||
{
|
||
"component_ids": ["comp-001", "comp-002"],
|
||
"time_range": {
|
||
"start": "2026-03-01T00:00:00Z",
|
||
"end": "2026-03-02T00:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| :--------------- | :------- | :--- | :------------------ |
|
||
| `component_ids` | []string | 是 | 待分析的元件 ID 列表（至少 1 个） |
|
||
| `time_range` | object | 否 | 分析时间范围 |
|
||
|
||
#### EVENT_ANALYSIS — 事件分析
|
||
|
||
```json
|
||
{
|
||
"event_type": "MOTOR_START",
|
||
"start_time": "2026-03-01T00:00:00Z",
|
||
"end_time": "2026-03-02T00:00:00Z",
|
||
"components": ["comp-001", "comp-002"]
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| :------------ | :------- | :--- | :------------------ |
|
||
| `event_type` | string | 是 | 事件类型 |
|
||
| `start_time` | string | 否 | 事件起始时间（RFC3339） |
|
||
| `end_time` | string | 否 | 事件截止时间（RFC3339） |
|
||
| `components` | []string | 否 | 关联的元件列表 |
|
||
|
||
#### BATCH_IMPORT — 批量导入
|
||
|
||
```json
|
||
{
|
||
"file_path": "/data/import/model.csv",
|
||
"file_type": "CSV",
|
||
"options": {
|
||
"overwrite": false,
|
||
"validate": true,
|
||
"notify_user": true
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| :--------------------- | :------ | :--- | :-------------------------------- |
|
||
| `file_path` | string | 是 | 导入文件路径 |
|
||
| `file_type` | string | 否 | 文件类型：`CSV`, `JSON`, `XML` |
|
||
| `options.overwrite` | boolean | 否 | 是否覆盖已有数据，默认 `false` |
|
||
| `options.validate` | boolean | 否 | 是否校验数据，默认 `true` |
|
||
| `options.notify_user` | boolean | 否 | 完成后是否通知用户，默认 `true` |
|
||
|
||
#### TEST — 测试任务
|
||
|
||
```json
|
||
{
|
||
"sleep_duration": 30
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| :--------------- | :--- | :--- | :---------------------------------------------- |
|
||
| `sleep_duration` | int | 否 | 模拟执行耗时（秒），默认 60，最大 3600 |
|
||
|
||
### 5.4 任务结果对象（AsyncTaskResult）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| :-------------- | :----- | :--------------------------------------------------- |
|
||
| `task_id` | string | 任务 UUID |
|
||
| `task_type` | string | 任务类型 |
|
||
| `status` | string | 当前状态 |
|
||
| `progress` | int | 进度（0-100），仅 `RUNNING` 时返回 |
|
||
| `created_at` | int64 | 创建时间戳（Unix 秒） |
|
||
| `finished_at` | int64 | 完成时间戳（Unix 秒），仅 `COMPLETED`/`FAILED` 返回 |
|
||
| `result` | object | 任务结果，仅 `COMPLETED` 时返回 |
|
||
| `error_code` | int | 错误码，仅 `FAILED` 时返回 |
|
||
| `error_message` | string | 错误描述，仅 `FAILED` 时返回 |
|
||
| `error_detail` | object | 错误详情，仅 `FAILED` 时返回 |
|
||
|
||
---
|
||
|
||
## 6. 典型调用流程
|
||
|
||
```
|
||
创建任务
|
||
└─ POST /task/async
|
||
└─ 返回 task_id
|
||
|
||
轮询状态（建议间隔 2-5 秒）
|
||
└─ GET /task/async/{task_id}
|
||
├─ status=SUBMITTED → 继续等待
|
||
├─ status=RUNNING → 查看 progress
|
||
├─ status=COMPLETED → 读取 result 字段
|
||
└─ status=FAILED → 读取 error_code / error_message
|
||
|
||
如需中止（仅 SUBMITTED 状态有效）
|
||
└─ POST /task/async/{task_id}/cancel
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 队列配置参考
|
||
|
||
| 配置项 | 值 |
|
||
| :------------- | :-------------------------- |
|
||
| Exchange | `modelrt.tasks.exchange` |
|
||
| Queue | `modelrt.tasks.queue` |
|
||
| Routing Key | `modelrt.task` |
|
||
| 优先级范围 | 0–10（默认 5） |
|
||
| 消息 TTL | 24 小时 |
|
||
| 最大重试次数 | 3 次 |
|
||
| 重试初始延迟 | 1 秒（指数退避，最大 5 分钟）|
|
||
|
||
---
|
||
|
||
**文档版本**: 1.1
|
||
**最后更新**: 2026-04-28
|
||
**相关文档**: [异步任务系统设计文档](./async_task_system.md)
|