WADE开发文档实战：quickstart骨架、增删改查与批量导入

简介：WADE开发文档面向需要基于WADE框架进行企业级Java应用开发与维护的技术人员，重点解决项目初始化、构建配置及框架版本升级后的兼容改造问题。整份资料为1个doc文档，压缩包约3.24MB，篇幅集中、查阅方便，适合作为日常开发时的案头参考。文档围绕quickstart生成空项目、build.properties中项目名称与WADELIB路径等参数配置、ant编译打包流程展开，并逐版本梳理2.52至2.59的建议改造点，涉及输入框回车控制、集群缓存共享、DataMap与DatasetList数据格式统一、页面命名调整等内容；新增数据部分还给出HTML表单、页面Java事件与Java Bean方法的编写步骤及代码片段。已有973人学习，可帮助开发者快速理解框架约定、减少升级迁移中的踩坑。

1. 拿到 WADE 开发文档的第一晚：它到底在解决什么问题

我第一次碰这套东西，是接手一个没人说得清边界的后台系统：页面里写的是<a jwcid="@wade:PageRedirect">，Java 方法第一行永远是PageData pd = getPageData();，查一条记录不写 SQL 而是dao.queryByPK("TF_F_CUST_VIP", data)。项目里没有 Spring 的@Service，没有 MyBatis 的 mapper.xml，编译入口藏在 build 目录的 Ant 脚本里，翻遍代码也找不到请求从哪进来。这种时候，一份把「框架怎么搭、页面怎么写、数据怎么落库」讲透的 WADE 开发文档，比任何通用教程都值钱。它面向的不是从零学 Java 的人，而是要在一个现成框架里加表、加页面、加批量导入功能的开发。下面按我拆这套东西的真实顺序走：先骨架，再主链路，然后批量与导入导出，最后落到版本改造和二次开发。

2. 工程骨架：quickstart、wadelib 与 Ant 三件套怎么咬合

WADE 这套框架的工程不是一个 Maven 项目，而是一份叫 quickstart 的样板工程加一个独立发布的框架包 wadelib。新项目不是从零建，而是把 quickstart 复制一份、批量改名，然后把不再需要的示例页面剔掉。理解这一点，后面所有的目录、配置、编译命令才有落脚点。

2.1 目录结构与三份核心文件

quickstart 解压后的顶层目录很固定，横向铺开，没有src/main/java那种层级：

真正决定编译走向的是build/build.properties。这份文件是纯文本键值对，改了立刻生效，不需要任何重新生成：

# 编译时的省代码，开发时用 common，打包部署时选择对应的省份 PROVINCE_NAME = common # 项目名称，打包后的 jar / war 都以这个名称为准 PROJECT_NAME = wade-quickstart # 项目目录，.. 表示 build 目录的上一级 PROJECT_HOME = .. # WADELIB 框架包的目录路径 WADELIB_HOME = ../../../wadelib/wadelib # 各类路径的推导，后面的脚本全部引用这些变量 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

参数说明按重要性排：PROVINCE_NAME控制编译时打进包里的省代码，开发期统一用common，出包时按省份切；PROJECT_NAME决定最终 war 包名，也让脚本知道要去哪个目录找资源；PROJECT_HOME用..表示相对 build 目录的上一级，意味着所有 Ant 命令必须在build/下执行，换个目录跑就会路径错乱；WADELIB_HOME指向框架包内部的wadelib子目录，注意它是两层同名目录——外面的wadelib是发布包，里面的wadelib才是真正的框架根，写路径时少写一层就找不到build_wadelib.xml；APPLANG = GB2312是老项目的默认编码，页面里出现中文乱码先回来查这一行。

2.2 用 ant newproject 复制出一个干净的新工程

新建项目不是手动复制文件夹，quickstart 自带一个newproject目标做整目录复制加批量改名。它依赖的正是build.properties里那六个别名：

# 原系统的小写名称 OLD_NAME1 = quickstart # 原系统的首字母大写名称 OLD_NAME2 = Quickstart # 原系统的大写名称 OLD_NAME3 = QUICKSTART # 新系统的小写名称 NEW_NAME1 = custmgr # 新系统的首字母大写名称 NEW_NAME2 = Custmgr # 新系统的大写名称 NEW_NAME3 = CUSTMGR

为什么要分三种大小写？这是这套框架的命名约定决定的：全小写对应包名和目录路径（examples.basic.VipcustEdit这一层）、首字母大写对应 Java 类名前缀和页面注册名、全大写对应常量与资源键。常见的做法是newproject内部用 Ant 的copy加replace任务，把待生成目录里的文本文件全部扫一遍，按这三组做字符串替换。所以替换是字面级的、不分词的——如果你把NEW_NAME1起成list，那么源码里所有出现quickstart的地方都会变成list，包括某些不该改的地方。血泪经验是别名起得越独特越好，别用app、main、test这类满大街都是的短词。

实际执行只有四步，但第四步之后必须手工清一遍：

cd build # 1. 先把 build.properties 里的 OLD_NAME* / NEW_NAME* 改成你的项目名 # 2. 生成新项目骨架，编译产物落到 build 目录下 ant newproject # 3. 手工删掉 page.application 与 sidebar.html 里 quickstart 保留的页面注册和菜单项 # 这两处是配置文本，newproject 只替换名称，不会删除条目 # 4. 编译验证 ant all

第三步是最容易被跳过的一步。etc/page.application里登记的是「哪个页面路径对应哪个 Page 类」，sidebar.html里是左侧菜单项。骨架复制过来时这两份配置原样保留，只把名字换掉了，结果就是新项目启动后菜单里挂着一堆指向不存在页面的入口，点进去直接 500。判断方法很简单：新项目首次跑起来，先点一遍每个菜单，报错的那个就去这两份文件里搜名字删掉。

2.3 WADELIB_HOME 与 build.xml 的引入路径

build/build.xml本身很短，主体逻辑全部来自框架包里的build_wadelib.xml，靠一行 import 挂进来：

<!-- 推荐写法一：用属性变量拼路径，改了 WADELIB_HOME 这里不用动 --> <import file="${WADELIB_HOME}/build/build_wadelib.xml"/>

如果 wadelib 和应用目录不在同一级，就必须改这一行。比如应用在proj/app、框架在proj/wadelib，那么相对 build 目录算下来是../../wadelib/build/build_wadelib.xml：

<!-- 写法二：硬编码相对路径，目录一挪就得跟着改 --> <import file="../../wadelib/build/build_wadelib.xml"/>

我一般固定用写法一，把差异收敛到build.properties的一个变量上。这里翻车过的场景很典型：把项目从D:\work\proj挪到另一台机器的E:\code\proj，写法二的相对路径没变、盘符变了，Ant 报Cannot find build_wadelib.xml，日志里指向的还是上一台机器的绝对路径——因为 Ant 会缓存上一次的解析结果，把.ant缓存和build/下的临时目录一起清掉才恢复正常。

2.4 ant all 与 ant allwar 两条编译路径

同一份脚本对外只暴露两个目标，用途完全不同：

# 开发期用这个：编译到 web/WEB-INF/classes，改完 Java 直接刷新页面 ant all # 出包用这个：打成 war，需要 ant-contrib.jar 支持 <if> / <foreach> 任务 ant allwar

ant all只做编译和资源拷贝，速度快，适合改一行看一眼。ant allwar会走完整的打包链路：切PROVINCE_NAME、编译、打 jar、打 war，脚本里用到了<if>这类条件任务，而这些任务不在 Ant 核心包里，必须先把ant-contrib.jar放进$ANT_HOME/lib，或者在命令行上加-lib指定：

# 把扩展包丢进 Ant 的 lib 目录，之后 allwar 才能识别 <if> 任务 cp ant-contrib.jar "$ANT_HOME/lib/" # 不想动全局环境的话，用 -lib 临时挂载 ant allwar -lib ant-contrib.jar

第二种方式更适合多人共用一台构建机，避免有人换了 Ant 版本之后把 jar 覆盖掉。报错信息通常是Problem: failed to create task or type if，看到这条直接查 ant-contrib，不用去翻业务代码。

3. 增删改查主链路：PageData、IData 与 DAO 的三层分工

框架把一次请求切成三段，每段职责很清晰，写新功能时按这个三段式套就行，不用想太多。页面组件负责收集表单值和触发事件，Page 类负责取参数、调 Bean、决定跳转，Bean 负责把业务字段补全后交给 DAO。三层的边界模糊了，代码就会变成一坨。

3.1 页面组件与 PageData 的分工

HTML 用的是jwcid属性标记组件类型，表达式用ognl:前缀，事件方法统统写成listener="ognl:listeners.xxx"。列表页的新增入口是这样：

<!-- source 决定跳转时携带哪些数据，value 是链接文案，onclick 才是真正的跳转动作 --> <a jwcid="@wade:PageRedirect" source="ognl:condition" value="新增" class="e_bLinkAdd" onclick="redirectTo('examples.basic.VipcustEdit', null, parameters)"/>

@wade:PageRedirect是框架自己的组件，不是标准标签，它把source指向的对象解析成 URL 参数，redirectTo的第二个参数是目标 Page 上要执行的 listener 方法名，第三个parameters是当前页面的查询条件集合——翻页、返回时这些条件会原样带回去，用户不用重新筛。

Page 类里的入口方法统一收一个IRequestCycle，然后立刻拿PageData：

public void createVipcust(IRequestCycle cycle) throws Exception { PageData pd = getPageData(); // 页面上的所有表单字段都在 pd.getData() 里，以文本形式存放 ExamplesBean bean = new ExamplesBean(); String vip_id = bean.createVipcust(pd, pd.getData()); // 把主键带回去，下一页可以直接拿去查详情 pd.setTransfer("VIP_ID", vip_id); // 操作完弹提示，两个按钮分别指向继续新增和查看详情 redirectToMsg("VIP 客户资料新增成功，选择【继续新增】跳转到[VIP 客户资料新增]页面，选择【查看详情】跳转到[VIP 客户资料详情]页面", new String[] { getPageName(), getPageName() }, new String[] { null, "queryVipcust" }, new String[] { "继续新增", "查看详情" }); }

pd.getData()是整页表单字段的集合，类型是IData，本质是个有序 Map。pd.setTransfer(key, value)只往下页传一个键值，不带参数的重载pd.setTransfer("VIP_ID")表示「PageData 里已有的这个键直接传下去」。redirectToMsg后面跟三个数组，依次是目标页面名、目标页面上的 listener 方法名、按钮文案，位置一一对应，写错顺序就是按钮点下去跳到错误页面，而且不报错，只能靠肉眼核对。

3.2 新增：取值、补默认值、插表

Bean 里的新增方法承担了数据补全的活，凡是页面上没填、但表里非空或有业务默认值的字段，全部在这里补齐：

public String createVipcust(PageData pd, IData data) throws Exception { ExamplesDAO dao = new ExamplesDAO(pd); // 主键不走自增，统一从数据库序列取 String vip_id = dao.getSequence("SEQ_VIP_ID"); // 表单里提交的字段名和表字段名不一致时，在这里做映射 data.put("USER_ID", data.get("USECUST_ID")); data.put("CUST_ID", data.get("USECUST_ID")); data.put("CUST_NAME", data.get("USECUST_NAME")); data.put("VIP_ID", vip_id); data.put("REMOVE_TAG", ExampleFactory.VIP_REMOVETAG_VALID); // 有效标记 data.put("NET_TYPE_CODE", ExampleFactory.VIP_NETTYPE_DEFAULT); // 默认网别 // 归属信息一律从登录上下文取，不接受页面传值，防止越权 data.put("IN_STAFF_ID", pd.getContext().getStaffId()); data.put("IN_DEPART_ID", pd.getContext().getDeptId()); data.put("CITY_CODE", pd.getContext().getCityId()); data.put("EPARCHY_CODE", pd.getContext().getEpachyId()); data.put("JOIN_DATE", common.getSysTime()); data.put("IN_DATE", common.getSysTime()); dao.insert("TF_F_CUST_VIP", data); return vip_id; }

参数说明：pd用来取会话上下文，data是待插入的字段集合，返回主键方便调用方跳转。这里有个必须记住的约定——所有数据都以文本形式进数据集，时间也是如此，直接写yyyy-MM-dd HH:mm:ss格式的字符串就行，框架在落库时自己处理类型转换。曾经有同事在data.put("JOIN_DATE", new Date())里塞了个 Date 对象，编译期毫无问题，运行时在 Oracle 那一层抛类型不匹配，日志还被吞掉半截，这就是典型的「框架帮你做了转换，你就别自作主张」的场景。

归属字段从pd.getContext()取而不是从表单取，这条规则值得单独强调：一旦允许页面传CITY_CODE，用户改一下隐藏域就能把数据写到别的业务区，事后清理这类脏数据的成本极高。

3.3 修改：save 与 update 的选择，以及防并发覆盖

修改这条链路上最容易踩的坑不是代码怎么写，而是两个 DAO 方法的语义差异：

• update是整行覆盖，data里没有指定的字段会被写成 null 或空串。
• save是先按主键查一遍原记录，再用data覆盖，没涉及的字段保持原值。

结论很直接：页面上只改三五个字段，用save；data已经是整行完整数据，用update，省一次查询。用错方向的代价是全表字段被清空，而且没有后悔药。

第二个问题是并发。同一个页面被打开两次，或者两个人同时编辑同一条记录，后提交的那个不应该无脑覆盖。框架给的解法是把「关键列」一起作为匹配条件传进去：

public boolean updateVipcust(PageData pd, IData data, String[] values) throws Exception { ExamplesDAO dao = new ExamplesDAO(pd); // 按 VIP_ID + REMOVE_TAG 两个条件更新：记录被删或被注销时匹配不到，返回 false return dao.save("TF_F_CUST_VIP", data, new String[] { "VIP_ID", "REMOVE_TAG" }, values); }

values是按new String[] { vip_id, remove_tag }的顺序从页面参数里取出来的，顺序必须和列名数组严格对应，错位了就是拿主键去匹配标记位，永远匹配不上。Page 类里判断返回值即可：

public void updateVipcust(IRequestCycle cycle) throws Exception { PageData pd = getPageData(); String vip_id = pd.getParameter("VIP_ID"); String remove_tag = pd.getParameter("REMOVE_TAG"); ExamplesBean bean = new ExamplesBean(); if (!bean.updateVipcust(pd, pd.getData(), new String[] { vip_id, remove_tag })) common.error("修改失败，信息在此操作前已经被操作过"); pd.setTransfer("VIP_ID"); redirectToMsg("VIP 客户资料修改成功...", new String[] { getPageName(), getPageName() }, new String[] { null, "queryVipcust" }, new String[] { "继续修改", "查看详情" }); }

注意remove_tag这个字段的语义：它不是用来筛选「有效记录」的，而是用来判断「这条记录在我打开页面之后有没有被注销」。把它当作并发令牌用，比引入版本号字段轻量得多，前提是这个状态在同一条业务链上只会单调变化。

3.4 删除与查看：绑定列参数怎么传

删除和单条查询是同一套模式的两个方向，区别只在于 DAO 方法的返回值和传入结构：

public boolean deleteVipcust(PageData pd, String vip_id, String remove_tag) throws Exception { ExamplesDAO dao = new ExamplesDAO(pd); IData data = new DataMap(); data.put("VIP_ID", vip_id); data.put("REMOVE_TAG", remove_tag); // 同样用两列做匹配条件，注销后的记录删不掉 return dao.delete("TF_F_CUST_VIP", data, new String[] { "VIP_ID", "REMOVE_TAG" }); }

查看则是反过来，返回一条IData，查不到返回 null，Page 类负责把 null 转成用户能看懂的提示：

public IData queryVipcust(PageData pd, String vip_id) throws Exception { ExamplesDAO dao = new ExamplesDAO(pd); IData data = new DataMap(); data.put("VIP_ID", vip_id); // queryByPK 默认按表结构主键查，第三个参数换成指定列就按指定列查 return dao.queryByPK("TF_F_CUST_VIP", data); }

这里有个细节值得写下来：queryByPK名字里带 PK，但实际行为可以通过第三个参数改成任意列组合。一个常见的用法是包一层sysdate之类的条件查「当前有效」的那条记录，把业务规则下沉到 DAO 调用处，而不是在 Bean 里用 if 判断，代码会干净很多。

3.5 批量：DatasetList 与 executeBatch

批量操作分三种，选哪种取决于你要做的事能不能用一条 SQL 覆盖。

第一种是批量插入，把逐条记录攒成一个IDataset再一次性提交：

public void createVipcusts(PageData pd, IDataset dataset) throws Exception { ExamplesDAO dao = new ExamplesDAO(pd); for (int i = 0; i < dataset.size(); i++) { IData data = (IData) dataset.get(i); data.put("VIP_ID", dao.getSequence("SEQ_VIP_ID")); data.put("USER_ID", data.get("USECUST_ID")); data.put("CUST_ID", data.get("USECUST_ID")); data.put("CUST_NAME", data.get("USECUST_NAME")); data.put("REMOVE_TAG", ExampleFactory.VIP_REMOVETAG_VALID); data.put("IN_STAFF_ID", pd.getContext().getStaffId()); data.put("JOIN_DATE", common.getSysTime()); } // 一次提交整批，框架内部按批处理提交，不要在外面循环单条 insert dao.insert("TF_F_CUST_VIP", dataset); }

第二种是批量删除，用页面勾选的 ID 数组拼数据集，逻辑和上面几乎对称。第三种是自定义批量，当插入、更新、删除三种通用能力都表达不了你的业务时，走executeBatch手工绑定参数：

String sql = "update TF_F_VIP_CUST set CUST_NAME = ?, CUST_TYPE = ? where VIP_ID = ?"; Parameter[] params = new Parameter[vip_ids.length]; for (int i = 0; i < params.length; i++) { params[i] = new Parameter(); params[i].add(cust_names[i]); // 第 1 个 ? 对应 params[i].add(cust_types[i]); // 第 2 个 ? 对应 params[i].add(vip_ids[i]); // 第 3 个 ? 对应 } executeBatch(sql, params);

Parameter就是一组有序占位符值的容器，add的顺序必须和 SQL 里?出现的顺序完全一致。原始文档示例里这句 SQL 写成了set CUST_NAME = ? and CUST_TYPE = ?，用and连接两个赋值——这在 SQL 里是语法错误，抄的时候记得改成逗号，别照抄。这种文档里的笔误很常见，判断依据永远是 SQL 语法本身，不是示例。

4. 批量导入：import/export 双份 XML 配置怎么落地

Excel 导入是这类系统里出现频率最高、也最容易做砸的功能。框架把它拆成两件事：一份配置描述「怎么读」，一份配置描述「失败后怎么原样吐回去」。两份额外配置都放在etc/下，和业务代码分开放。

4.1 导入配置 import/xxx.xml 的 cell 属性

读取配置描述每一列的校验规则和展示属性：

<sheet desc="VIP 客户资料"> <header isshow="true" height="300"> <!-- type: 1 字符串 / 2 数字 / 3 时间；nullable 控制必填；maxsize 控制最大长度 --> <cell name="USECUST_ID" desc="客户标识" type="2" align="1" width="4000" nullable="no" maxsize="16"/> <cell name="USECUST_NAME" desc="客户名称" type="1" align="1" width="6000" nullable="no" maxsize="100"/> </header> </sheet>

name必须和 Bean 里data.get(...)用的键一致，是这一份配置和代码之间唯一的契约。nullable="no"的效果是整批数据里任一行该列为空，那一行就进失败集，不会静默跳过。maxsize是读入时截断还是报错，取决于框架版本，稳妥做法是在配置里放宽一点，把长度校验交给业务侧自己做，这样报错信息才说得清楚。

4.2 失败回写配置必须全部设 type=“1”

第二份配置专门管失败数据的导出，位置在etc/export/下。它有一个和导入配置完全不同的原则：

<sheet name="VIP 客户资料" desc="日程信息"> <header isshow="true" height="300"> <!-- 全部列一律 type="1"，不做任何类型转换，保证原样回吐 --> <cell name="SCHE_SUBJECT" desc="日程主题" type="1" align="1" width="6000"/> <cell name="IMPORT_ERROR" desc="导入错误" type="1" align="1" width="10000"/> </header> </sheet>

为什么必须全是字符串？因为用户上传的原始值要原封不动还给他，让他能改完再传一次。如果某列设成type="3"并配了format="yyyy-MM-dd HH:mm"，而用户填的是2007-03-01，导出时会补成2007-03-01 00:00，用户拿回去一对比就懵了：「我明明填的是日期，怎么多出来时间」。这属于典型的「框架帮你格式化，反而害了你」。

IMPORT_ERROR这一列是框架约定的固定列名，错误原因由业务侧在失败记录上写进去，导出时按列名匹配，写错名字这一列就空着。

4.3 页面方法：ExcelParser 的两个方向

Page 类只做编排，读和写都交给ExcelParser：

public void importVipcusts(IRequestCycle cycle) throws Exception { PageData pd = getPageData(); // 导入返回的是数据集数组，取 [0] 表示只读第一张 sheet IDataset dataset = ExcelParser.importExcel(pd, "examples/basic/VipcustList.xml", pd.getUploadFile("FILE_PATH").getStream())[0]; ExamplesBean bean = new ExamplesBean(); IDataset failds = bean.importVipcusts(pd, dataset); if (failds.size() != 0) { // 把失败集写成 Excel，返回文件标识用于生成下载链接 String file_id = ExcelParser.writeExcelByImport(pd, "examples/basic/VipcustImport.xml", new IDataset[] { failds }); redirectToMsgByPopup("VIP 客户资料批量导入情况：共导入" + dataset.size() + "条，成功" + (dataset.size() - failds.size()) + "条，失败" + failds.size() + "条，请点击[" + ExcelParser.getFailedLinkByImport(file_id, "日程批量导入失败列表.xls") + "]下载导入失败文件"); } else { redirectToMsgByPopup("VIP 客户资料批量导入成功，按【关闭】关闭窗口回到主页面"); } }

几个参数的含义要记牢：importExcel的第二个参数是相对etc/的配置路径，不带.xml前的目录前缀就会报找不到；第三个参数直接吃getUploadFile("FILE_PATH").getStream()得到的输入流，FILE_PATH必须和 HTML 里<input type="file" name="FILE_PATH"/>的 name 一致；返回值是IDataset[]，一个 sheet 对应一个元素。writeExcelByImport返回的file_id不是文件名，是框架内部的文件标识，必须用getFailedLinkByImport包一下才能变成可点击的下载链接，直接把file_id拼进 a 标签是拿不到文件的。

Bean 侧的逻辑是把整批数据过一遍，校验不通过的行写进failds并把原因放进IMPORT_ERROR，通过的行走批量插入。这里不要图省事把整个导入放到一个事务里，一条脏数据回滚全表，用户会在地铁上给你打电话。

4.4 表单 encType 与模板下载

HTML 这一侧有两个点，任何一个漏掉都会导致「点了导入没反应」：

<!-- enctype 必须 multipart，否则服务端拿不到文件流 --> <form method="post" enctype="multipart/form-data" jwcid="@Form"> <!-- name 要和 Page 里 getUploadFile 的键一致 --> <input type="file" name="FILE_PATH"/> <a href="#" jwcid="@LinkSubmit" listener="ognl:listeners.importVipcusts" value="导入" desc="日程信息"></a> <!-- file_name 是下载后保存的名字，file_path 是服务器上的实际路径 --> <a href="attach?file_name=日程批量导入模板.xls&file_path=/templet/examples/basic/VipcustTemplet.xls" target="printframe">下载导入模板</a> </form>

target="printframe"指向页面里一个隐藏 iframe，作用是下载不刷新当前页面，用户填了一半的数据不会丢。模板统一放templet/下，路径写死相对路径，别写绝对路径，一换环境就 404。

还有一步经常被忽略：页面上必须实现verifyAll、confirmForm、confirmInfo这套标准校验方法，即使方法体是空的。原因是框架的提交链路按固定顺序回调这几个钩子，缺一个就会在某个环节中断，表现是「后台完全收不到数据，也没有任何报错」，属于查起来最耗时的一类黑匣子问题。

5. 版本改造与踩坑排查：从 2.5 到 2.59 那些必须动的地方

框架每升一个版本，都会在文档里列一页「建议改造点」。这些条目单独看都是小事，攒在一起就是一套必须做完的清单，做一半升上去，系统会在某个想不到的地方出问题。

5.1 版本改造清单：按影响面排优先级

2.52 那条要把优先级拉到最高，因为它的失败方式是硬报错。2.53 和 2.55 属于「不做也能跑，但集群环境下会有诡异问题」的类型——典型的翻车场景是双节点部署后，用户在 A 节点登录、请求被分发到 B 节点，缓存里查不到登录态，页面突然跳回登录页，日志里一片正常。这就是不做 2.55 的代价。

2.59 的JDK_VERSION是给编译器用的，配1.5时如果实际运行环境是 1.4，类文件版本不兼容，部署时才会报UnsupportedClassVersionError，本地编译永远发现不了。稳妥做法是直接按最低运行环境配：

# 按实际生产环境的最低 JDK 版本配置，宁可编译期保守 JDK_VERSION = 1.4

5.2 页面初始化脚本与 DOM 操作的规范化

2.5 那一版动了页面加载机制，改动不大但影响所有老页面。旧写法是在页面底部手写一段脚本调init()：

<!-- 老写法：每个页面都要手写，而且时机不可控 --> <script>init();</script>

新机制是页面载入时自动调一个按页面名生成的默认方法，比如页面叫examples.basic.VipcustEdit，就去调initVipcustEdit()，没定义就静默跳过。想改方法名，在页面头部声明initScript参数即可。同一版还规整了 DOM 取值方式：

// 推荐：通过框架封装的方法取对象，能正确处理复合组件 getElement("custName"); getElements("vipList"); hidden("vipId"); disabled("btnSubmit"); // 禁止：直接操作 DOM，日期组件这种复合对象只会隐藏文本框，图标还在 // document.getElementById("joinDate").disabled = true;

原因很实在：日期组件在页面上是一个文本框加一个日历图标，两个 DOM 节点。直接disabled文本框，图标还能点，用户点了弹出日历但选不中值，这个 bug 在测试那边很难复现，只有真用户会踩。

同一版还把linkSubmit(page, listener, params)换成了@wade:PageSubmit组件。老方法的跳转在不同浏览器下表现不一致，尤其是在表单里嵌套使用时，某些环境下根本不跳。新组件没这个毛病，改造成本也就是把属性挪一遍。

5.3 五条踩坑记录：现象、原因、解决

坑一：新项目跑起来菜单全是死链

现象：ant newproject之后编译通过、登录正常，左侧菜单点哪个都 500，控制台报找不到页面类。

原因：etc/page.application里的页面注册项和sidebar.html里的菜单项都是 quickstart 原样带过来的，newproject只做了字符串替换，没有删条目。

解决：打开这两份文件，把不属于新业务的条目整行删掉，再重新ant all。养成习惯，新项目生成后第一件事就是清这两份配置，别等到跑起来才回头查。

坑二：allwar 报 failed to create task or type if

现象：ant all一切正常，ant allwar直接停在任务解析阶段，日志里是failed to create task or type if。

原因：allwar里有条件判断逻辑，用了 ant-contrib 提供的任务类型，这个包不在 Ant 核心里。

解决：把ant-contrib.jar放进$ANT_HOME/lib，或者每次构建时加-lib参数指定。构建机是多人共用的话，走-lib更安全，避免有人升级 Ant 时把 jar 覆盖掉。

坑三：Bottom 页面在 Linux 上 404

现象：本地 Windows 开发一切正常，部署到 Linux 服务器后每个页面底部都报错。

原因：2.52 要求把Buttom改成Bottom，代码里改了但资源文件名没改。Windows 文件系统不区分大小写，Linux 区分。

解决：用find . -name "*uttom*"全仓搜一遍，文件名、page.application里的注册名、类名三处一起改。这类问题在提交前跑一次全仓搜索就能拦住，比部署后发现省事得多。

坑四：修改页面只改了两个字段，结果整行被清空

现象：编辑页提交后，用户没动的备注、地址这些字段全变成空值。

原因：Bean 里用了dao.update(...)，它按整行覆盖写，data里没有的字段一律置空。

解决：改成dao.save(...)，它会先查原记录再覆盖。判断标准很简单——页面上的表单字段是否覆盖了表的全部列，覆盖了用update，否则一律save。

坑五：导入失败的文件日期全变了样

现象：用户上传的 Excel 里有几行日期不对，下载回来的失败文件里日期都多出00:00，用户不认账。

原因：失败回写配置的列设了type="3"和format，导出时做了格式化转换，原始值丢失。

解决：export/xxximport.xml里所有列统一type="1"，不做任何转换，原样吐回去。这条规则适用于所有「把用户数据还给他」的场景，不只是导入失败。

6. 二次开发：把 quickstart 改成自己业务模块的验证清单

真正上手改的时候，最怕的不是不会写，而是改完之后不知道有没有改对。我现在的做法是每加一个业务模块，都按固定顺序验证一遍，把问题拦在提交之前。

第一步是确认新模块的页面注册完整。加一张表对应的列表页、编辑页、详情页，三份 HTML 放在web/下对应包路径里，Page 类放在src/下同名包路径里，然后去page.application注册。注册名和文件路径必须严格对应，这里错一个字母的表现是页面 404，但报错信息不会告诉你是哪一条配置错了——所以在注册完之后立刻跑一遍ant all，让编译期先把拼写问题暴露出来。

第二步是核对字段映射。Bean 里data.put的键名、导入配置里的name属性、表单控件的name，这三处是同一份契约的三种表述，任何一处不一致都表现为「数据进去了但是空的」。我一般会在 Bean 的新增方法末尾加一行临时日志，把data的键全打出来对一遍，确认无误再删掉：

// 临时校验：打印实际提交的字段名和值，对完删掉 for (Object key : data.keySet()) { System.out.println("[WADE-DEBUG] " + key + " = " + data.get(key)); }

第三步是并发路径。新做的修改功能，一定要用两个浏览器窗口同时打开同一条记录，一个先改先提交，另一个后提交，看第二个是不是被拦截并给出提示。没被拦截就说明匹配列没配对，save的第三个参数里少了并发令牌列。

第四步是打包验证。ant all通过不代表ant allwar通过，allwar会走PROVINCE_NAME切换和完整的资源拷贝，有些只在特定省份生效的配置到这个环节才会暴露。我的习惯是每个模块自测完都跑一次allwar，把打出来的 war 丢到一个干净环境里起一遍，登录、点菜单、做一次新增和一次导入，走完这条线再提。

最后一步是版本改造清单的自查。框架文档里从 2.5 到 2.59 列的条目，我做成一张勾选表放在项目根目录，每次升级框架前对着勾一遍，尤其是Bottom改名和ehcache.xml合并这两条——前者是硬报错，后者是只在集群下才现形的软故障。

从那以后我每次生成新项目、或者往老项目里加模块，都强制走一遍这五步，哪怕只是加一个只有两个字段的小页面。WADE 这套框架的约定密度高，省一步，后面就要花三倍时间去定位一个不带任何报错的空值。希望帮到你。

本文还有配套的精品资源，点击获取