跳到主要内容

工作流API

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向使用与集成 Yudao Cloud 中 BPM（工作流）能力的开发者，提供工作流 API 的完整接口文档。内容覆盖流程实例接口、任务管理接口、流程定义接口、流程状态管理接口等核心功能，并结合 Flowable 工作流引擎的实际实现，给出流程创建、任务审批、状态流转、流程监控等接口规范与最佳实践。

项目结构​

Yudao Cloud 的 BPM 模块采用“API + 业务实现”的分层结构：

  • API 层：对外暴露 RPC 接口（Feign），定义流程实例、任务、模型等 API。
  • 控制器层：REST 控制器，提供管理后台的流程实例、任务、模型等 HTTP 接口。
  • 服务层：封装流程实例、任务、模型等业务逻辑，与 Flowable 引擎交互。
  • 枚举与 DTO：统一状态枚举、请求/响应 DTO，确保接口契约清晰。

Mermaid Diagram Code:

graph TB
subgraph "API 层"
A1["BpmProcessInstanceApi.java"]
end
subgraph "控制器层"
C1["BpmProcessInstanceController.java"]
C2["BpmTaskController.java"]
C3["BpmModelController.java"]
end
subgraph "服务层"
S1["BpmProcessInstanceService.java"]
end
subgraph "Flowable 引擎"
F1["Runtime/History/Repository APIs"]
end
A1 --> C1
A1 --> C2
A1 --> C3
C1 --> S1
C2 --> S1
C3 --> S1
S1 --> F1

图表来源

章节来源

核心组件​

  • 流程实例 API（Feign）：提供流程实例创建、查询、取消、状态消息等 RPC 接口。
  • 流程实例控制器：提供管理后台的流程实例分页、详情、取消、变量查询等 HTTP 接口。
  • 任务控制器：提供待办/已办/全部任务分页、审批/退回/委派/转派/加签/减签/抄送等任务操作。
  • 模型控制器：提供流程模型的增删改查、部署、状态变更、简单模型维护等接口。
  • 流程实例服务：封装流程实例的查询、创建、取消、变量管理、事件处理等核心逻辑。

章节来源

架构总览​

以下序列图展示“创建流程实例”的典型调用链路，从 API 到控制器再到服务层与 Flowable 引擎的交互。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant API as "BpmProcessInstanceApi"
participant Ctrl as "BpmProcessInstanceController"
participant Svc as "BpmProcessInstanceService"
participant Engine as "Flowable 引擎"
Client->>API : POST /process-instance/create<br/>携带 userId 与创建参数
API-->>Ctrl : 转发请求
Ctrl->>Svc : createProcessInstance(userId, reqDTO)
Svc->>Engine : 启动流程实例(processDefinitionKey, variables)
Engine-->>Svc : 返回实例ID
Svc-->>Ctrl : 实例ID
Ctrl-->>Client : 成功响应(实例ID)

图表来源

详细组件分析​

流程实例接口​

  • 接口目标：提供流程实例的创建、查询、取消、状态消息管理等能力。

  • 关键接口

    • 创建流程实例：POST /process-instance/create
    • 查询流程实例：POST /process-instance/get
    • 取消流程实例：POST /process-instance/cancel
    • 获取状态消息：GET /process-instance/getInstanceStatusMessage
    • 更新状态消息：POST /process-instance/updateInstanceStatusMessage

  • 请求/响应要点

    • 创建请求包含流程定义标识、业务唯一标识、流程变量、发起人自选审批人映射。
    • 查询请求支持按流程定义标识、业务标识、实例ID、状态过滤。
    • 状态消息用于流程运行时的扩展状态描述与持久化。

  • 代码片段路径

Mermaid Diagram Code:

flowchart TD
Start(["创建流程实例"]) --> Validate["校验请求参数<br/>processDefinitionKey/businessKey/variables"]
Validate --> StartEngine["启动流程实例<br/>传入 variables"]
StartEngine --> SaveBizKey["绑定业务唯一标识<br/>businessKey"]
SaveBizKey --> Assignees["处理发起人自选审批人映射"]
Assignees --> ReturnId["返回实例ID"]

图表来源

章节来源

任务管理接口​

  • 接口目标：提供任务的待办/已办/全部分页、审批/退回/委派/转派/加签/减签/抄送等操作。

  • 关键接口

    • 待办分页：GET /bpm/task/todo-page
    • 已办分页：GET /bpm/task/done-page
    • 全部任务分页：GET /bpm/task/manager-page
    • 任务列表（按实例）：GET /bpm/task/list-by-process-instance-id
    • 通过任务：PUT /bpm/task/approve
    • 不通过任务：PUT /bpm/task/reject
    • 退回任务：PUT /bpm/task/return
    • 委派任务：PUT /bpm/task/delegate
    • 转派任务：PUT /bpm/task/transfer
    • 加签任务：PUT /bpm/task/create-sign
    • 减签任务：DELETE /bpm/task/delete-sign
    • 抄送任务：PUT /bpm/task/copy
    • 子任务列表（按父任务）：GET /bpm/task/list-by-parent-task-id
    • 任务变量查询：GET /bpm/task/getVariablesByTaskId

  • 代码片段路径

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "BpmTaskController"
participant Svc as "BpmTaskService"
participant Engine as "Flowable 引擎"
Client->>Ctrl : PUT /task/approve<br/>提交审批参数
Ctrl->>Svc : approveTask(loginUserId, reqVO)
Svc->>Engine : 完成当前任务并推进流程
Engine-->>Svc : 新任务/流程结束
Svc-->>Ctrl : true
Ctrl-->>Client : 成功响应

图表来源

章节来源

流程定义接口​

  • 接口目标：提供流程模型的增删改查、部署、状态变更、简单模型维护等能力。

  • 关键接口

    • 模型列表：GET /bpm/model/list
    • 获取模型：GET /bpm/model/get
    • 新建模型：POST /bpm/model/create
    • 修改模型：PUT /bpm/model/update
    • 批量修改排序：PUT /bpm/model/update-sort-batch
    • 部署模型：POST /bpm/model/deploy
    • 修改模型状态：PUT /bpm/model/update-state
    • 删除模型：DELETE /bpm/model/delete
    • 清理模型：DELETE /bpm/model/clean
    • 获取简单模型：GET /bpm/model/simple/get
    • 保存简单模型（已废弃）：POST /bpm/model/simple/update

  • 代码片段路径

章节来源

流程状态管理接口​

  • 状态枚举：包含未开始、审批中、审批通过、审批不通过、已取消、系统错误等状态。

  • 状态判断工具：提供是否为拒绝状态、是否为流程结束状态、按状态获取枚举等工具方法。

  • 状态消息：支持获取与更新流程实例状态消息，便于业务侧扩展状态描述。

  • 代码片段路径

章节来源

依赖关系分析​

  • 模块依赖：BPM 模块由 API 与 Biz 两个子模块组成，API 提供对外 RPC 接口，Biz 提供控制器与服务实现。
  • 控制器依赖：控制器依赖服务层接口，服务层依赖 Flowable 引擎的 Runtime/History/Repository API。
  • 权限控制：控制器使用注解进行权限校验，如“bpm:process-instance:query”、“bpm:task:update”等。

Mermaid Diagram Code:

graph LR
API["BpmProcessInstanceApi.java"] --> CTRL1["BpmProcessInstanceController.java"]
API --> CTRL2["BpmTaskController.java"]
API --> CTRL3["BpmModelController.java"]
CTRL1 --> SVC["BpmProcessInstanceService.java"]
CTRL2 --> SVC
CTRL3 --> SVC
SVC --> ENGINE["Flowable 引擎"]

图表来源

章节来源

性能考量​

  • 分页查询：流程实例与任务均提供分页接口，建议前端在大数据量场景下使用分页参数，避免一次性加载过多数据。
  • 变量查询：流程变量与任务变量查询接口返回字符串化后的键值对，注意避免在高频场景下重复查询，可在前端或网关层做缓存。
  • 事件处理：流程实例的创建与完成事件处理涉及事务与引擎交互，建议在业务侧合理拆分大事务，避免长时间阻塞。
  • 权限控制：控制器使用注解进行权限校验，建议在网关层统一鉴权，减少不必要的服务调用。

故障排查指南​

  • 创建失败：检查流程定义标识是否存在、业务唯一标识是否重复、流程变量格式是否正确。
  • 任务无法审批：确认当前登录用户是否具备相应权限、任务是否仍处于运行中、是否存在加签/减签等并发状态。
  • 状态异常：通过状态消息接口核对流程实例状态消息，结合状态枚举判断是否为系统错误或流程结束状态。
  • 变量缺失：使用变量查询接口确认流程变量是否已正确设置，注意变量命名与作用域。

章节来源

结论​

本文档系统性地梳理了 Yudao Cloud BPM 模块的工作流 API，覆盖流程实例、任务管理、流程定义与状态管理等核心能力。通过明确的接口规范、调用链路与最佳实践，帮助开发者快速集成 Flowable 工作流引擎并稳定落地业务审批流程。

附录​

  • 集成要点
    • 使用 Feign 接口进行内部服务间调用，保持一致的请求/响应契约。
    • 在控制器层统一进行权限校验与参数校验，降低服务层负担。
    • 对流程变量与状态消息进行规范化管理，便于监控与审计。
  • 自定义配置
    • 可根据业务需求扩展状态枚举与状态消息字段，确保与前端展示一致。
    • 对流程变量命名与作用域进行约束，避免跨流程污染。
用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答