Java 轻量级流程引擎 Easy Work：核心原理与生产级落地

一、为什么你需要轻量级流程引擎？

在企业级开发中，审批流、工单流转、状态机管控等流程类需求无处不在。传统重量级流程引擎（Activiti、Flowable、Camunda）虽功能完备，但存在部署复杂、学习成本高、对中小微型流程场景过度设计的痛点；而自研流程引擎又极易出现扩展性差、边界处理不到位、维护成本高的问题。

Easy Work 作为一款开源轻量级 Java 流程引擎，有效解决了上述矛盾。它基于状态机模型设计，剥离了 BPMN2.0 规范中 90% 的低频复杂特性，仅保留核心的流程编排、任务管控、扩展监听能力，学习成本降低 90%，性能较传统引擎提升 3 倍以上，适用于中小微型流程场景。

二、Easy Work 核心架构与底层原理

2.1 核心架构设计

Easy Work 采用分层架构设计，高度解耦，兼容 Spring 生态，整体架构如下：

文章配图

各层核心职责：

业务应用层：对接业务系统，发起流程、处理任务、查询流程数据
核心 API 层：提供极简的统一操作入口，屏蔽底层复杂实现
核心功能模块：流程定义、实例、任务、扩展四大核心模块，覆盖全流程生命周期
持久化层：基于 MyBatis-Plus 实现数据持久化，兼容 MySQL 等主流数据库
数据存储层：MySQL 8.0+ 存储流程与业务数据，支持自动建表

2.2 底层核心原理

流程引擎的本质，是对业务状态流转的标准化管控。Easy Work 的底层核心是「流程定义 + 状态机 + 动作执行」三层模型：

流程定义层：相当于流程的「施工图纸」，是静态模板，定义了流程有哪些节点、节点间的流转规则、每个节点的执行动作、审批人、监听器等，一个流程定义可生成无数个流程实例。
状态机核心层：相当于流程的「大脑」，核心逻辑是「当前状态 + 触发动作=下一个状态」，负责校验流转合法性、触发节点执行动作、管理流程全生命周期，杜绝非法流转。
动作执行层：相当于流程的「手脚」，负责执行节点绑定的业务逻辑、审批逻辑、条件判断、监听器触发等，是流程引擎与业务系统的核心对接点。

2.3 核心概念与易混淆点明确区分

概念	核心定义	本质	易混淆点澄清
流程定义 (ProcessDefinition)	流程的静态模板，定义了流程的全链路规则	相当于 Java 中的类	流程定义修改后，已启动的流程实例不会生效，需升级版本号
流程实例 (ProcessInstance)	基于流程定义启动的具体流程，是流程的一次执行	相当于 Java 中的对象	一个流程定义可对应无数个流程实例，实例之间相互隔离
流程节点 (ProcessNode)	流程中的单个步骤，是流程的最小执行单元	相当于类中的方法	节点是静态定义，任务是节点运行时的动态实例
任务 (TaskInfo)	流程实例运行到用户任务节点时生成的待办事项	相当于方法的执行实例	只有 USER_TASK 类型节点会生成任务，其他节点自动执行
流转规则 (Transition)	节点之间的跳转规则，分为无条件流转和条件流转	相当于代码中的 if-else/跳转逻辑	排他网关必须设置默认分支，否则会出现流程卡死
节点监听器 (TaskListener)	节点事件触发时执行的自定义逻辑，支持创建/完成/取消事件	相当于切面 AOP	监听器异常会阻断流程流转，非核心逻辑需做好异常处理

三、快速搭建可运行的 Easy Work 项目

3.1 环境要求

JDK 17+
Spring Boot 3.x
MySQL 8.0+
Maven 3.8+

3.2 Maven 依赖配置

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.3</version>
        <relativePath/>
    </parent>
    <groupId>com.jam</groupId>
    <artifactId>easy-work-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>easy-work-demo</name>
    <description>Easy Work 流程引擎演示项目</description>
    <properties>
        <java.version>17
        2.2.0
        3.5.7
        2.0.52
        33.2.1-jre
        2.6.0
    
    
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            org.springframework.boot
            spring-boot-starter-jdbc
        
        
            com.william
            easy-work-spring-boot-starter
            ${easy-work.version}
        
        
            com.baomidou
            mybatis-plus-boot-starter
            ${mybatis-plus.version}
        
        
            com.mysql
            mysql-connector-j
            runtime
        
        
            org.projectlombok
            lombok
            1.18.34
            provided
        
        
            com.alibaba.fastjson2
            fastjson2
            ${fastjson2.version}
        
        
            com.google.guava
            guava
            ${guava.version}
        
        
            org.springdoc
            springdoc-openapi-starter-webmvc-ui
            ${springdoc.version}
        
        
            org.springframework.boot
            spring-boot-starter-test
            test
        
    
    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
                
                    
                        
                            org.projectlombok
                            lombok

3.3 应用配置文件 application.yml

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/easy_work_demo?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: root
  transaction:
    default-timeout: 30
mybatis-plus:
  mapper-locations: classpath*:/mapper/**/*.xml
  type-aliases-package: com.jam.demo.entity
  configuration:
    map-underscore-to-camel-case: true
    cache-enabled: false
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
easy-work:
  auto-ddl: true
  table-prefix: ew_
  async-execute: false
springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha

3.4 数据库初始化

创建数据库（MySQL 8.0+）

CREATE DATABASE IF NOT EXISTS easy_work_demo DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

业务表创建（请假申请表）

CREATE TABLE IF NOT EXISTS `t_leave_apply` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键 ID',
  `process_instance_id` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '流程实例 ID',
  `user_id` bigint NOT NULL COMMENT '申请人 ID',
  `user_name` varchar(32) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '申请人姓名',
  `dept_id` bigint NOT NULL COMMENT '部门 ID',
  `leave_type` tinyint NOT NULL COMMENT '请假类型：1-事假，2-病假，3-年假',
  `start_time` datetime NOT NULL COMMENT '请假开始时间',
  `end_time` datetime NOT NULL COMMENT '请假结束时间',
  `leave_days` decimal(10,1) NOT NULL COMMENT '请假天数',
  `leave_reason` varchar(512) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '请假原因',
  `status` tinyint NOT NULL DEFAULT '0' COMMENT '申请状态：0-草稿，1-审批中，2-已通过，3-已驳回',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` datetime NOT NULL DEFAULT     COMMENT ,
   (`id`),
  KEY `idx_process_instance_id` (`process_instance_id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_status` (`status`),
  KEY `idx_create_time` (`create_time`)
) ENGINEInnoDB  CHARSETutf8mb4 utf8mb4_unicode_ci COMMENT;

Easy Work 核心表：开启 auto-ddl: true 后，项目启动时会自动创建，无需手动执行。

3.5 项目启动类

package com.jam.demo;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@MapperScan("com.jam.demo.mapper")
public class EasyWorkDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(EasyWorkDemoApplication.class, args);
    }
}

四、完整实战示例：员工请假审批流程

4.1 流程设计

请假审批流程是企业最常用的流程场景，流程链路如下：

文章配图

4.2 流程节点枚举定义

package com.jam.demo.enums;
import lombok.Getter;

@Getter
public enum LeaveProcessNodeEnum {
    START("start", "发起请假申请"),
    MANAGER_APPROVE("manager_approve", "部门经理审批"),
    HR_RECORD("hr_record", "人事备案"),
    END("end", "流程结束");
    
    private final String nodeCode;
    private final String nodeName;
    
    LeaveProcessNodeEnum(String nodeCode, String nodeName) {
        this.nodeCode = nodeCode;
        this.nodeName = nodeName;
    }
}

4.3 流程定义配置

package com.jam.demo.config;
import com.jam.demo.enums.LeaveProcessNodeEnum;
import com.william.easywork.definition.ProcessDefinition;
import com.william.easywork.definition.ProcessNode;
import com.william.easywork.enums.NodeTypeEnum;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class LeaveProcessConfig {
    @Bean
    public ProcessDefinition leaveProcessDefinition() {
        return ProcessDefinition.builder()
                .processCode("leave_apply_process")
                .processName("员工请假审批流程")
                .version(1)
                .description("员工请假申请，部门经理审批，人事备案的标准流程")
                .startNodeCode(LeaveProcessNodeEnum.START.getNodeCode())
                .endNodeCode(LeaveProcessNodeEnum.END.getNodeCode())
                .addNode(buildStartNode())
                .addNode(buildManagerApproveNode())
                .addNode(buildHrRecordNode())
                .addNode(buildEndNode())
                .build();
    }

    private ProcessNode buildStartNode() {
        return ProcessNode.builder()
                .nodeCode(LeaveProcessNodeEnum.START.getNodeCode())
                .nodeName(LeaveProcessNodeEnum.START.getNodeName())
                .nodeType(NodeTypeEnum.START)
                .addTransition(LeaveProcessNodeEnum.MANAGER_APPROVE.getNodeCode())
                .build();
    }

    private ProcessNode buildManagerApproveNode() {
        return ProcessNode.builder()
                .nodeCode(LeaveProcessNodeEnum.MANAGER_APPROVE.getNodeCode())
                .nodeName(LeaveProcessNodeEnum.MANAGER_APPROVE.getNodeName())
                .nodeType(NodeTypeEnum.USER_TASK)
                .addTransition("pass", LeaveProcessNodeEnum.HR_RECORD.getNodeCode())
                .addTransition(, LeaveProcessNodeEnum.END.getNodeCode())
                .build();
    }

     ProcessNode  {
         ProcessNode.builder()
                .nodeCode(LeaveProcessNodeEnum.HR_RECORD.getNodeCode())
                .nodeName(LeaveProcessNodeEnum.HR_RECORD.getNodeName())
                .nodeType(NodeTypeEnum.SERVICE_TASK)
                .addTransition(LeaveProcessNodeEnum.END.getNodeCode())
                .build();
    }

     ProcessNode  {
         ProcessNode.builder()
                .nodeCode(LeaveProcessNodeEnum.END.getNodeCode())
                .nodeName(LeaveProcessNodeEnum.END.getNodeName())
                .nodeType(NodeTypeEnum.END)
                .build();
    }
}

4.4 业务实体与数据层

4.4.1 请假申请实体类

package com.jam.demo.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.io.Serializable;
import java.math.BigDecimal;
import java.time.LocalDateTime;

@Data
@TableName("t_leave_apply")
@Schema(description = "请假申请实体")
public class LeaveApply implements Serializable {
    private static final long serialVersionUID = 1L;
    
    @TableId(type = IdType.AUTO)
    @Schema(description = "主键 ID")
    private Long id;
    
    @Schema(description = "流程实例 ID")
    private String processInstanceId;
    
    @Schema(description = "申请人 ID")
    private Long userId;
    
    @Schema(description = "申请人姓名")
    private String userName;
    
    @Schema(description = "部门 ID")
    private Long deptId;
    
    @Schema(description = "请假类型：1-事假，2-病假，3-年假")
    private Integer leaveType;
    
    @Schema(description = "请假开始时间")
    private LocalDateTime startTime;
    
    @Schema(description = "请假结束时间")
    private LocalDateTime endTime;
    
    @Schema(description = "请假天数")
    private BigDecimal leaveDays;
    
    
     String leaveReason;
    
    
     Integer status;
    
    
     LocalDateTime createTime;
    
    
     LocalDateTime updateTime;
}

4.4.2 Mapper 接口

package com.jam.demo.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.jam.demo.entity.LeaveApply;
import org.apache.ibatis.annotations.Mapper;

@Mapper
public interface LeaveApplyMapper extends BaseMapper<LeaveApply> {
}

4.5 请求参数定义

4.5.1 请假申请请求参数

package com.jam.demo.req;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import lombok.Data;
import java.math.BigDecimal;
import java.time.LocalDateTime;

@Data
@Schema(description = "请假申请请求参数")
public class LeaveApplyReq {
    @Schema(description = "申请人 ID", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotNull(message = "申请人 ID 不能为空")
    private Long userId;
    
    @Schema(description = "申请人姓名", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotBlank(message = "申请人姓名不能为空")
    private String userName;
    
    @Schema(description = "部门 ID", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotNull(message = "部门 ID 不能为空")
    private Long deptId;
    
    @Schema(description = "请假类型：1-事假，2-病假，3-年假", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotNull(message = "请假类型不能为空")
    private Integer leaveType;
    
    @Schema(description = "请假开始时间", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotNull(message = "请假开始时间不能为空")
    private LocalDateTime startTime;
    
    @Schema(description = "请假结束时间", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotNull(message = "请假结束时间不能为空")
    private LocalDateTime endTime;
    
    @Schema(description = "请假天数", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotNull(message = "请假天数不能为空")
    private BigDecimal leaveDays;
    
    @Schema(description = "请假原因", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotBlank(message = "请假原因不能为空")
    private String leaveReason;
}

4.5.2 审批请求参数

package com.jam.demo.req;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import lombok.Data;

@Data
@Schema(description = "请假审批请求参数")
public class LeaveApproveReq {
    @Schema(description = "申请 ID", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotNull(message = "申请 ID 不能为空")
    private Long applyId;
    
    @Schema(description = "审批人 ID", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotNull(message = "审批人 ID 不能为空")
    private Long approveUserId;
    
    @Schema(description = "审批人姓名", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotBlank(message = "审批人姓名不能为空")
    private String approveUserName;
    
    @Schema(description = "审批结果：pass-通过，reject-驳回", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotBlank(message = "审批结果不能为空")
    private String approveResult;
    
    @Schema(description = "审批意见")
    private String approveRemark;
}

4.6 业务服务层实现

4.6.1 服务接口

package com.jam.demo.service;
import com.baomidou.mybatisplus.extension.service.IService;
import com.jam.demo.entity.LeaveApply;
import com.jam.demo.req.LeaveApplyReq;
import com.jam.demo.req.LeaveApproveReq;

public interface LeaveApplyService extends IService<LeaveApply> {
    Long submitLeaveApply(LeaveApplyReq req);
    void managerApprove(LeaveApproveReq req);
    void hrRecord(String processInstanceId);
}

4.6.2 服务实现类

package com.jam.demo.service.impl;
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.google.common.collect.Maps;
import com.jam.demo.entity.LeaveApply;
import com.jam.demo.enums.LeaveProcessNodeEnum;
import com.jam.demo.mapper.LeaveApplyMapper;
import com.jam.demo.req.LeaveApplyReq;
import com.jam.demo.req.LeaveApproveReq;
import com.jam.demo.service.LeaveApplyService;
import com.william.easywork.core.ProcessEngine;
import com.william.easywork.entity.ProcessInstance;
import com.william.easywork.entity.TaskInfo;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.transaction.TransactionStatus;
import org.springframework.transaction.support.DefaultTransactionDefinition;
import org.springframework.util.ObjectUtils;
import org.springframework.util.StringUtils;
import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.Map;

@Slf4j
@Service
public class LeaveApplyServiceImpl extends ServiceImpl<LeaveApplyMapper, LeaveApply> implements LeaveApplyService {
    private final ProcessEngine processEngine;
    private final PlatformTransactionManager transactionManager;
    private final LeaveApplyMapper leaveApplyMapper;

    public LeaveApplyServiceImpl {
        .processEngine = processEngine;
        .transactionManager = transactionManager;
        .leaveApplyMapper = leaveApplyMapper;
    }

    
     Long  {
            ();
        transactionDefinition.setTimeout();
           transactionManager.getTransaction(transactionDefinition);
         {
             (ObjectUtils.isEmpty(req)) {
                  ();
            }
             (!StringUtils.hasText(req.getUserName())) {
                  ();
            }
             (req.getLeaveDays() ==  || req.getLeaveDays().compareTo(BigDecimal.ZERO) <= ) {
                  ();
            }
                ();
            leaveApply.setUserId(req.getUserId());
            leaveApply.setUserName(req.getUserName());
            leaveApply.setDeptId(req.getDeptId());
            leaveApply.setLeaveType(req.getLeaveType());
            leaveApply.setStartTime(req.getStartTime());
            leaveApply.setEndTime(req.getEndTime());
            leaveApply.setLeaveDays(req.getLeaveDays());
            leaveApply.setLeaveReason(req.getLeaveReason());
            leaveApply.setStatus();
            leaveApply.setCreateTime(LocalDateTime.now());
            leaveApply.setUpdateTime(LocalDateTime.now());
            leaveApplyMapper.insert(leaveApply);
            Map<String, Object> variables = Maps.newHashMap();
            variables.put(, leaveApply.getId());
            variables.put(, req.getUserId());
            variables.put(, req.getUserName());
            variables.put(, req.getDeptId());
               processEngine.getRuntimeService()
                    .startProcessInstanceByCode(, variables);
            leaveApply.setProcessInstanceId(processInstance.getInstanceId());
            leaveApplyMapper.updateById(leaveApply);
            transactionManager.commit(transactionStatus);
            log.info(, leaveApply.getId(), processInstance.getInstanceId());
             leaveApply.getId();
        }  (Exception e) {
            transactionManager.rollback(transactionStatus);
            log.error(, req, e);
              ( + e.getMessage(), e);
        }
    }

    
       {
            ();
        transactionDefinition.setTimeout();
           transactionManager.getTransaction(transactionDefinition);
         {
             (ObjectUtils.isEmpty(req)) {
                  ();
            }
             (!StringUtils.hasText(req.getApproveResult())) {
                  ();
            }
             (!.equals(req.getApproveResult()) && !.equals(req.getApproveResult())) {
                  ();
            }
               leaveApplyMapper.selectById(req.getApplyId());
             (ObjectUtils.isEmpty(leaveApply)) {
                  ();
            }
             (leaveApply.getStatus() != ) {
                  ();
            }
             (!StringUtils.hasText(leaveApply.getProcessInstanceId())) {
                  ();
            }
               processEngine.getTaskService()
                    .getCurrentTaskByInstanceId(leaveApply.getProcessInstanceId());
             (ObjectUtils.isEmpty(taskInfo)) {
                  ();
            }
             (!LeaveProcessNodeEnum.MANAGER_APPROVE.getNodeCode().equals(taskInfo.getNodeCode())) {
                  ();
            }
            Map<String, Object> variables = Maps.newHashMap();
            variables.put(, req.getApproveUserId());
            variables.put(, req.getApproveUserName());
            variables.put(, req.getApproveResult());
            variables.put(, req.getApproveRemark());
            processEngine.getTaskService()
                    .completeTask(taskInfo.getTaskId(), req.getApproveResult(), variables);
             (.equals(req.getApproveResult())) {
                leaveApply.setStatus();
            }  {
                leaveApply.setStatus();
            }
            leaveApply.setUpdateTime(LocalDateTime.now());
            leaveApplyMapper.updateById(leaveApply);
            transactionManager.commit(transactionStatus);
            log.info(, req.getApplyId(), req.getApproveResult());
        }  (Exception e) {
            transactionManager.rollback(transactionStatus);
            log.error(, req, e);
              ( + e.getMessage(), e);
        }
    }

    
       {
            ();
        transactionDefinition.setTimeout();
           transactionManager.getTransaction(transactionDefinition);
         {
             (!StringUtils.hasText(processInstanceId)) {
                  ();
            }
               lambdaQuery()
                    .eq(LeaveApply::getProcessInstanceId, processInstanceId)
                    .one();
             (ObjectUtils.isEmpty(leaveApply)) {
                  ();
            }
               processEngine.getTaskService()
                    .getCurrentTaskByInstanceId(processInstanceId);
             (ObjectUtils.isEmpty(taskInfo)) {
                  ();
            }
             (!LeaveProcessNodeEnum.HR_RECORD.getNodeCode().equals(taskInfo.getNodeCode())) {
                  ();
            }
            processEngine.getTaskService().completeTask(taskInfo.getTaskId());
            leaveApply.setStatus();
            leaveApply.setUpdateTime(LocalDateTime.now());
            leaveApplyMapper.updateById(leaveApply);
            transactionManager.commit(transactionStatus);
            log.info(, processInstanceId);
        }  (Exception e) {
            transactionManager.rollback(transactionStatus);
            log.error(, processInstanceId, e);
              ( + e.getMessage(), e);
        }
    }
}

4.7 自动执行监听器（人事备案节点）

package com.jam.demo.listener;
import com.jam.demo.service.LeaveApplyService;
import com.william.easywork.annotation.NodeListener;
import com.william.easywork.enums.ListenerEventEnum;
import com.william.easywork.listener.NodeTaskListener;
import com.william.easywork.model.ListenerContext;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;

@Slf4j
@Component
@NodeListener(nodeCode = "hr_record", event = ListenerEventEnum.TASK_CREATE)
public class HrRecordTaskListener implements NodeTaskListener {
    private final LeaveApplyService leaveApplyService;

    public HrRecordTaskListener(LeaveApplyService leaveApplyService) {
        this.leaveApplyService = leaveApplyService;
    }

    @Override
    public void onEvent(ListenerContext context) {
        log.info("人事备案节点监听器触发，流程实例 ID：{}", context.getInstanceId());
        try {
            String processInstanceId = context.getInstanceId();
            if (!StringUtils.hasText(processInstanceId)) {
                log.error("流程实例 ID 为空，无法执行人事备案");
                return;
            }
            leaveApplyService.hrRecord(processInstanceId);
            log.info("人事备案自动执行完成，流程实例 ID：{}", processInstanceId);
        } catch (Exception e) {
            log.error("人事备案自动执行失败，流程实例 ID：{}", context.getInstanceId(), e);
              ( + e.getMessage(), e);
        }
    }
}

4.8 接口 Controller 层

package com.jam.demo.controller;
import com.jam.demo.req.LeaveApplyReq;
import com.jam.demo.req.LeaveApproveReq;
import com.jam.demo.service.LeaveApplyService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/leave/apply")
@Tag(name = "请假申请管理", description = "请假申请流程相关接口")
public class LeaveApplyController {
    private final LeaveApplyService leaveApplyService;

    public LeaveApplyController(LeaveApplyService leaveApplyService) {
        this.leaveApplyService = leaveApplyService;
    }

    @PostMapping("/submit")
    @Operation(summary = "发起请假申请", description = "提交请假申请并启动流程实例")
    public ResponseEntity<Long> submitLeaveApply(@Valid @RequestBody LeaveApplyReq req) {
        Long applyId = leaveApplyService.submitLeaveApply(req);
        return ResponseEntity.ok(applyId);
    }

    @PostMapping("/manager/approve")
    @Operation(summary = "部门经理审批", description = "部门经理对请假申请进行审批")
    public ResponseEntity<Void> managerApprove(@Valid @RequestBody LeaveApproveReq req) {
        leaveApplyService.managerApprove(req);
        return ResponseEntity.ok().build();
    }

    
    
     ResponseEntity<Void>  {
        leaveApplyService.hrRecord(processInstanceId);
         ResponseEntity.ok().build();
    }
}

五、生产级最佳实践

5.1 事务控制最佳实践

优先使用编程式事务：流程引擎操作与业务操作必须在同一个事务中，编程式事务可精准控制事务边界，避免声明式事务的失效场景（如非 public 方法、异常被捕获）。
事务超时控制：核心流程操作设置 30s 以内的超时时间，避免长事务占用数据库连接，影响系统性能。
事务回滚兜底：所有流程操作必须捕获异常，异常时强制回滚事务，杜绝业务数据与流程数据不一致的问题。

5.2 性能优化最佳实践

索引优化：对流程表的 process_code、instance_id、node_code、create_time 字段建立联合索引，业务表的流程实例 ID 字段必须建立索引。
缓存优化：开启 Easy Work 的流程定义缓存，避免每次启动流程实例都查询数据库；高频查询的待办任务可加入二级缓存。
异步解耦：非核心逻辑（如消息通知、日志记录、第三方接口调用）使用异步执行，避免阻塞主流程，提升接口响应速度。
历史数据归档：对已完成超过 3 个月的流程实例，定期归档到历史表，避免主表数据量过大导致查询性能下降。

5.3 分布式场景最佳实践

分布式锁控制：集群部署时，同一个流程实例的操作必须加分布式锁，避免多个节点同时操作导致数据不一致。
异步任务可靠性：异步执行的流程任务，使用消息队列（RocketMQ/Kafka）实现，避免异步任务丢失。
数据库高可用：流程引擎数据库必须使用主从复制 + 读写分离，避免单点故障导致流程系统不可用。

六、常见坑与避坑指南

流程定义修改后，已启动的流程实例不生效
- 原因：流程实例启动时会复制当前版本的流程定义数据，后续修改不会影响已启动的实例
- 避坑：修改流程定义后必须升级版本号，新启动的实例使用新版本，已启动的实例继续使用旧版本
排他网关无匹配分支，流程卡死
- 原因：条件表达式编写错误，或未设置默认分支，导致网关没有匹配到任何流转路径
- 避坑：所有排他网关必须设置默认分支，条件表达式覆盖所有可能场景，上线前必须全场景测试
监听器异常阻断流程流转
- 原因：监听器中的业务逻辑抛出未捕获的异常，导致任务完成失败，流程无法继续流转
- 避坑：非核心逻辑的异常必须捕获，不影响主流程；核心逻辑异常必须抛出，触发事务回滚，同时做好告警通知
事务失效导致数据不一致
- 原因：使用声明式事务，流程操作与业务操作不在同一个事务中，或异常被捕获未触发回滚
- 避坑：核心流程操作优先使用编程式事务，确保流程与业务操作的原子性，异常必须向上抛出

七、总结

Easy Work 作为轻量级 Java 流程引擎，以极简的设计、较低的学习成本、较强的扩展性，有效解决了中小微型流程场景的痛点。它剥离了传统流程引擎的冗余特性，保留了核心的流程编排能力，让开发者可以在短时间内完成流程的设计、开发与上线。

Java 轻量级流程引擎 Easy Work：核心原理与生产级落地

一、为什么你需要轻量级流程引擎？

二、Easy Work 核心架构与底层原理

2.1 核心架构设计

2.2 底层核心原理

2.3 核心概念与易混淆点明确区分

三、快速搭建可运行的 Easy Work 项目

3.1 环境要求

3.2 Maven 依赖配置

3.3 应用配置文件 application.yml

3.4 数据库初始化

3.5 项目启动类

四、完整实战示例：员工请假审批流程

4.1 流程设计

4.2 流程节点枚举定义

4.3 流程定义配置

4.4 业务实体与数据层

4.4.1 请假申请实体类

4.4.2 Mapper 接口

4.5 请求参数定义

4.5.1 请假申请请求参数

4.5.2 审批请求参数

4.6 业务服务层实现

4.6.1 服务接口

4.6.2 服务实现类

4.7 自动执行监听器（人事备案节点）

4.8 接口 Controller 层

五、生产级最佳实践

5.1 事务控制最佳实践

5.2 性能优化最佳实践

5.3 分布式场景最佳实践

六、常见坑与避坑指南

七、总结

更多推荐文章

相关免费在线工具

Java 轻量级流程引擎 Easy Work：核心原理与生产级落地

一、为什么你需要轻量级流程引擎？

二、Easy Work 核心架构与底层原理

2.1 核心架构设计

2.2 底层核心原理

2.3 核心概念与易混淆点明确区分

三、快速搭建可运行的 Easy Work 项目

3.1 环境要求

3.2 Maven 依赖配置

3.3 应用配置文件 application.yml

3.4 数据库初始化

3.5 项目启动类

四、完整实战示例：员工请假审批流程

4.1 流程设计

4.2 流程节点枚举定义

4.3 流程定义配置

4.4 业务实体与数据层

4.4.1 请假申请实体类

4.4.2 Mapper 接口

4.5 请求参数定义

4.5.1 请假申请请求参数

4.5.2 审批请求参数

4.6 业务服务层实现

4.6.1 服务接口

4.6.2 服务实现类

4.7 自动执行监听器（人事备案节点）

4.8 接口 Controller 层

五、生产级最佳实践

5.1 事务控制最佳实践

5.2 性能优化最佳实践

5.3 分布式场景最佳实践

六、常见坑与避坑指南

七、总结

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具