简介：WADE开发文档面向使用WADE开发框架的Java开发者，尤其是需要从零搭建项目或进行框架版本升级改造的技术人员，系统梳理了框架的基本功能与开发步骤。文档围绕新建项目与开发改造两大主线展开：新建项目部分讲解如何借助quickstart工具生成空项目，并说明build.properties中项目名称、项目目录、WADELIB包路径、编译信息等配置项的含义；开发改造部分按WADE2.52至2.59各版本列出建议改造点，涉及JDK版本配置、输入框回车动作控制、集群缓存共享、客户端DataMap与DatasetList数据格式统一、页面命名调整等内容，便于读者对照自身版本排查兼容性问题。资源包共1个doc文件，约3.24MB，结构紧凑，适合作为日常开发查阅手册。目前已有974人学习，可供快速上手框架与版本迁移时参考。
1. 从 quickstart 到空项目：WADE 环境搭建的第一道坎
接手一个 WADE 老项目做二次开发，最怕的不是业务逻辑复杂，而是环境根本跑不起来。WADE 开发框架的工程结构依赖 Ant 构建，新建项目要靠 quickstart 提供的ant newproject生成空壳，再改build.properties里的项目名、目录路径和省份代码。很多人第一次装完直接ant all，结果编译报错、页面 404、菜单里还残留 quickstart 的示例链接，排查半天才发现是OLD_NAME和NEW_NAME三组大小写没对齐。这套环境在电信、政企类后台系统里很常见，适合需要维护 WADE 2.5x 系列老项目的开发者。装不好不会报致命错误，但会在编译、打包、部署三个环节轮流翻车，后面每改一个功能都要先跟环境搏斗。
2. 装前准备：JDK、Ant 与 wadelib 的目录约定
2.1 版本选择与依赖清单
WADE 2.59 的build.properties里明确有JDK_VERSION=1.4|1.5这个配置项，说明框架本身对 JDK 版本有硬约束。我一般会先确认两件事：应用编译用哪个 JDK，运行环境又是哪个 JDK。原文提到这个参数“可以解决 jdk1.4 的运行环境下能够部署应用”，意思是编译时用 1.5、运行时跑 1.4 也能兼容。实际落地时，开发机装 JDK 1.5，JAVA_HOME指向 1.5 目录，build.properties里写JDK_VERSION=1.5；如果目标服务器只有 1.4，就改成1.4重新编译。
Ant 用 1.6.x 或 1.7.x 都行，不要上太新的版本，老 build.xml 里的 task 定义容易不认。ant-contrib.jar是打包发布环节的必需品，ant allwar依赖它，缺了会直接报taskdef class net.sf.antcontrib... cannot be found。我习惯把它放到build/lib/下，并在build.xml里用taskdef显式引入，避免依赖 Ant 的全局 classpath。
目录结构上，原文给了一条关键约定：WADELIB_HOME = ../../../wadelib/wadelib，并且注明“一般建议 wadelib 和应用目录在同一级目录上”。我踩过的坑是把 wadelib 放到了应用目录里面，结果build_wadelib.xml的相对路径怎么算都不对。稳妥的做法是保持这样的平级结构：
workspace/ ├── wadelib/ │ ├── build/ │ │ └── build_wadelib.xml │ └── wadelib/ │ └── web/WEB-INF/lib/ └── wade-quickstart/ ├── build/ │ └── build.properties ├── etc/ ├── src/ └── web/如果 wadelib 确实没法跟应用平级，就得改build/build.xml里引入build_wadelib.xml的那行配置，把路径改成实际的相对位置，比如../../wadelib/build/build_wadelib.xml。这一步改错，编译时会在解析 wadelib 依赖的地方报文件找不到，错误信息不会直接告诉你路径写错了，只会说某个 target 的前置条件不满足，属于典型的“黑匣子”报错。
2.2 build.properties 逐项配置
拿到 quickstart 后，第一件事不是急着ant newproject，而是先把build/build.properties改对。原文给出的配置项里，最容易被忽略的是三组名称映射：
# 编译时的省代码，开发时用公用，打包部署时选择对应的省份 PROVINCE_NAME = common # 项目名称，项目打包后的 jar、war 都以这个名称为准 PROJECT_NAME = wade-quickstart # 项目目录，.. 表示当前的上级 PROJECT_HOME = .. # WADELIB 包的目录路径 WADELIB_HOME = ../../../wadelib/wadelib # build、config 等目录路径 build=${PROJECT_HOME}/build config=${PROJECT_HOME}/etc source=${PROJECT_HOME}/src classes=${PROJECT_HOME}/web/WEB-INF/classes lib=${WADELIB_HOME}/web/WEB-INF/lib web=${PROJECT_HOME}/web APPLANG=GB2312 # 新建项目需要如下配置 # 原系统的小写名称 OLD_NAME1 = quickstart # 原系统的首字母大写名称 OLD_NAME2 = Quickstart # 原系统的大写名称 OLD_NAME3 = QUICKSTART # 新系统的小写名称 NEW_NAME1 = custmgr # 新系统的首字母大写名称 NEW_NAME2 = Custmgr # 新系统的大写名称 NEW_NAME3 = CUSTMGRPROVINCE_NAME在开发阶段填common，打包部署时换成实际省份代码，这个值会影响编译时加载哪套省代码。PROJECT_NAME决定最终 war 包的名字，改完记得同步检查web.xml里的 display-name 和page.application里的应用名，三处不一致会导致部署后上下文路径对不上。
OLD_NAME1/2/3和NEW_NAME1/2/3是ant newproject做文本替换的依据。quickstart 里所有示例页面、Java 包名、配置文件都带着quickstart字样，newproject 会按这三组大小写形式批量替换成新名称。如果只改了NEW_NAME1没改NEW_NAME2，生成的项目里会出现custmgr和Quickstart混用的情况，编译能过，但页面跳转时类名对不上，运行期才报错。我一般会把三组都填满，并且保证大小写形式跟原名称严格对应。
APPLANG=GB2312是老项目的编码约定，新建项目如果目标环境用 UTF-8，这里要同步改，否则中文资源文件读出来是乱码。改编码不是只改这一处，build.xml里的javac任务、web.xml的 filter 配置都要跟着调，属于牵一发动全身的改动，没有明确要求就保持 GB2312 不动。
3. 生成空项目：ant newproject 的执行与清理
3.1 执行 newproject 并验证产物
配置改完后，在build目录下执行：
cd build ant newproject这个 target 会读取build.properties里的名称映射，在build目录下生成一个全新的空项目目录。执行完先别急着编译，检查三件事：新目录名是否等于NEW_NAME1，目录下的src里包路径是否已经替换成新名称，web/WEB-INF/classes下是否有残留的 quickstart 编译产物。常见情况是 newproject 只替换了文本，没有清理旧的 class 文件，导致新旧类混在一起，运行时报ClassNotFoundException或者加载到旧逻辑。
生成后的目录结构大致是：
build/custmgr/ ├── build/ ├── etc/ ├── src/ └── web/如果ant newproject报错说某个文件找不到，先确认 quickstart 的原始目录是否完整，尤其是web/examples/basic/下的示例页面，newproject 依赖这些文件做模板。缺文件的情况下，target 执行到一半中断，会留下一个半成品目录，这时候要把生成的目录整个删掉重来，不要在半成品上继续改。
3.2 清理 quickstart 残留配置
newproject 生成的项目里，page.application和sidebar.html还保留着 quickstart 的页面名称配置和菜单配置。原文明确要求“删除 page.application、sidebar.html 中 quickstart 保留的一些页面名称配置和菜单配置”。这一步不做，编译能过，但启动后侧边栏会多出一堆示例菜单，点进去全是 404。
page.application里搜examples.basic开头的条目，整段删掉；sidebar.html里对应的菜单项也一并清理。清理完再检查web/WEB-INF/下有没有残留的示例 jsp 或 html，有就删。我一般会保留examples/basic下的代码作为参考，但不会让它们出现在菜单配置里，避免误点。
3.3 编译与打包命令的取舍
开发阶段用ant all，这是默认 target，编译源码、拷贝资源、生成 classes，不打包。测试和发布用ant allwar，它会打出 war 包，依赖ant-contrib.jar。两个命令的区别不只是打不打包，allwar还会执行资源过滤和 war 结构整理，如果build.properties里PROVINCE_NAME填的是common，打出来的 war 是通用版，部署到具体省份前要改成对应省代码重新打。
# 开发编译 ant all # 测试打包发布，需确保 ant-contrib.jar 已就位 ant allwarant allwar报taskdef找不到时，检查ant-contrib.jar是否在build/lib/下，以及build.xml里taskdef的classpath是否指向了正确位置。另一个常见问题是 war 包打出来缺少WEB-INF/lib下的依赖，原因是WADELIB_HOME路径不对，lib变量解析到了空目录，编译能过但打包时拷不到 jar。
4. 版本改造点落地：从 2.5 到 2.59 的配置调整
4.1 JDK_VERSION 与编译目标
WADE 2.59 要求配置JDK_VERSION=1.4|1.5，这个参数直接传给javac的source和target。填1.5时编译出的 class 版本是 49，能在 1.4 的 JVM 上跑的前提是代码里没用 1.5 特有的语法。如果项目里用了泛型或枚举，运行时在 1.4 环境会报UnsupportedClassVersionError。我一般开发阶段填1.5，确认目标服务器 JDK 版本后，发布前改成对应值重新编译，不要指望一个包通吃。
4.2 输入框回车动作与 enterAction
WADE 2.56 给输入框组件加了enterAction参数，原文建议“以后对输入框回车动作的控制采用该参数来实现”。老代码里常见的是在onkeydown里判断 keyCode 然后手动提交，这种写法在不同浏览器下行为不一致，而且跟组件的内部事件容易冲突。改造时把输入框上的回车处理换成：
<input jwcid="@wade:TextField" value="ognl:info.CUST_NAME" enterAction="alert('xxx')" />enterAction的值是回车后执行的脚本，可以是提示、提交或者跳转。改造范围是所有输入框组件，包括弹出窗口、金额输入、文本输入、下拉表格。逐个页面替换工作量大，但比留着旧写法在特定浏览器上偶发失效要稳。
4.3 集群缓存与 ehcache.xml 增量合并
WADE 2.55 之前缓存不支持集群共享，2.55 起需要每个应用更新到 Quickstart 2.35 及以上版本，参照etc/common/ehcache.xml改造。原文的说法是“一般只需获取 quickstart 的 ehcache.xml 增量加上自定义的 cache 配置即可”。实际操作时，拿新版 quickstart 的ehcache.xml跟项目现有的做 diff，把新增的cache节点合并进来，保留项目自定义的 cache 配置，不要整个文件覆盖，否则自定义缓存策略会丢。
合并后重点检查cacheManagerPeerProviderFactory和cacheEventListenerFactory这两段集群相关配置是否完整，缺了会导致集群节点间缓存不同步，表现为 A 节点改了数据、B 节点读到的还是旧值。这种问题在单机测试时完全看不出来，上集群才暴露。
4.4 页面命名与 linkSubmit 替换
WADE 2.52 要求把web/Buttom.html、view/Buttom.java改成Bottom.html、Bottom.java，page.application里的配置也要同步改，否则底部页面报错。这是拼写修正带来的不兼容，升级时全局搜Buttom替换成Bottom，包括配置文件里的引用。
WADE 2.5 把linkSubmit(page,listener,params)标记为不推荐，原因是“对不同浏览器存在无法实现跳转的问题”，替代方案是@wade:PageSubmit组件。改造时把页面里的linkSubmit调用换成组件写法：
<a jwcid="@wade:PageSubmit" value="删除" listener="ognl:listeners.deleteVipcust" desc="VIP 客户资料" class="e_bLinkDelete" onclick="return queryBox(this, 'vips');" />同一版本还规范了 DOM 获取方式，要求用getElement(name)、getElements(name)、hidden(name|obj)、disabled(name|obj)，禁止直接写document.getElementById(name).disabled = true。原因是很多组件不是单一 DOM 对象，比如日期组件包含文本框和图标，直接操作只会隐藏文本框，图标还在。改造时全局搜document.getElementById，逐个替换成框架提供的方法。
5. 避坑排查：newproject 与编译环节的五个翻车现场
5.1 ant newproject 后项目名大小写混用
现象：生成的项目编译通过，但页面跳转时报类找不到，日志里出现custmgr和Quickstart两种前缀。
原因：NEW_NAME1/2/3只填了部分，或者填的大小写形式跟OLD_NAME不对应，newproject 的文本替换漏掉了某些形式。
解决：三组名称全部填满，严格按小写、首字母大写、全大写对应。改完删掉生成目录重新执行ant newproject，不要在旧产物上打补丁。
5.2 ant allwar 报 ant-contrib 找不到
现象：ant all正常，ant allwar报taskdef class net.sf.antcontrib.logic.IfTask cannot be found。
原因：ant-contrib.jar没放对位置，或者build.xml里taskdef的 classpath 没指向它。
解决：把 jar 放到build/lib/下，在build.xml顶部加taskdef声明并指定classpath。不要依赖 Ant 安装目录的 lib，换台机器就失效。
5.3 编译通过但部署后页面 404
现象：war 包部署到容器后，访问首页正常，点菜单全是 404。
原因：page.application和sidebar.html里 quickstart 的示例配置没清理干净，菜单指向了不存在的页面。
解决：全局搜examples.basic，把page.application里的页面注册和sidebar.html里的菜单项删掉，重新打包。
5.4 JDK 版本不匹配导致运行时报错
现象：编译成功，部署到 1.4 环境启动时报UnsupportedClassVersionError。
原因：JDK_VERSION填了1.5，但代码里用了 1.5 语法，或者编译时实际用的 JDK 跟配置不一致。
解决：确认JAVA_HOME指向的 JDK 版本，build.properties里JDK_VERSION跟目标运行环境对齐，发布前用目标 JDK 重新编译。
5.5 wadelib 路径不对导致打包缺依赖
现象：ant all编译正常，ant allwar打出的 war 里WEB-INF/lib是空的。
原因：WADELIB_HOME的相对路径算错了，lib变量解析到不存在的目录，拷贝任务静默跳过。
解决：按平级目录结构摆放 wadelib，或者改build.xml里build_wadelib.xml的引入路径。打包后解压 war 检查WEB-INF/lib下是否有 jar，没有就说明路径有问题。
6. 装完怎么验证：从编译产物到页面跑通的检查清单
环境装完不等于跑通，我一般按四层验证走一遍，每层都有明确的通过标准，不靠“看起来没报错”判断。
第一层，编译产物完整性。执行ant all后检查web/WEB-INF/classes下是否有新名称对应的包路径，比如custmgr/而不是quickstart/。同时确认classes下没有残留的旧 class 文件，有就手动清掉重新编译。这一层过了，说明 newproject 的文本替换和编译链路是通的。
第二层，war 包结构。执行ant allwar后解压 war，检查三处：WEB-INF/lib下是否有 wadelib 的 jar，WEB-INF/classes下包路径是否为新名称，WEB-INF/web.xml的 display-name 是否跟PROJECT_NAME一致。任何一处不对，部署后都会出问题。
第三层，启动日志。部署到容器后看启动日志，重点搜三类信息：page.application解析是否报错、ehcache 初始化是否成功、数据源连接是否正常。集群环境下还要确认缓存 peer 配置有没有生效，日志里会有 peer provider 的初始化记录。
第四层，页面功能冒烟。按新增、修改、删除、查看、批量操作、导入六条链路各走一遍。新增走PageRedirect跳转到编辑页，提交后看redirectToMsg的提示是否正常；修改重点验证save和update的取舍，部分字段更新必须用save，否则未传字段会被清空；删除验证queryBox确认框和PageSubmit提交；导入验证enctype="multipart/form-data"是否生效，失败数据能否下载。
验证时可以用一个简单的检查脚本把关键点串起来：
#!/bin/bash # 检查编译产物和 war 包结构 APP_NAME="custmgr" CLASSES_DIR="web/WEB-INF/classes" # 1. 检查包路径是否为新名称 if [ -d "$CLASSES_DIR/$APP_NAME" ]; then echo "OK: 包路径已替换为 $APP_NAME" else echo "FAIL: 包路径仍是旧名称，检查 newproject 是否执行完整" fi # 2. 检查是否有 quickstart 残留 class if find "$CLASSES_DIR" -name "*Quickstart*" | grep -q .; then echo "FAIL: 存在 quickstart 残留 class，需清理后重新编译" else echo "OK: 无残留 class" fi # 3. 检查 war 包内 lib 是否非空 WAR_FILE="build/${APP_NAME}.war" if [ -f "$WAR_FILE" ]; then LIB_COUNT=$(unzip -l "$WAR_FILE" | grep "WEB-INF/lib/.*\.jar" | wc -l) echo "war 包内 jar 数量: $LIB_COUNT" [ "$LIB_COUNT" -gt 0 ] && echo "OK: 依赖已打入" || echo "FAIL: WEB-INF/lib 为空，检查 WADELIB_HOME" fi脚本里的判断逻辑对应前面几层的检查点，跑一遍能快速定位是编译阶段还是打包阶段出的问题。APP_NAME改成实际的NEW_NAME1，CLASSES_DIR按项目结构调整。
从那以后我每次新建 WADE 项目，都强制先跑一遍这个检查脚本再进开发，宁可多花两分钟确认产物，也不在部署后对着 404 页面猜是配置问题还是代码问题。希望帮到你。
本文还有配套的精品资源，点击获取
