简介WADE开发文档面向使用WADE框架进行企业级Java Web开发的中初级开发者围绕框架入门、项目搭建与版本升级改造提供系统说明。文档以单一doc文件收录压缩包约3.24MB内容聚焦quickstart生成空项目、build.properties项目参数配置与WADELIB包路径设置并梳理新建项目、开发改造、新增数据等常见开发场景对2.52至2.59等版本的兼容性调整与建议用法也有集中归纳。已有973人学习适合需要快速理解框架结构、减少升级迁移踩坑的读者。其价值在于把分散的配置项、组件用法和版本差异整理成可检索的参考帮助读者建立从项目初始化到功能改造的整体认知并作为日常开发中的查阅手册。1. 从一份 WADE 开发文档说起Ant 构建 HTML 组件化这套老骨架今天还怎么接手前段时间有人接手一个跑了十几年的 Java Web 工程仓库里没有 pom.xml只有 build 目录下的 build.xml 和十几行 build.properties前端不是 JSP 也不是 Vue而是一堆 HTML 文件标签上挂着jwcidwade:PageRedirect这类非标准属性onclick 里调的是redirectTo(examples.basic.VipcustEdit, null, parameters)。翻遍仓库能对上号的就一份 WADE 开发文档。这套东西的价值不在于新而在于它把「新建工程 → 增删改查 → 批量 → Excel 导入」的每一步都钉死在固定模板上照着文档走一个下午能出一套能跑的业务页面反过来不看文档硬改一个Buttom拼写错误就能让你对着空白页排查半天。这篇把这份文档里真正能落地的部分拆开讲谁在什么场景下用、参数怎么填、哪几个地方我吃过亏。2. 用 quickstart 起一个新工程build.properties 里每个参数都要对上WADE 没有依赖管理器的概念新建工程的方式很原始拿一份叫 quickstart 的模板工程跑一次 Ant 目标在 build 目录下生成一套全新的空项目骨架。这个动作看起来简单但它背后是一次批量文本替换 目录重命名参数填错一个生成出来的工程要么编译不过要么带着 quickstart 的残留页面。2.1 为什么是 ant newproject而不是复制粘贴一份模板很多人第一反应是直接cp -r quickstart newprj把目录名改掉就完事。这个做法在 WADE 里会翻车。因为 quickstart 里的类名、包路径、page.application 配置、sidebar 菜单、甚至 war 包名都是以quickstart / Quickstart / QUICKSTART三种大小写形态散落在几十个文件里的。手改漏一处编译时找不到类还是小事最坑的是运行期某个页面跳转 404你得顺着配置文件一层层挖。ant newproject干的就是这件事读取 build.properties 里声明的三组旧名和三组新名按大小写形态做全量替换再把目录结构复制过去。常见做法是把新项目的三种形态一次想清楚再动手比如新系统叫 custmgr那OLD_NAME1/2/3就是quickstart/Quickstart/QUICKSTARTNEW_NAME1/2/3就对应custmgr/Custmgr/CUSTMGR。三组必须形态一致小写对的小写、驼峰对的驼峰、全大写对的全大写交叉填错会产生Custmgr和CUSTMGR混用的半成品工程。第一步永远是先进 build 目录把所有参数确认一遍再执行# 进入构建目录所有 ant 目标都在这里执行 cd build # 先确认 build.properties 里的新旧名称已按三种大小写形态填好 # 再执行生成命令不带参数读取的就是当前目录的 build.properties ant newproject # 生成完成后回上级目录做一次全量编译验证 cd .. ant allant newproject没有交互式确认参数错了它照跑不误生成完你才发现新工程名叫Newquickstart。所以我的习惯是先cp build.properties build.properties.bak再改出问题直接回滚比重跑一次省事。2.2 build.properties 逐行拆路径、编码、版本三块这份配置文件的参数可以分成三类路径类决定 Ant 去哪找源码和依赖编码类决定编译产物里的字符集名称类决定生成工程叫什么。下表按原文给的配置项整理重点看第三列的说明。参数示例值含义与注意点PROVINCE_NAMEcommon编译时的省代码。开发期统一用 common 走公用代码打包部署时换成实际省份代码这是 WADE 做多省份定制的方式PROJECT_NAMEwade-quickstart项目名称最终产出的 jar / war 文件名都以它为准改这里等于改交付物名字PROJECT_HOME..项目根目录..表示 build 目录的上级一般不用动WADELIB_HOME../../../wadelib/wadelibWADELIB 包所在路径框架核心 jar 从这里的 lib 目录取build${PROJECT_HOME}/build构建脚本目录config${PROJECT_HOME}/etc配置文件目录ehcache、import 定义都在这下面source${PROJECT_HOME}/srcJava 源码目录classes${PROJECT_HOME}/web/WEB-INF/classes编译输出目录注意它在 web 下面不是 targetlib${WADELIB_HOME}/web/WEB-INF/lib依赖 jar 目录指向 WADELIB 而非项目自身web${PROJECT_HOME}/web静态资源与页面目录APPLANGGB2312编译编码。老工程基本都是 GB2312改 UTF-8 要连带改页面 meta、文件实际编码、IDE 设置不建议半路动APPLANG这一项值得单独说两句。新手看到 GB2312 第一反应是「乱码改成 UTF-8」改完之后中文注释编译报错、页面输出问号。原因是这套模板里的 HTML 文件本身就是 GB2312 存盘的配置和文件编码必须一致。要真改是一次全量转码工程不是改一行配置能解决的事。pdf/lib这两项都指向 WADELIB 而不是项目内目录这意味着 WADE 的依赖是「共享 lib」模式多个应用共用一个 wadelib 包。好处是升级框架只改一处坏处是不同应用对同一个 jar 版本有要求时会打架。这也是为什么下面要讲目录结构约束。2.3 WADELIB 和应用目录的相对位置决定 build.xml 要不要改文档里有一句很关键的提醒一般建议 wadelib 和应用目录在同一级。原因是 build.xml 里引入build_wadelib.xml用的是相对路径默认按同级目录算。一旦你的实际部署把 wadelib 放到了别处Ant 会报找不到文件报错信息通常是 import 行号不太直观。!-- build/build.xml 中引入框架构建脚本的那一行默认按同级目录推算 -- import file../../wadelib/build/build_wadelib.xml/ !-- 若 wadelib 与应用不在同一级把相对路径改成实际层级 -- import file../../../wadelib/build/build_wadelib.xml/判断规则很简单从 build 目录出发往上走到能和 wadelib 目录平级的那一层../的个数就是路径前缀。改完别忘了WADELIB_HOME也要同步这两个值必须指向同一个 wadelib否则编译期用的框架 jar 和构建脚本引用的框架版本可能对不上出现「编译通过、运行期 ClassNotFound」的玄学问题。2.4 ant all 和 ant allwar 的分工以及 ant-contrib 这个前置开发期和发布期走两个目标这一点文档写得很明确开发用ant all测试打包发布用ant allwar。前者只编译到 classes 目录改完代码刷新页面就生效后者会打成 war包含完整的目录结构和依赖。ant allwar有一个额外前置需要 ant-contrib.jar。这个 jar 提供 Ant 原生的 if/else、循环等逻辑控制WADE 的打包脚本里用到了。没有它执行 allwar 会直接报taskdef class net.sf.antcontrib.logic.IfTask cannot be found。# 开发期只编译产物进 web/WEB-INF/classes ant all # 发布期打 war 包执行前确认 ant-contrib.jar 已放到 Ant 的 lib 目录 # 或者通过 -lib 参数临时指定 jar 所在目录 ant -lib ./lib allwar把 ant-contrib.jar 放进 Ant 安装目录的 lib 下是全局生效的做法团队里每个人都要做一次-lib方式只在当次命令有效适合 CI 环境或者不想动全局配置的场景。我一般在项目 build 目录下放一份写进一个 build.sh 里固定住新人拉代码跑脚本就行省掉「我这能打包你那不能」的来回确认。新建工程的完整动作到这儿就闭环了改 build.properties → ant newproject → 删 quickstart 残留配置 → 编译验证。第三步的清理最容易被跳过page.application 和 sidebar.html 里还留着 quickstart 示例页面的注册项和菜单项不删的话菜单上会多出一堆点进去报错的死链。判断方法就是全局搜quickstart把配置项删干净页面文件留着当参考实现不影响运行。3. 从 HTML 到 Bean 的三层落地新增、修改、查看的骨架怎么搭WADE 的业务页面是严格的四层分工HTML 声明组件和事件、Page 类接请求做编排、Bean 类写业务和 DAO 调用、DAO 落库。这套分层本身不新鲜新鲜的是每一层之间靠什么串起来——HTML 靠jwcid属性绑定组件Page 靠PageData拿参数和上下文Bean 靠IData传数据。搞不清这三个东西的边界写出来的代码会到处取不到值。3.1 HTML 层jwcid 绑定和 redirectTo 的参数含义页面上做跳转不用a href而是声明一个组件!-- 列表页的「新增」按钮点击后跳到编辑页不带参数 -- a jwcidwade:PageRedirect sourceognl:condition value新增 classe_bLinkAdd onclickredirectTo(examples.basic.VipcustEdit, null, parameters)/ !-- 列表页的「查看/修改」链接把整行数据作为参数带过去 -- a jwcidwade:PageRedirect sourceognl:info columnsVIP_ID valueognl:info.VIP_ID onclickredirectTo(examples.basic.VipcustEdit, queryVipcust, parameters)/jwcid是组件声明wade:PageRedirect表示这是个跳转组件。redirectTo是框架注入的全局函数三个参数依次是目标页面全名、目标页面上的监听方法名、当前页面待传递的参数集合。第二个参数传 null 表示只跳页面不调方法传queryVipcust表示跳过去之后立刻在目标 Page 上执行这个方法用查出来的数据填充表单。source和columns配合使用决定哪些字段会变成 URL 参数带过去。sourceognl:info指向列表当前行对象columnsVIP_ID说明只取主键列。常见错误是source指向了一个循环里已经失效的变量跳过去参数是空的再往后就是「您要查看的记录已不存在」这种提示。3.2 Page 层PageData 是这个世界的入口Page 类的每个 public 方法对应一个页面事件参数固定是IRequestCycle。方法体第一步永远是拿PageDatapublic void createVipcust(IRequestCycle cycle) throws Exception { PageData pd getPageData(); ExamplesBean bean new ExamplesBean(); // 表单数据在 pd.getData() 里整包交给 Bean 处理Page 不写业务 String vip_id bean.createVipcust(pd, pd.getData()); // 把主键传下去下一个页面能从 PageData 里直接取出 pd.setTransfer(VIP_ID, vip_id); // 四组数组按位置一一对应页面、监听方法、按钮文案 redirectToMsg(VIP 客户资料新增成功选择【继续新增】跳转到新增页面选择【查看详情】跳转到详情页面, new String[] { getPageName(), getPageName() }, new String[] { null, queryVipcust }, new String[] { 继续新增, 查看详情 }); }pd.getData()返回的是表单提交上来的IData键名就是 HTML 里组件的 name。pd.setTransfer(key, value)把值放进跨页面传递区接收方用pd.getParameter(VIP_ID)取。pd.getContext()拿的是会话上下文员工号、部门、业务区这些身份信息都从这里出不要自己去读 session。redirectToMsg的四个参数必须长度一致第 n 个页面对应第 n 个监听方法和第 n 个按钮文案。少写一个元素运行时数组越界报错信息不会告诉你哪一行配错了。写这个方法的时候我一般先写页面数组再照着数量补齐另外两个避免错位。3.3 Bean 层数据填充的固定套路和容易漏的字段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; }规律是业务字段从前端 data 里取主键从序列取状态位和网别用常量类兜底人员部门地区和时间一律从pd.getContext()和common.getSysTime()取。最后这条是安全边界前端传什么员工号都不认。新建页面最容易漏的是REMOVE_TAG这个有效标记漏了之后记录插进去了但列表查不出来因为默认查询条件带了有效标记过滤。文档里还有一句注释值得记住所有数据都以文本方式导入数据集时间也直接写成yyyy-MM-dd HH:mm:ss形式的字符串。也就是说这一层不做类型转换转换由 DAO 按目标表字段类型处理。好处是代码里不用到处写 Date 格式化坏处是格式不合法时错误会抛在 DAO 里堆栈不指向你的业务代码。3.4 修改和删除为什么必须带 REMOVE_TAG 一起做条件新增是插入改和删才是真正考验设计的地方。文档专门提醒了一个场景同一个页面被打开多次或者多人同时操作在你提交之前别人已经改过甚至删掉了这条记录。这时候如果只按主键更新会把别人的修改直接覆盖掉而且没有任何提示。WADE 的做法是把「能识别记录当前状态的关键列」一起放进更新条件public boolean updateVipcust(PageData pd, IData data, String[] values) throws Exception { ExamplesDAO dao new ExamplesDAO(pd); // values 是 {vip_id, remove_tag}两个值都匹配上才更新 // 返回 false 表示没有行被影响说明记录已被改动或已注销 return dao.save(TF_F_CUST_VIP, data, new String[] { VIP_ID, REMOVE_TAG }, values); }Page 层拿到 false 就直接common.error(修改失败信息在此操作前已经被操作过)把冲突暴露给用户而不是静默吞掉。这就是最朴素的乐观并发控制用状态列当版本号使。删除同理dao.delete(TF_F_CUST_VIP, data, new String[] { VIP_ID, REMOVE_TAG })注销过的记录删不掉符合业务预期。这里还有一个必须分清的差别save和update。update是整行覆盖data 里没带的字段会被置空save是先按主键查出原记录再把 data 里的字段覆盖上去其余字段保持原值。做表单编辑页面时页面上只提交了部分字段用update会把没在表单里出现的列全部清空——这是我在老系统里见过最多的一类数据丢失。判断标准很简单data 是否包含该表的全部业务字段包含才用update换性能否则老老实实save。4. 批量与导入DatasetList、executeBatch 和 ExcelParser 的实际用法单条增删改查照着模板抄就行真正拉开工作量差距的是批量和导入。这两个功能在 WADE 里各有两套写法批量有「通用批量」和「自定义批量」导入有「标准模板导入」和「带错误回写导入」。选错写法代码量差三倍。4.1 通用批量DatasetList 攒数据一次落库批量新增的核心是不在循环里调 insert而是把整批数据攒成一个IDataset再交给 DAOpublic 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(REMOVE_TAG, ExampleFactory.VIP_REMOVETAG_VALID); data.put(IN_STAFF_ID, pd.getContext().getStaffId()); data.put(IN_DATE, common.getSysTime()); } // 一次性批量插入减少网络往返 dao.insert(TF_F_CUST_VIP, dataset); } public void deleteVipcusts(PageData pd, String[] vips) throws Exception { ExamplesDAO dao new ExamplesDAO(pd); IDataset dataset new DatasetList(); for (int i 0; i vips.length; i) { IData data new DataMap(); data.put(VIP_ID, vips[i]); dataset.add(data); } // 批量删除条件列由 DAO 内部按主键处理 dao.delete(TF_F_CUST_VIP, dataset); }注意dao.insert和dao.delete对IDataset的重载是框架封装好的内部会切成 JDBC 的 batch 执行。主键仍然要逐条取序列别想着循环外取一次然后自增——序列值不连续手工自增在并发下会撞号。HTML 侧批量入口用PageSubmit而不是PageRedirect因为要在当前页触发提交!-- 勾选多行后点删除先弹确认框确认后提交到 deleteVipcusts -- a jwcidwade:PageSubmit value删除 listenerognl:listeners.deleteVipcusts descVIP 客户资料 classe_bLinkDelete onclickreturn queryBox(this, vips);/queryBox(this, vips)返回 false 时整个提交被拦下这是前端唯一一道确认。desc会拼进确认框文案写清楚操作对象别留空。4.2 自定义批量通用 CRUD 覆盖不了时用 executeBatch 手工绑参有些批量操作不是简单的 insert/update/delete比如「按客户标识批量改名称和类型且每行改的值都不一样」。这时候通用方法没法表达得自己拼 SQL 和参数public void batchUpdateVipcusts(IData param) throws Exception { // 前端把多行数据以数组形式提交这里按列拆成三个平行数组 String[] vip_ids common.getValues(param.get(VIP_ID)); String[] cust_names common.getValues(param.get(CUST_NAME)); String[] cust_types common.getValues(param.get(CUST_TYPE)); String sql update TF_F_VIP_CUST set CUST_NAME ?, CUST_TYPE ? where VIP_ID ?; // 每个 Parameter 对应一行add 的顺序必须和 SQL 里 ? 的顺序严格一致 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]); params[i].add(cust_types[i]); params[i].add(vip_ids[i]); } executeBatch(sql, params); }这段代码有两个必须盯住的地方。第一Parameter.add的顺序就是占位符顺序cust_names和cust_types写反了类型对不上报的错是类型转换不指向具体行号只能靠日志逐行核。第二三个数组的长度必须一致common.getValues拆出来的数组长度取决于前端提交的结构某一行少传一个字段就会长度不齐后面的行全部错位。稳妥做法是在循环前加一次长度断言长度不等直接抛业务异常。executeBatch是框架提供的方法不走 DAO 的通用封装事务边界由 Page 层控制中途失败整批回滚。4.3 Excel 导入两份 XML 配置一份管进一份管错导入是 WADE 里配置最重的一块需要两个 XML一份定义导入模板的列格式和校验规则一份定义导出失败数据时的列格式。导入配置示例!-- etc/import/examples/basic/VipcustList.xml定义 Excel 列与字段的映射 -- sheet descVIP 客户资料 header isshowtrue height300 !-- type: 1字符串 2数字 3时间nullable: 是否必填maxsize: 最大长度 -- cell nameUSECUST_ID desc客户标识 type2 align1 width4000 nullableno maxsize16/ cell nameUSECUST_NAME desc客户名称 type1 align1 width6000 nullableno maxsize100/ /header /sheet失败回写配置示例!-- etc/export/examples/basic/VipcustImport.xml把导入失败的行原样导出 -- sheet nameVIP 客户资料 desc日程信息 header isshowtrue height300 cell nameSCHE_SUBJECT desc日程主题 type1 align1 width6000/ !-- 固定加一列错误原因值由业务代码写入 IMPORT_ERROR -- cell nameIMPORT_ERROR desc导入错误 type1 align1 width10000/ /header /sheet失败回写这份配置有一条铁律所有列都设成type1不做任何格式转换。原因文档讲得很清楚如果某列设成时间类型并指定了formatyyyy-MM-dd HH:mm用户原本填的是2007-03-01导出时会变成2007-03-01 00:00原始数据被改写用户拿着这份错误文件改完再导一次数据就对不上了。导出配置里也不要设format保持原样。4.4 导入页面的三个必写项和 Page 层的错误汇总导入页面比普通表单多几个硬性要求缺一个就读不到文件!-- 1. form 必须有 enctype否则服务器拿不到文件流 -- form jwcidForm enctypemultipart/form-data !-- 2. 文件域 name 要与后台 getUploadFile 的参数一致 -- input typefile nameFILE_PATH/ !-- 3. 提交按钮走 PageSubmit监听导入方法 -- a href# jwcidLinkSubmit listenerognl:listeners.importVipcusts value导入 desc日程信息/ !-- 4. 模板下载走 attachfile_name 是下载显示名file_path 是服务器实际路径 -- a hrefattach?file_name日程批量导入模板.xlsfile_path/templet/examples/basic/VipcustTemplet.xls targetprintframe下载模板/a /form后台的处理流程是「解析 → 逐行入库 → 收集失败行 → 生成错误文件 → 汇总提示」public void importVipcusts(IRequestCycle cycle) throws Exception { PageData pd getPageData(); // importExcel 返回 IDataset 数组取第 0 个即解析结果 IDataset dataset ExcelParser.importExcel(pd, examples/basic/VipcustList.xml, pd.getUploadFile(FILE_PATH).getStream())[0]; ExamplesBean bean new ExamplesBean(); // 业务校验在 Bean 里做返回失败行集合 IDataset failds bean.importVipcusts(pd, dataset); if (failds.size() ! 0) { // 把失败行按错误模板导出返回文件 id String file_id ExcelParser.writeExcelByImport(pd, examples/basic/VipcustImport.xml, new IDataset[] { failds }); // 用文件 id 生成下载链接拼进提示文案 redirectToMsgByPopup(VIP 客户资料批量导入情况共导入 dataset.size() 条成功 (dataset.size() - failds.size()) 条失败 failds.size() 条请点[ ExcelParser.getFailedLinkByImport(file_id, 日程批量导入失败列表.xls) ]下载导入失败文件); } else { redirectToMsgByPopup(VIP 客户资料批量导入成功按【关闭】关闭窗口回主页面); } }Bean 里逐行处理时成功行进succds失败行除了原数据还要补两个字段IMPORT_RESULT置 false、IMPORT_ERROR写具体原因。这两个字段就是错误文件里能看出「为什么失败」的唯一来源写清楚「客户标识超长」比写「导入失败」有用得多。还有一条容易被忽略文档要求导入页面必须加verifyAll / confirmForm / confirmInfo这组标准验证方法否则后台取不到数据。这不是可选项是框架在解析上传文件前的前置钩子少了它getUploadFile返回 null。5. 版本升级的六处翻车点排查从 2.5 到 2.59 逐条对WADE 的「开发改造」章节本质上是一份升级 checklist。每个版本列出来的建议点都是「原来能跑但建议换写法」或者「不换就会报错」两类。前者可以缓后者必须改。下面这六条是我在实际工程里真碰过问题的按「现象 → 原因 → 解决」写。5.1 现象页面底部整块报错控制台提示找不到 Buttom 页面这是一条纯拼写引发的血案。2.52 之前底部页面文件叫web/Buttom.html和view/Buttom.java正确拼写应该是Bottom。某次升级后框架内部按正确拼写去找旧的错误文件名就找不到了。原因很明确框架侧的引用路径改了但应用里的文件名和page.application里的注册项还是旧拼写。解决要三处一起改——文件名改成Bottom.html/Bottom.javapage.application里对应的页面注册项改成新名字然后全局搜一遍Buttom确认没有残留引用。只改文件名不改配置报错会从「找不到文件」变成「页面未注册」换个错误继续。5.2 现象页面加载后初始化脚本不执行下拉框没数据2.5 之前常用scriptinit();/script这种方式在页面末尾手写初始化调用。升级后这类写法失效页面看着正常但联动逻辑全不跑。原因是框架改了初始脚本的调用机制每个页面载入时自动调用一个按页面名生成的方法比如页面全名examples.basic.VipcustEdit对应initVipcustEidt()。框架按约定找方法找不到就静默忽略不报错。所以现象是「什么都没发生」最难查。解决分两步先删掉 HTML 里手写的init()调用再把初始化逻辑挪到按约定命名的方法里。要自定义方法名也可以用wade:Head的initScript参数指定但方法必须存在且签名正确否则一样静默跳过。排查这类问题的土办法是在初始化方法第一行打日志日志不出来就说明方法没被调上回头查命名。5.3 现象用 document.getElementById 禁用日期组件只灰掉了输入框日历图标还能点这条踩过的人最多。老代码里到处是document.getElementById(name).disabled true对普通输入框没问题对日期组件就翻车。原因是 WADE 的很多组件不是单一 DOM 节点。日期组件实际由一个文本框加一个图标组成getElementById只能拿到其中之一改它的 disabled 只是灰掉半个组件。文档明确要求改用框架封装的方法getElement(name)、getElements(name)、hidden(name|obj)、disabled(name|obj)。这几个方法知道组件的真实结构会对整个组件生效。解决的迁移成本不小但必须做。搜document.getElementById和document.getElementByName逐个换成对应封装方法。视觉上判断标准很简单禁用之后点图标不该弹出日历能弹就是没换干净。5.4 现象单机跑得好好的一上集群缓存就各节点不一致2.55 之前的缓存是进程内的多节点部署时每个节点各存一份A 节点更新了缓存B 节点还是旧值用户刷新几次看到的数据不一样。原因是缓存实现没有走集群共享。新版本支持共享前提是每个应用把 quickstart 升到 2.35 及以上然后参照etc/common/ehcache.xml改造。实际操作不是整份覆盖而是拿 quickstart 里那份文件的增量部分合并到自己的配置里保留业务自定义的 cache 定义。整份覆盖会把自定义缓存全冲掉这是另一个坑。改完的验证方法两个节点分别触发一次写操作然后在另一个节点读能读到新值说明共享生效。只看日志里有没有「cache initialized」不算数。5.5 现象本地 JDK 1.5 编译通过部署到 1.4 环境启动报 UnsupportedClassVersionError2.59 加了JDK_VERSION参数就是为这个场景准备的。不配这一项Ant 用当前环境的 JDK 编译产物版本跟着环境走。解决是在 build.properties 里显式声明JDK_VERSION1.4或1.5# 编译目标 Java 版本与运行环境保持一致 # 部署环境是 1.4 就必须写 1.4否则 class 文件版本偏高运行期直接拒绝加载 JDK_VERSION 1.4配完之后还要确认编译用的 JDK 本身支持-target 1.4高版本 JDK 已经移除了对老 target 的支持会报target release 1.4 conflicts with default source release。这种情况只能装一个对应版本的老 JDK 专门做编译。这类问题的排查顺序是先看运行环境的java -version再看 class 文件版本javap -verbose看 major version最后核对构建配置别一上来就怀疑代码。6. 改完一个 CRUD 页面后我会跑的六步检查这套框架的反馈回路偏慢编译不报错不代表页面能用页面能打开不代表数据对。我自己的习惯是每改完一个业务页面按固定顺序走一遍六步下来大部分问题当场暴露不用等测试提。步骤检查动作通过标准1全局搜新页面名看page.application和sidebar.html是否都注册了两处都有无 quickstart 残留2编译走ant all确认 classes 目录下有新 Page 类无编译告警类文件时间戳是新的3打开列表页看菜单项和按钮是否渲染按钮样式类生效无裸链接4走一遍新增 → 查看 → 修改 → 删除的完整链路每步提示文案正确主键能传递5修改页故意留空一个字段提交用 save 时原值保留用 update 时字段被清空确认选对了方法6打开两个标签页同时改同一条记录后提交的一方收到「已被操作过」提示第 5 步是专门用来验证save/update选型的。这条我以前吃过亏一个客户信息编辑页表单上只放了五个字段后台用了update结果每次保存都把没在表单上的备注、标签、扩展属性全清空了。上线三天才发现数据已经没法回滚只能从备份里捞。从那以后我每写一个更新方法都先数一遍 data 里的键和表里的列对不对得上对不上就强制走save性能差一点认了。第 6 步验证的是乐观并发那套条件列。做法是开两个窗口加载同一条记录第一个窗口改完提交第二个窗口再提交看是否被拦。拦不住说明更新条件里漏了状态列或者 Page 层没处理false返回值直接忽略了。这一步用两个人配合测更真实一个人操作容易自己骗自己。还有一个进阶技巧值得单独提给PageData的取参加一层兜底日志。pd.getParameter(VIP_ID)取不到时返回 null代码里如果不判空直接拼查询条件会变成全表扫描或者空指针。我的习惯是在每个 Page 事件的入口打一行「页面名 关键参数」日志量不大但排查「为什么这条记录查不出来」的时候能一眼看出是参数没传过来还是传过来是空。public void queryVipcust(IRequestCycle cycle) throws Exception { PageData pd getPageData(); String vip_id pd.getParameter(VIP_ID); // 入口日志参数为空是最常见的一类问题先定位再往下查 log.debug(queryVipcust enter, vip_id vip_id); if (vip_id ! null) { ExamplesBean bean new ExamplesBean(); IData info bean.queryVipcust(pd, vip_id); if (info null) { // 记录不存在要用业务提示不要抛空指针让页面白屏 common.error(您要查看的记录已不存在); } setInfo(info); } }这段代码本身没什么技术含量价值全在那一行日志和 null 分支上。老系统里最耗时间的不是写功能是定位「数据为什么没出来」而这条链路上任何一个环节断掉表现都是同一个空白页面。把入口参数、Bean 返回、DAO 影响行数这三个点各打一行日志排查时间能从半天压到十分钟。这套东西放到今天看确实旧Ant 构建、HTML 组件、GB2312 编码每一样都和现在的技术栈隔着代。但它把一个业务系统的骨架拆得很干净新建工程有固定套路增删改查有固定分层批量和导入有固定模板版本升级有逐条 checklist。接这类工程的时候先照着文档把这几条走通比上来就重构靠谱得多。希望帮到你。本文还有配套的精品资源点击获取