16 KiB

Raw Permalink Blame History

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. 通用响应结构

成功响应

{
  "code": 2000,
  "msg": "success message",
  "payload": {}
}

失败响应

{
  "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>

请求体

{
  "task_type": "TOPOLOGY_ANALYSIS",
  "params": { }
}

字段	类型	必填	说明
`task_type`	string	是	任务类型，枚举值见 §5.1
`params`	object	是	任务参数，不同任务类型的参数结构见 §5.3

成功响应 200

{
  "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 示例

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

{
  "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 示例

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

{
  "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 附带错误信息：

{
  "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 示例

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

{
  "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 示例

curl -X POST "http://localhost:8080/task/async/123e4567-e89b-12d3-a456-426614174000/cancel"

4.5 内部接口：更新任务进度

POST /task/internal/async/progress

由 Worker 内部调用，更新任务执行进度（0-100）。

请求体

{
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "progress": 75
}

字段	类型	必填	说明
`task_id`	string	是	任务 UUID
`progress`	int	是	进度值，范围 0-100

成功响应 200

{
  "code": 2000,
  "msg": "task progress updated successfully",
  "payload": null
}

4.6 内部接口：更新任务状态

POST /task/internal/async/status

由 Worker 内部调用，更新任务状态。当状态更新为 COMPLETED 或 FAILED 时，同步写入 finished_at 时间戳。

请求体

{
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "RUNNING",
  "timestamp": 1741846205
}

字段	类型	必填	说明
`task_id`	string	是	任务 UUID
`status`	string	是	目标状态，枚举值见 §5.2
`timestamp`	int64	是	状态变更时间戳（Unix 秒）

成功响应 200

{
  "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 — 拓扑连通性分析

分析两个元件之间是否存在连通路径。

{
  "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 — 性能分析

{
  "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 — 事件分析

{
  "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 — 批量导入

{
  "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 — 测试任务

{
  "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
相关文档: 异步任务系统设计文档

16 KiB Raw Permalink Blame History Unescape Escape

ModelRT 异步任务 API 文档

1. 概述

2. API 端点总览

3. 通用响应结构

成功响应

失败响应

响应码说明

4. 详细接口说明

4.1 创建异步任务

4.2 批量查询任务结果

4.3 查询单个任务详情

4.4 取消异步任务

4.5 内部接口：更新任务进度

4.6 内部接口：更新任务状态

5. 数据结构参考

5.1 任务类型（task_type）

5.2 任务状态（status）

5.3 各任务类型的 params 结构

TOPOLOGY_ANALYSIS — 拓扑连通性分析

PERFORMANCE_ANALYSIS — 性能分析

EVENT_ANALYSIS — 事件分析

BATCH_IMPORT — 批量导入

TEST — 测试任务

5.4 任务结果对象（AsyncTaskResult）

6. 典型调用流程

7. 队列配置参考

16 KiB

Raw Permalink Blame History