第6章 基于Java的自定义流程引擎内核开发（上）

CHAPTER06基于Java的自定义流程引擎内核开发（上）流程定义解析、节点实例化与基础流转逻辑·面向开发工程师与架构师Contents课程目录基于Java的自定义流程引擎内核开发（上）01流程定义解析引擎02节点实例化与任务创建03基础流转逻辑实现04实战案例与常见问题排查CHAPTER01流程定义解析引擎将JSON流程图编译为引擎可执行的内存执行树JSONSchema流程定义JSONSchema结构规范流程定义JSONSchema是引擎解析的输入源，由元信息、节点列表、连线列表三大维度构成。每个维度都有严格的字段规范和约束条件，Schema的设计质量直接决定后续解析、实例化、流转全链路的稳定性。元信息区包含processKey（全局唯一标识）、name、version、status字段，版本号自增机制确保同一流程定义的多版本可追溯管理processKey·version节点列表每个元素含nodeId（UUID）、nodeType（6种枚举值）、nodeName、config嵌套配置，审批节点含assigneeStrategy与slaHours6种枚举值连线列表每条记录含fromNodeId、toNodeId、conditionExpr路径表达式，默认连线conditionExpr为null表示无条件流转conditionExpr声明式优先所有流转规则、审批人策略、超时配置均在JSON中声明，引擎运行时读取而非硬编码运行时读取SCHEMAEXAMPLE采购审批流程JSON定义示例以采购审批流程为例，一个完整的流程定义JSON包含5个节点和5条连线，通过conditionExpr表达式实现金额阈值驱动的差异化审批路径，充分展示Schema声明式描述复杂业务逻辑的能力。采购审批流程JSON核心字段解析字段/节点类型说明processKeyString'purchase_approval'，全局唯一标识，用于关联业务表单和接口调用node_1(开始)START绑定采购申请表单Schema，提交时自动创建流程实例node_2(部门经理)APPROVALassigneeStrategy='DEPT_MANAGER'，slaHours=4，超时自动升级node_3(条件分支)CONDITION两条出边：$.amount<50000→结束/$.amount>=50000→总监审批node_4(采购总监)APPROVALassigneeStrategy='ROLE:purchase_director'，slaHours=8node_5(结束)END配置endCallback触发ERP采购订单创建接口5个节点+5条连线完整描述采购审批从发起到终结的全路径，条件分支根据金额阈值自动选择差异化审批链路PIPELINE·PARSER流程定义解析器：JSON到内存执行树流程定义解析器采用"反序列化→校验→邻接表构建→入口定位"四步流水线，将静态JSON转化为可直接驱动流转的内存执行树结构。解析结果缓存至Redis，同一流程定义的多个实例共享同一执行树，避免重复解析开销。01反序列化Jackson反序列化JSON为ProcessDefinition对象，nodes和transitions分别映射为List<NodeDefinition>和List<Transition>，完成静态数据到领域模型的转换。ProcessDefinition02结构校验校验器检查节点ID全局唯一性、nodeType枚举合法性、连线fromNodeId/toNodeId是否引用已声明节点，异常立即抛出DefinitionException终止流程。DefinitionException03邻接表构建遍历transitions构建Map<String,List<Transition>>邻接表，key为fromNodeId，value为该节点所有出边列表，为运行时快速查找后继节点提供O(1)索引。Map邻接表04入口定位扫描nodes找到nodeType=START的节点记录为entryNodeId，缺失START节点时抛出NoEntryNodeException终止解析，确保执行树拥有唯一入口。entryNodeIdVersionManagement·CacheStrategy流程定义版本管理与缓存策略流程定义采用版本号自增+实例绑定版本的策略实现平滑升级，解析结果缓存至Redis避免重复解析开销。v+1版本号自增机制每次发布新版本时查询当前最大version并+1，已运行实例绑定创建时的definitionId，新实例始终使用最新版本。24hRedis缓存策略解析后的执行树序列化为JSON缓存至flow:def:{key}:{version}，TTL24小时，实例创建时优先缓存读取。Consistency缓存失效机制管理员修改流程定义后主动删除旧版缓存key，下次实例创建时触发重新解析并回写，确保缓存与数据库强一致。Traceability多版本共存保障flow_instance表记录definition_id指向创建时的具体版本，历史实例回溯时加载对应版本定义而非最新版本。Chapter02节点实例化与任务创建从流程实例启动到第一个待办任务生成的完整链路CoreAPI流程实例创建：startProcess核心逻辑startProcess是流程引擎的入口API，负责从执行树加载到实例持久化的全链路操作。通过businessKey将流程实例与业务数据绑定，在单一事务内完成实例创建、START节点激活和初始变量写入，确保流程启动的原子性。入口方法签名：startProcess(StringprocessKey,StringbusinessKey,Map<String,Object>variables)，返回FlowInstance对象供业务层持有01执行树加载：优先从Redis缓存读取ProcessDefinition，缓存未命中时触发解析器从flow_definition表加载JSON并回写缓存02实例持久化：INSERTflow_instance记录，status=RUNNING，start_time=当前时间戳，business_key关联业务表单ID实现流程与数据绑定03初始变量写入：将variables参数批量INSERT到flow_variable表，key-value结构存储，后续条件分支通过$.key路径表达式读取变量值04流程引擎运行所依赖的服务器基础设施环境FLOWENGINE·NODEDISPATCH节点激活调度：策略模式驱动多类型处理activateNode方法采用策略模式，根据nodeType分发到不同的NodeHandler实现类。START自动推进、APPROVAL创建待办、CONDITION计算路由、END执行回调，四种处理器覆盖基础流转全场景，新增节点类型仅需实现NodeHandler接口即可零侵入扩展。StartNodeHandler自动标记START节点为COMPLETED，立即读取邻接表获取下一条出边并递归调用activateNode推进到下一节点递归推进EndNodeHandler标记实例status=COMPLETED，执行endCallback配置的动作（触发ERP接口、发送通知），清理运行时变量缓存endCallbackApprovalNodeHandler调用审批人策略引擎解析assignee，INSERTflow_task待办记录，发送钉钉/邮件通知，启动SLA倒计时flow_taskConditionNodeHandler遍历出边列表，用flow_variable数据对conditionExpr求值，选择首个表达式为true的出边继续流转，无匹配时走default分支default分支AssigneeStrategyEngine审批人策略引擎：5种策略与兜底机制审批人策略引擎通过AssigneeStrategy接口统一5种解析策略（指定人/角色/部门主管/上级/表单字段），策略工厂根据config动态选择实现类。内置fallback兜底机制，当主策略解析为空时自动升级到上级部门，确保流程不因审批人缺失而阻塞。5种审批人策略对比策略类型解析逻辑适用场景指定人FIXED从config.userIds直接读取预设的用户ID列表固定岗位审批，如财务备案节点始终由指定财务人员处理角色ROLE查询sys_user_role表获取持有目标角色的所有用户角色级审批，如"采购总监"角色持有人审批大额采购单部门主管DEPT_MGR根据发起人dept_id查询该部门的manager_id字段直属上级审批，如请假申请由部门经理审批上级SUPERIOR沿部门树向上查找parent_id对应部门的manager_id逐级上报审批，如重大事故需厂长级别审批表单字段FORM_FIELD从flow_variable读取指定字段值作为审批人userId动态指定审批人，如采购单中"项目负责人"字段值决定审批人5种策略覆盖从静态指定到动态解析的全场景，fallback兜底机制确保流程不因人员变动或缺失而阻塞Fallback→上级部门CHAPTER03基础流转逻辑实现审批通过、驳回、撤回等核心运行时动作的代码实现TRANSACTIONPIPELINEapprove()审批通过：五步事务化流转approve方法是流程引擎调用频率最高的API，采用五步事务化流水线完成从任务状态更新到下一节点激活的全链路操作。权限校验前置、操作日志同步写入、邻接表出边读取与条件表达式求值在同一事务内完成，确保流转原子性。STEP01权限校验验证userId与flow_task.assignee匹配，不匹配时抛出UnauthorizedAccessException拒绝操作UnauthorizedSTEP02任务更新UPDATEflow_taskSETstatus='APPROVED'，记录approve_time与审批意见，标记节点完成APPROVEDSTEP03日志记录INSERTflow_log记录operator、action、nodeId与timestamp，支持进度追踪和审计flow_logSTEP04出边路由邻接表获取出边列表，单出边直接采用，多出边遍历conditionExpr求值选择目标conditionExprSTEP05递归激活调用activateNode推进流程，遇END节点标记实例COMPLETED并触发endCallbackCOMPLETEDWORKFLOWENGINE·REJECTreject()驳回：三种回退策略与审计追溯reject方法支持'驳回到上一节点/发起人/指定节点'三种回退策略，通过flow_log回溯确定目标节点。驳回后在目标节点重新创建待办任务，中间节点审批记录标记为'已失效'但保留，确保审计链条完整可追溯。三种驳回策略驳回到上一节点：从flow_log按时间倒序查找最近一个APPROVED状态的审批节点，作为回退目标驳回到发起人：定位START后的第一个APPROVAL节点，重新创建待办任务让发起人修改后重新提交驳回到指定节点：前端传入targetNodeId参数，引擎验证节点存在于已流转路径后执行回退驳回后状态处理当前待办status→REJECTED；目标节点创建新待办status=PENDING；中间节点历史记录标记valid_flag=0flow_log写入action='REJECT'记录，包含驳回原因comment，驳回后所有后续节点SLA计时器重置FlowVariableManagement流程变量管理：条件分支的数据基础设施flow_variable表以key-value结构存储流程运行时变量，是条件分支路由判断的唯一数据来源。引擎提供upsert语义的setVariable和类型安全的getVariable方法，表达式求值前自动加载全量变量构建上下文Map，并内置null安全处理防止NPE。Upsert语义setVariable先按instanceId+varKey查询，存在则UPDATE，不存在则INSERT，避免重复key导致数据混乱。该机制确保同一流程实例中变量唯一性，支持并发场景下的原子性操作。INSERT/UPDATE泛型类型转换getVariable(key,Class<T>)自动将String值转为Integer/BigDecimal/Date等目标类型。内置类型转换器支持常见Java类型，开发者可扩展自定义Converter实现复杂对象映射。Class<T>Generic批量上下文加载getVariables一次查询返回Map<String,Object>全量上下文，供条件表达式引擎一次性求值。减少数据库往返次数，提升网关路由计算性能，支持复杂嵌套条件的快速解析。Map<String,Object>Null安全策略表达式求值前对Map所有value做null检查，替换为默认值：数字→0、字符串→空串、布尔→false。防御性编程策略杜绝NPE异常，确保流程引擎稳定运行，避免运行时崩溃。NPEPreventionFLOWENGINE·LOG流程操作日志：审计追溯与进度追踪flow_log表记录流程全生命周期的每一次操作，是审计追溯、进度追踪和问题排查的唯一数据源。日志写入与状态更新在同一事务内完成，确保操作记录的完整性和一致性。前端通过日志数据渲染审批时间线，运维通过日志定位异常根因。flow_log核心字段与操作类型枚举字段类型说明instance_idBIGINT关联flow_instance，标识日志归属的流程实例node_idVARCHAR操作发生的节点ID，用于在流程图上高亮标注流转路径actionENUMAPPROVE/REJECT/WITHDRAW/TRANSFER/TIMEOUT/START/END七种操作类型operatorVARCHAR操作人userId，系统自动操作（超时/条件路由）记录为'system'commentTEXT审批意见/驳回原因/备注，前端审批弹窗中用户输入的文本timestampDATETIME操作时间戳，精确到毫秒，用于计算各节点处理耗时Summary—7种操作类型覆盖流程全生命周期，毫秒级时间戳支持节点耗时分析，operator区分人工与系统操作Chapter04实战案例与常见问题排查用制造业真实场景串联引擎内核全链路，附高频问题三步排查法APICALLCHAIN实战：采购审批流程全链路API调用以金额80000元采购审批为例，演示从startProcess到endCallback的全闭环API链路，条件分支根据amount自动路由差异化审批路径。制造业采购审批业务场景01启动流程：startProcess('purchase_approval','PO-2024001',{amount:80000,supplier:'华为'})，引擎创建实例并推进到部门经理节点02经理审批：approve(task_001,'manager_zhang','同意采购')，引擎更新状态并路由到条件分支节点03条件路由：读取amount=80000，求值$.amount≥50000为true，自动走采购总监路径，跳过低金额分支04完结回调：approve(task_002,'director_li','批准')，流程到达END，endCallback调用ERPAPI创建采购订单CASESTUDY实战：MES生产工单流转与外部系统联动MES生产工单流程展示引擎与外部系统深度集成的能力：API事件触发启动、HTTP接口调用实现物料齐套检查、流程挂起等待补料、endCallback同时触发MES状态更新和WMS领料单生成。多系统联动在单一事务+消息队列架构下保证数据最终一致性。▶流程启动与齐套检查1API事件触发：MES排产确认后调用startProcess('production_order','WO-2024001',{bom_id:'BOM-001'})启动流程，实现生产指令的数字化下发。2齐套检查节点：引擎调用ERP库存接口比对BOM物料清单，齐套率100%自动通过进入下一环节；物料不足时流程状态置为SUSPENDED挂起，等待补料通知后自动恢复执行。▶审批流转与多系统回调1并行回调机制：车间主任审批通过后，endCallback并行触发双系统更新——MES同步更新工单状态为"已审批"，WMS即时生成领料单推送至仓储终端，消除信息孤岛。2异步容错保障：外部接口调用采用消息队列异步执行配合指数退避重试机制，单次调用失败自动重试3次；全部失败时记录异常日志至监控中心并即时通知运维人员介入处理，确保业务流程的连续性与数据完整性。Troubleshooting高频问题排查速查表流程引擎开发中的常见问题可归结为定义解析、变量引用、审批人缺失、事务配置、并发控制、类型匹配六类。掌握"日志定位→数据核查→配置验证"三步排查法，可快速定位并解决80%以上的引擎开发故障。常见问题排查方向解决方案流程定义解析抛出DefinitionExceptiondefinition_json格式错误或节点ID重复、连线引用不存在的nodeId前端设计器保存前执行图完整性校验：检查孤立节点、断裂连线、ID唯一性条件分支走错路径conditionExpr中引用的变量名与flow_variable的var_key不匹配统一使用$.字段名语法，开发环境开启表达式求值日志打印中间结果审批人解析返回空列表目标角色无绑定用户、部门主管岗位空缺、表单字段值为null每种策略配置fallback兜底（如角色为空时升级到上级部门经理）状态更新但日志未写入@Transactional注解未正确配置或事务传播行为设置错误确认Service方法添加@Transactional(rollbackFor=Exception.class)并发审批导致数据不一致两个审批人同时提交，flow_task状态被重复更新approve方法入口加SELECTFORUPDATE行锁，仅首个提交成功条件表达式类型转换异常变量存储为String但表达式按数字比较（如'80000'>='50000'按字典序）setVariable时声明var_type，getVariable时按声明类型自动转换六类高频问题均可通过"日志定位→数据核查→配置验证"三步排查法快速解决，重点关注fallback兜底和并发控制SUMMARY本章核心知识点回顾本章围绕"解析→实例化→流转"主线，系统实现了自定义流程引擎的三大核心模块：JSONSchema解析器将流程定义编译为内存执行树；startProcess+activateNode完成实例创建与节点调度；approve/reject方法实现事务化流转逻辑。8张数据表、4种节点处理器、5种审批人策略构成引擎的完整技术骨架。PARSING流程定义解析JSONSchema由元信息、节点列表与连线列表三维构成，解析器按反序列化、校验、邻接表、入口定位四步流水线编译为执行树。版本管理采用自增version与实例绑定策略，解析结果缓存Redis避免重复开销，多版本共存保障历史实例可回溯。REDISCACHESCHEDULING实例化与调度