简介：WADE开发文档是一份系统介绍WADE开发框架的官方技术资料，面向使用该框架进行Java应用开发与版本升级的工程师。文档重点梳理了新建项目与开发改造两大核心功能，涵盖quickstart工具生成空项目的完整步骤、build.properties关键配置项、WADELIB包的作用与路径设置，并补充新增数据功能的页面与Java Bean写法参考，能帮助读者快速搭建新工程并理解框架基础结构。包体为单个doc格式文件，压缩包大小3.24MB，内容集中、便于按章节查阅。值得关注的是，文档按版本整理了多个建议改造点，如2.59版的JDK_VERSION配置、2.56版输入框enterAction参数、2.55版集群缓存共享的ehcache调整、2.53版客户端DataMap/DatasetList数据格式统一，以及2.52版底部页面改名等，覆盖从编译环境到页面组件的常见迁移细节，对系统升级具有很强的实操参考价值。目前已有970人学习浏览，是快速上手WADE框架与平滑升级的实用参考资料。
1. WADE开发文档不是一本 API 手册：先看懂它在讲什么
我第一次翻开 WADE 开发文档时，习惯性地去找 Controller、Service 那种通用 Web 框架的章节结构，结果翻了半天没找到入口。后来才反应过来，WADE 不是一套通用 Web 框架，而是一套以流程引擎为核心的 Java 应用开发框架：文档的主线是「先建模流程，再往节点里填业务代码」。它解决的问题很明确——审批、工单、合同流转这类状态迁移特别多的业务，如果用普通 MVC 硬写，状态判断会散落在各个 Service 里，改一次流程要动一片代码。WADE 把流程控制从业务代码里抽出来，由引擎统一驱动，业务只关心每个节点做什么。适合的人群是 Java 后端开发者，尤其是要做企业级流程类系统、却不想从零造流程引擎轮子的团队。
2. WADE 的架构主线：流程引擎、工作清单与业务节点各管什么
2.1 流程定义、活动节点与转移：文档里出现频率最高的三个词
WADE 开发文档的前几章，通常都会围绕三个词展开：流程定义（Process Definition）、活动节点（Activity）、转移（Transition）。这三个词不是概念堆砌，而是整个框架的数据模型，搞懂它们，后面读引擎 API 才不会一头雾水。
流程定义是一张有向图，描述一次业务从开始到结束要经过哪些步骤、步骤之间怎么跳，它独立于业务代码存在，一般是一个 XML 文件。活动节点是图上的一个点，代表一个可以执行的单元。节点分两类：一类是自动节点，挂一段脚本或一个 Java 动作类，引擎执行到它就自动运行；另一类是人工节点，执行到它就生成一条待办，等人处理完再继续走。转移是图上的边，定义节点之间的走向，边上可以挂条件，条件满足才走这条路，否则就拐去别的分支。
读文档时我建议记住一个顺序：先看流程定义文件的结构，再看引擎如何解释这个文件，最后才看业务代码怎么写。很多新手上来就翻引擎 API，结果不知道 API 操作的对象是什么，越看越玄学。我一般建议先自己手写一个最简单的流程定义文件，把它跑起来，再回头读 API 章节，理解会顺很多。
文档里通常会配一张流程定义元素表，类似下面的结构（字段名以你手里的文档为准，不同版本略有差异）：
| 定义元素 | 作用 | 常见属性 |
|---|---|---|
| process-definition | 流程定义根节点 | name、displayName、version |
| start-node | 流程起点 | 必须有且只有一个 |
| task-node | 人工任务节点 | actor（经办人）、form（表单标识） |
| activity-node | 自动动作节点 | type、class（动作类） |
| transition | 转移边 | to（目标节点）、condition（路由条件） |
| end-node | 流程终点 | 可以有多个 |
这张表几乎覆盖了 90% 的日常建模需求。剩下的子流程、定时器、通知节点，都是在这些基础元素上叠加出来的。遇到看不懂的章节，先回来看这张表，判断这个新元素挂在哪个基础元素下面，读起来会快很多。
2.2 流程实例与数据上下文：运行时的状态和数据怎么管理
流程定义是「图纸」，流程实例（Process Instance）是「按图纸造出来的那台机器」。每次发起一次业务，引擎就创建一个流程实例，实例会记录当前走到哪个节点、经过哪些转移、状态是运行中还是已结束。一个流程定义可以同时有成千上万个实例在跑，实例之间互不影响，这也是 WADE 能支撑高并发流程业务的根基。
实例和业务数据之间的桥梁叫数据上下文（Context）。WADE 的上下文是一组 key-value 数据，挂在实例上，流程每走一个节点，节点动作可以读它、改它，下一个节点拿到的就是修改后的值。这样设计的好处是，业务数据随流程流动，不需要每个节点都去数据库重新查一遍。
上下文的设计是最容易被忽视的部分。我的经验是：上下文里放的是「流程决策需要的数据」和「节点间传递的中间结果」，不是数据库表的全量拷贝。比如请假流程，上下文里放请假人、请假天数、审批结论就够了，请假表单的完整明细应该通过业务主键去业务表查。把整个表单对象塞进上下文的做法，短期能跑，后期流程一复杂就会出现数据膨胀和一致性问题。
WADE 的引擎在节点进入时通常会保存一份上下文快照，这个快照是排查问题的利器。流程走偏了，翻快照能看到当时上下文里到底有哪些值，不用靠猜。开发文档里一般会写清楚快照的存储位置和保留策略，我建议保留时间别设太短，至少留一个月，线上出问题才有后悔药吃。
2.3 工作清单（Worklist）机制：人工任务的派发与经办闭环
人工任务在 WADE 里不是「数据库里的一张待办表」这么简单，它有完整的生命周期。流程执行到一个人工节点时，引擎会生成一个工作项（Work Item），指派给指定的人或角色，同时进入待办清单（Worklist）。经办人打开待办、填写表单、提交后，引擎把结果写回上下文，然后评估转移条件，决定流程下一步往哪走。
工作清单的查询通常是独立接口，和流程引擎主链路分开。以典型接口设计为例：
// 查询当前用户可处理的待办 WorklistQuery query = new WorklistQuery(); query.setAssignee("u_1001"); // 经办人用户ID query.setStates(WorklistState.READY); // 只查待处理状态 List<WorkItem> workItems = worklistService.query(query); for (WorkItem item : workItems) { System.out.println(item.getProcessName()); // 流程名 System.out.println(item.getNodeName()); // 当前节点名 System.out.println(item.getCreateTime()); // 到达时间 }这段代码的逻辑是：先构造查询条件，限定经办人和状态，然后调用工作清单服务查询。注意工作清单查询是只读操作，不会修改流程状态；真正改变状态的是「领取」和「办结」两个动作，领取会给工作项加锁，办结会把处理结果写回上下文并触发转移评估。把查询和处理分开，是为了避免前端轮询待办时误触流程推进。
参数说明：setAssignee 传的是用户唯一标识，不是用户名；setStates 可以同时传多个状态，常见有 READY（待处理）和 RUNNING（正在处理）。如果你的文档版本里有分类和优先级字段，建议在查询条件里带上，待办列表的排序和分组在数据量大时有明显区别。生产环境里我见过有人把待办查询写成全表扫描，三个月后列表接口响应从 200ms 涨到 3 秒，加索引加条件才好起来。
3. 照着 WADE 开发文档搭工程：目录结构、流程定义与最小可跑流程
3.1 工程骨架与流程定义文件的放置规则
WADE 项目本身是 Java 工程，常见构建方式是 Maven 或 Gradle。开发文档里通常会给一个推荐目录结构，我按最常见的做法整理如下：
src/main/java 业务动作类、服务类 src/main/resources ├── wade.xml 引擎全局配置 └── processes/ 流程定义文件目录 └── leave_approve.xml流程定义文件建议单独放一个目录，不要和普通配置文件混在一起。引擎启动时会扫描这个目录，解析所有流程定义，注册到流程库中。文件命名和流程定义的 name 属性最好保持一致，比如文件叫 leave_approve.xml，流程名也叫 leave_approve，排查问题时能少一层对应关系，线上定位实例属于哪个流程一眼就能看出来。
这里有一个容易踩的坑：流程定义文件修改后，要不要重启应用。多数 WADE 版本在开发模式下支持热加载，但生产环境默认关闭。开发文档里一般会有对应的开关配置，开发时打开、上线前务必关掉，否则线上改一个文件整个流程库都会重新加载，正在跑的实例被重新解析，轻则日志刷屏，重则流程状态错乱。
引擎全局配置 wade.xml 里通常要确认几个关键项：流程定义扫描路径、上下文持久化方式、异步执行线程池大小。我刚接触时只改扫描路径，其他都默认，结果压测时发现节点动作执行慢，看监控才知道异步线程池只有 4 个线程，全堵在排队上。这个参数在文档里不起眼，但一定要根据业务量评估。
3.2 写一个最小流程定义：节点、路由与自动动作
以一个简单的「加班申请自动校验」流程为例，流程只有三个环节：开始、校验、结束。校验节点用自动动作实现，判断加班时长是否超限，然后通过路由条件走不同分支。
<process-definition name="overtime_check" displayName="加班申请校验" version="1.0"> <start-node name="start"> <transition to="validate" /> </start-node> <activity-node name="validate" type="java" class="com.example.overtime.ValidateAction"> <transition to="pass"> <condition lang="groovy">ctx.valid == true</condition> </transition> <transition to="reject"> <condition lang="groovy">ctx.valid == false</condition> </transition> </activity-node> <end-node name="pass" /> <end-node name="reject" /> </process-definition>这个定义的核心逻辑：流程从 start 进入 validate 节点，validate 节点挂了一个 Java 动作类 ValidateAction，执行完后上下文里会有一个 valid 值。之后两条转移分别带条件，ctx.valid 为 true 走 pass，为 false 走 reject。注意 condition 里的脚本表达式用的是上下文里的值，这是 WADE 路由的标准写法，不要试图在条件里访问数据库或外部服务。
参数说明：activity-node 的 class 属性必须是全限定类名，并且类要实现文档里规定的动作接口；type="java" 表示走 Java 动作，有的版本还支持 type="script" 直接写脚本；condition 的 lang 属性声明表达式语言，大部分版本用 groovy，也支持 EL。两个 end-node 表示两个不同的结束分支，业务上可以借此区分「通过」和「拒绝」两种结果，后续统计时直接按结束节点归类即可。
流程定义写完后，启动应用前可以先做一次语法校验。多数版本支持命令行或启动时校验，校验失败会直接提示第几行有问题。我习惯把流程定义文件当代码一样 review，重点看三个点：每个节点是不是都有出口、条件分支是否覆盖全、end-node 是否能从任意路径到达。漏一个分支，流程跑到那里就断了。
3.3 启动流程实例：引擎 API 入口与参数约定
流程定义写好后，业务侧通过引擎 API 发起流程。以典型接口设计为例：
// 组装初始上下文 Map<String, Object> initData = new HashMap<>(); initData.put("overtimeHours", 10.5); initData.put("applicant", "u_1001"); // 创建并启动流程实例 ProcessInstance instance = engine.createProcessInstance("overtime_check", "BIZ-2024-1021"); instance.start(initData, "u_1001");这段代码做了两件事：第一，准备初始上下文，把流程决策需要的字段放进去；第二，创建流程实例并启动。createProcessInstance 的第二个参数是业务主键，用来把流程实例和业务记录关联起来，这个主键必须唯一，重复会报错。start 方法的两个参数分别是初始上下文和发起人。
这里要说一下参数设计的原则。发起人和业务主键是两个容易被忽略但很重要的参数。发起人决定后续人工节点默认的归属参考，业务主键则是流程实例与业务表对账的钥匙。我见过不少项目把业务主键省略，结果流程实例和数据表对不上，排查问题全靠人工翻日志，非常被动。建议从第一天就养成传业务主键的习惯，后面所有流程维度的查询、统计、对账都依赖它。
启动流程时还可能遇到一个常见错误：流程定义不存在。引擎加载流程定义有延迟，如果应用刚启动就立刻发起流程，可能触发「流程未定义」的异常。我在开发环境遇到时，先确认 processes 目录下的文件是否被扫描到，再看引擎日志里的流程注册信息。运行一段时间后就没这个问题了，但测试脚本里首次调用前最好加一个等待或预热的步骤。
注意：启动流程是个重量级操作，会解析流程定义、创建实例、执行首节点、持久化上下文。不要把它放在前端请求的主链路上不加任何保护，务必做幂等控制，同一业务主键重复提交要直接拦截。
4. 把真实业务写进 WADE 节点：动作类、人工审批与上下文传参
4.1 节点动作类的实现与注册：业务动作的落地姿势
自动节点挂的 Java 动作类，是 WADE 里业务代码最集中的地方。一个动作类实现一个动作，做完一件事，把结果写回上下文。以加班校验动作为例：
public class ValidateAction implements NodeAction { @Override public void execute(ActionContext ctx) { // 从上下文中读取业务数据 double hours = (Double) ctx.getData("overtimeHours"); String applicant = (String) ctx.getData("applicant"); // 调用业务服务完成校验 boolean valid = overtimeService.check(applicant, hours); // 把结果写回上下文，供路由条件使用 ctx.setData("valid", valid); } }这个类的写法要点：execute 方法里不直接操作数据库表，而是调业务服务；输入输出都通过 ActionContext 传递。这样做的原因是动作类由引擎的线程池调度，执行时机、事务边界都由引擎控制，业务代码如果自行管理事务，会和引擎的事务嵌套产生冲突，数据一致性反而更难保证。
参数说明：ActionContext 的 getData 返回的是 Object，需要自行转型，所以上下文里的数据类型要从一开始就约定好，否则节点多了之后转型异常会频繁出现。setData 写回的值会被引擎持久化到流程实例的数据存储中，供后续节点和路由条件读取。
动作类在流程定义里通过 class 属性注册，引擎运行时按需实例化。注意一个动作类可能被多个流程复用，所以类里不要定义有状态的成员变量，所有数据都走上下文。这个约束是 WADE 开发和普通业务开发最大的差异之一，写惯了带成员变量的 Service 的人，来这里最容易翻车。我见过有人把计数器、缓存 Map 定义成动作类的成员变量，多实例并发跑起来数据互相串，查了一个下午才定位到。
4.2 人工审批节点：经办人指派与待办回写
自动节点跑完之后，流程往往需要人参与。人工节点在流程定义里用 task-node 声明：
<task-node name="manager_approve" actor="u_1001,role_dept_manager" form="approve_form"> <transition to="end"> <condition lang="groovy">ctx.approved != null</condition> </transition> </task-node>actor 属性的含义是指定经办人，可以写具体用户，也可以写角色，多个值用逗号分隔。引擎执行到这个节点时，会为每个经办人生成一条待办。form 属性表示待办页面绑定的表单标识，前端根据这个标识渲染表单。这里要注意：一个节点多个经办人，是「所有人都要处理」还是「一个人处理就行」，取决于文档里对 task-node 并发策略的定义，两种模式都有，上生产前必须确认清楚，否则该会签的流程变成或签，或者反过来。
人工节点最常见的需求是动态指定经办人，比如按申请人的部门找经理。actor 属性支持上下文表达式：
<task-node name="manager_approve" actor="${deptManagerId}" form="approve_form">deptManagerId 是上下文里的值，在进入这个节点前由上游动作计算好。这样就把「找谁审批」的逻辑从流程定义里解耦出去，换一个审批人不需要改流程定义，只改上游计算逻辑。这个用法在文档里叫动态 actor，是人工节点用得最多的特性，建议所有带部门流转的流程都按这个方式建模。
待办的回写是另一个关键点。经办人提交表单后，前端调用工作项办结接口，把审批意见写入上下文：
WorkItem item = worklistService.claim(taskId, "u_2001"); Map<String, Object> result = new HashMap<>(); result.put("approved", true); result.put("comment", "同意"); worklistService.complete(item, result);这段代码展示了两个动作：claim（领取）和 complete（办结）。claim 把工作项锁给当前用户，防止多人同时处理同一待办；complete 把 result 写回上下文并触发转移评估。注意 claim 之后如果长时间不 complete，工作项会一直停在 RUNNING 状态，通常需要配合超时释放机制，否则一个人挂起，整个流程就卡死。我在项目里统一加了 15 分钟未提交自动释放的兜底，处理完超时待办还要给用户提示，这个机制上线前就要设计好。
4.3 上下文传参的三个原则：哪些数据该放流程里
上下文是 WADE 里的高频数据通路，也是出问题最多的地方。我总结三条原则，照着做能少踩一半的坑：
第一，只放决策需要的数据。路由条件和后续动作需要什么，就放什么。完整的业务明细放业务表，通过业务主键回查。上下文不是缓存，放得越多，持久化开销越大，排查时视野越杂。第二，保持可序列化。上下文的存储介质决定了它必须能序列化，放了不可序列化的对象，流程实例在持久化或迁移时直接报错。第三，明确数据归属，避免同名覆盖。不同节点往上下文写同一个 key，后写的覆盖先写的，排查起来非常耗时。建议命名带前缀，比如 applyHours、leadApprove、hrApprove，一眼能看出是谁写的。
上下文里最常见的误用是放「大对象」和「临时资源」。有人把数据库连接、文件句柄、甚至会话对象放进上下文，理由是「后续节点要用」。这类对象要么不能序列化，要么生命周期和流程不一致，早晚出问题。正确的做法是动作类里自行创建和释放资源，上下文只留资源标识，比如文件的存储路径、任务 ID 号。
提示：上下文快照是排查流程问题的第一手材料，但要注意快照里可能包含敏感数据。审批类流程的上下文里如果放了身份证号、金额这类信息，快照的存储和日志打印要做脱敏，权限也要收住，否则等于是把敏感数据明文摆在库里。
5. WADE 开发避坑指南：五个高频翻车现场与排查路径
5.1 节点动作抛异常，流程实例卡在中间态
现象：自动节点执行到一半报错，流程实例既不结束也不回退，查状态是 RUNNING，但日志里已经打出一堆异常堆栈。后续节点永远等不到触发，业务数据停在半路上。
原因：动作类的异常没有被框架捕获，事务回滚了，但流程实例的节点指针没有回退到一个可恢复的位置。部分版本里实例会进入一个等待状态，需要人工干预才能继续，而大多数人不会注意到这个状态。
解决：在动作类里做异常兜底，业务异常和系统异常分开处理。业务异常（比如校验不通过）不要抛出，而是把结论写进上下文走分支；系统异常（比如数据库故障）才允许抛出，并配置引擎的错误处理策略。我一般还会给动作类的 execute 加一层 try-catch，把异常信息写进上下文的 error 字段，同时让实例走到一个失败节点，而不是卡在半路。这样流程至少可以正常结束，事后通过上下文里的 error 字段定位问题。
5.2 上下文塞了不可序列化对象，流程实例持久化失败
现象：流程跑得好好的，某次重启应用后，部分实例的上下文数据读不出来，甚至引擎启动时加载历史实例直接报错。
原因：上下文里的对象不可序列化。开发时不重启不迁移，问题不暴露；一旦实例要被持久化、清理或迁移，序列化失败导致数据丢失。最常见的就是把各种工具类实例、连接对象放进上下文，图一时方便。
解决：给上下文数据做一层约束，只允许放入基础类型、DTO 和可序列化对象。可以在动作类的基类里加一个校验方法，setData 之前检查对象是否实现 Serializable。上线前跑一轮全流程演练，把流程从开始走到结束，再重启应用验证上下文恢复，这一步能提前暴露绝大多数序列化问题。
5.3 路由条件里的「假」值被当成「真」值
现象：路由条件写 ctx.approved == false 或 ctx.valid == true，结果流程走了完全相反的分支。查上下文值确实是对的，条件就是判断错，看起来很玄学。
原因：类型不一致。上下文里存的是字符串 "false"，条件表达式里比的是布尔 false；脚本语言在宽松模式下会把非空字符串当 truthy，有值就判真。还有一种是空值问题，ctx.approved 是 null 时，== false 不成立，条件判断结果和预期完全相反。
解决：路由条件不要依赖隐式转换，显式写类型判断。推荐写法是 ctx.approved != null && ctx.approved.asBoolean() == false。更稳妥的做法是在写上下文时就统一类型，布尔值一律用 Boolean，不要用字符串表示。上线前把每个路由条件都过一遍，专门找「值可能为 null、可能为字符串、可能为布尔」的地方补判断。
5.4 并发发起流程，业务主键重复导致数据错乱
现象：压测或月初集中发起业务时，日志频繁报主键冲突，部分流程实例创建失败，已创建的实例数据还出现串号。
原因：业务主键的生成逻辑用了「时间戳 + 随机数」或「查表取最大值自增」，并发下生成重复值，而主键字段有唯一约束，冲突直接抛异常。有的项目为了省事，让前端传主键，结果前端生成的重复率更高。
解决：业务主键改用数据库序列或分布式 ID 生成器，保证全局唯一。发起流程前先校验主键不存在，发起失败时捕获异常并返回可重试的提示，不要静默吞掉。生产环境建议在流程实例表上对业务主键建唯一索引，作为最后一道防线。这个索引平时没用，但出问题的时候能挡住最坏的情况。
5.5 待办办结后审批记录查不到
现象：经办人提交审批后，待办列表里消失，但后续要查「谁在什么时间审批过」时，记录查不到，或者审批意见丢失。
原因：工作项办结时只回写了上下文，没有同步写业务侧自己的审批流水表。流程引擎的工作项在实例结束后可能被清理或归档，查询接口默认只提供运行中的工作项，历史数据需要单独查历史表。很多团队以为流程引擎记得住所有历史，实际上它主要保证运行态的一致性，不是审计系统。
解决：在办结动作里同步写业务审批流水表，记录经办人、审批时间、审批意见。把流程引擎当作调度器，不要把它当业务数据库。需要历史审计的业务，数据必须在业务侧落一份。我在项目里定的规矩是：任何人工节点的处理结果，除了写回上下文，必须同步写一张业务自己的审批记录表，流程实例删了也不怕。
6. 从跑通到上线：WADE 流程的验证方法、日志排查与性能兜底
一个流程从跑通到上线，中间还有三件事要补：验证正确性、排查效率和兜底性能。
先说验证。我一般会给每个流程定义写一个「流程模拟测试」，用脚本直接调引擎 API，构造多组上下文数据，断言走到哪个结束节点。路由条件的每个分支都要覆盖到，尤其是异常分支，别只测顺利的路径。
# 用脚本模拟流程：构造上下文、启动实例、推进到结束、断言结果 java -cp wade-test.jar com.example.FlowSimulator overtime_check applyHours=8 expect=pass java -cp wade-test.jar com.example.FlowSimulator overtime_check applyHours=20 expect=reject逻辑说明：每组参数对应一条路由分支，expect 是期望的结束节点。断言失败说明流程定义或动作类写得不对。这个方法能覆盖大部分路由逻辑，比手工点页面快得多，而且每次改完流程定义都能回归一遍。
日志排查方面，我会把引擎核心包的日志级别调到 DEBUG，重点关注三行日志：实例创建、节点进入、转移评估。实例创建日志能看到初始上下文；节点进入日志能看到当前节点的输入数据；转移评估日志能看到条件表达式的计算值。这三行串起来，就能定位流程走偏的位置。上线前记得调回 INFO，DEBUG 日志在生产环境会刷爆磁盘。
性能兜底上，流程实例表和上下文表会持续增长，三个月不清理就会拖慢引擎查询。常见做法是：给常用查询字段建联合索引，比如流程名、状态、创建时间；定期把已结束的实例归档到历史表，运行中的实例保留在热表。归档逻辑不要自己写任务硬删数据，用引擎自带的归档接口更稳妥，直接删表数据很容易把关联上下文也删了。
说到最后，我的习惯是：每上线一条流程，先在测试环境完整跑一遍，再重启一次应用验证上下文恢复，最后才放生产。这个习惯帮我挡掉了不少线上事故。WADE 这套框架适合流程密集的业务，但它的灵活性也意味着约束必须由项目自己立起来——上下文怎么传、异常怎么兜、数据怎么落，都是动手之前就该定好的规矩。希望帮到你。
本文还有配套的精品资源，点击获取
