常见问题与排错手册
导读
关于「常见问题与排错手册」,这里按「结论 → 原理 → 追问」的顺序梳理,方便随时查阅。
这一篇汇总开发这套系统时最容易踩的坑,按现象分类,给出原因与解法。
一、中文乱码
| 现象 | 原因 | 解法 |
|---|---|---|
提交表单后中文变 ??? |
请求未按指定编码解析 | web.xml 配置 CharacterEncodingFilter,且排在其他 Filter 之前 |
| 页面显示乱码 | 页面编码与响应编码不一致 | JSP 头部 <%@ page contentType="text/html;charset=GBK" pageEncoding="GBK" %> |
| 数据库里是乱码,读出来也是乱码 | 数据库/连接串字符集不一致 | 见下 |
完整的字符集链路必须五处一致:
JSP 页面编码 → Filter 编码 → JDBC 连接串 → 数据库字符集 → 表字段字符集
<!-- 1. Filter -->
<init-param><param-name>encoding</param-name><param-value>GBK</param-value></init-param>
<!-- 2. 连接串 -->
<property name="hibernate.connection.url">
jdbc:mysql://127.0.0.1/oa?useUnicode=true&characterEncoding=GBK
</property>
# 3. MySQL my.ini(老版本)
[mysql]
default-character-set=gb2312
[mysqld]
default-character-set=gb2312
改完字符集后必须删库重建,已存在的表不会跟着变。老版本 MySQL(5.0 及更早)建议用
gb2312/gbk;新版本统一用utf8mb4。
初始化数据导入时报中文异常,99% 是字符集问题,按上面三步处理即可。
二、Hibernate 相关
2.1 Duplicate import: User
现象:启动报 org.hibernate.DuplicateMappingException: duplicate import: User refers to both org.jbpm.identity.User and com.oa.model.User
原因:jBPM 自带 org.jbpm.identity.User,与业务 User 重名,Hibernate 的 HQL 自动导入冲突。
解法:业务 User 的映射关掉自动导入:
<hibernate-mapping auto-import="false">
<class name="com.oa.model.User" table="T_User"> ... </class>
</hibernate-mapping>
代价是所有 HQL 必须写全限定名:
getHibernateTemplate().find("from com.oa.model.User u where u.username = ?", username);
2.2 LazyInitializationException: could not initialize proxy
现象:JSP 里取 ${org.children} 或 ${document.creator.name} 报错。
原因:业务方法返回后 Session 已关闭,懒加载对象取不到数据。
解法:
- 确认
OpenSessionInViewFilter已配置且映射/*; - 或在集合映射上加
lazy="false"(如Organization.children); - 或在 HQL 里用
fetch join主动抓取。
列表页慎用
lazy="false",会引发 N+1 查询。
2.3 表没有自动创建
现象:启动后数据库里没有表,或缺少 JBPM_* 表。
排查:
hibernate.cfg.xml里hbm2ddl.auto是否为update/create;- 所有
*.hbm.xml是否都在mapping resource列表里(新增实体后容易忘); - jBPM 的映射是否加入(缺了就不会建
JBPM_*表); - 数据库账号是否有 DDL 权限。
2.4 NonUniqueObjectException
现象:a different object with the same identifier value was already associated with the session
原因:同一个 Session 里有两个 id 相同但对象不同的实例(常见于先 load 再 save 一个 new 出来的同 id 对象)。
解法:用 getHibernateTemplate().merge(obj) 或 session.evict(旧对象),避免重复构造。
三、Spring 与 Struts 整合
| 现象 | 原因 | 解法 |
|---|---|---|
No bean named '/org' is defined |
applicationContext-actions.xml 中 Bean 的 name 与 struts 的 path 不一致 |
两边必须完全一致,含前导斜杠 |
| Action 里的 Manager 为 null | Action 不是 Spring 创建的 | struts-config.xml 的 type 必须是 DelegatingActionProxy |
| 两个用户操作互相干扰 | Action 是单例 | 加 scope="prototype" |
| 事务没生效 | 切入点没匹配到 | 检查 execution (* com.oa.managers.*.*(..)) 路径是否正确 |
| 异常抛了但数据已提交 | 抛的是 checked exception,默认不回滚 | 抛 RuntimeException(本项目 SystemException 正是如此),或配置 rollback-for |
BeanCreationException 循环依赖 |
两个 Manager 互相注入 | 改为在方法里从容器取,或用 setter 注入 + 延迟使用 |
四、分页相关
| 现象 | 原因 | 解法 |
|---|---|---|
| 翻页后莫名跳到别的页 | ThreadLocal 未清理 | PagerFilter 的 finally 块里 removeOffset()/removePagesize() |
| 分页参数丢失 | 翻页 URL 未带其他查询参数 | <pg:param name="parentId"/> |
| 分页不生效,一次查全部 | SystemContext.getPagesize() 返回 Integer.MAX_VALUE |
确认 PagerFilter 已执行(filter-mapping 是否覆盖该 URL) |
无效的HQL查询语句 |
HQL 里没有 from 关键字 |
getCountQuery 依赖 indexOf("from"),HQL 必须包含 from |
五、权限相关
| 现象 | 原因 | 解法 |
|---|---|---|
| 登录后菜单为空 | 该用户没有任何 READ 授权 | 用管理员给角色授权,或检查 searchModules 里的角色查询 HQL |
| 按钮都不显示 | SecurityFunctions.aclManager 为 null |
Spring 里配置了该 Bean 且注入了 aclManager;注意 setter 不能是 static |
| 越权仍能访问 | 只做了前端隐藏 | Action 或 Manager 内再调 hasPermission 校验 |
| 授权不生效 | 用户级 ACL 的 aclTriState = -1(继承),但角色级没有记录 |
检查角色是否真的授权;或把用户级设为不继承 |
| 一个用户多个角色,权限不符合预期 | 角色优先级 orderNo 未按预期排序 | 确认 UsersRoles.orderNo,数字小的优先级高 |
调试技巧:直接查 ACL 表看位值:
SELECT principalType, principalSn, resourceSn,
aclState & 1 AS C, aclState & 2 AS R,
aclState & 4 AS U, aclState & 8 AS D,
aclTriState
FROM T_ACL WHERE principalSn = 5;
六、jBPM 相关
| 现象 | 原因 | 解法 |
|---|---|---|
启动报 jbpm.cfg.xml not found |
配置文件不在类路径根 | 从 jBPM 发行包拷 default.jbpm.cfg.xml 改名为 jbpm.cfg.xml,放 src/ 下 |
| 部署流程后查不到 | 流程名不一致 | Workflow.name 必须与 process-definition 的 name 完全一致 |
| 流程不前进 | 起始节点用了 taskInstance.end() |
起始节点没有任务实例,必须用 token.signal(transitionName) |
| 查不到我的待办 | actor-id 写的是用户 id |
必须是 User.username(登录名) |
| 公文状态一直是"新建" | 提交时没有更新 document.status | 检查 submitToWorkflow 是否回写了状态 |
| 流程结束了状态没变"完成" | 未判断 instance.hasEnded() |
flowToNextStep 末尾要判断并置 STATUS_END |
| 条件分支不生效 | 流程变量没注入 | 确认流程定义里挂了 CopyPropertiesActionHandler,且表单值已保存 |
| 删除流程后仍可发起 | 只删了 jBPM 或只删了 OA 侧 | 两边都要删,且 jBPM 要删所有版本 |
报错 JbpmContext 未关闭 |
用完没 close | 用 try/finally 调 context.close() |
流程调试建议:先把 jbpm.cfg.xml 的 logging 服务打开,直接看 JBPM_LOG 表,比看应用日志更直观。
七、动态表单相关
| 现象 | 原因 | 解法 |
|---|---|---|
提交后 props 为空 |
表单 enctype 不对,或 input 的 name 没写成 props(xxx) |
文件上传必须 enctype="multipart/form-data";name 严格用 props(字段名) |
| 模板找不到 | 模板不在 com/oa/freemarker/templates/ 下,或没编译进 WEB-INF/classes |
确认 ClassTemplateLoader(FreemarkerManager.class, "templates") 的相对路径 |
| 下拉框没有选项 | FormField.items 为空 |
定义表单时保存候选项(用 AutoArrayList 接收) |
| 整数字段保存成字符串 | 未做类型转换 | ConvertUtils.convert(source, Class.forName(type)) |
| 文件字段为 null | 取字节的方式不对 | FormFile.getFileData() |
无法处理输入的值 |
转换结果为 null | 检查类型配置(java.lang.Integer/java.lang.String/java.io.File 大小写与拼写) |
八、依赖与环境
| 现象 | 原因 | 解法 |
|---|---|---|
UnsupportedClassVersionError |
编译 JDK 高于运行 JDK | 统一 JDK 版本,或用 -source/-target 指定 |
NoSuchMethodError |
jar 版本冲突(常见 asm、cglib、commons-logging) |
删除重复 jar,只保留一个版本 |
ClassNotFoundException: org.apache.commons.dbcp... |
缺少依赖 | 补齐 commons 系列 |
生成映射后手工改的 hibernate.cfg.xml 被覆盖 |
又跑了 XDoclet 的"生成 Hibernate 配置文件" | 只跑"生成映射文件",配置文件改为手工维护 |
Ant 报 xdoclet taskdef not found |
xdoclet.home 路径不对 |
修改 build.xml 里的 xdoclet.home 属性 |
九、排错的一般方法
- 先看日志:
log4j打开org.hibernate.SQL=DEBUG,把 SQL 抄到 MySQL 里跑一遍; - 二分定位:Controller 打桩 → Manager 打桩 → 直接写 JUnit 测 Manager;
- 查数据:权限问题查
T_ACL,流程问题查JBPM_*,表单问题查T_Document_Properties; - 用调试页:DWR 的
/dwr/、jBPM 的日志表,都是现成的观测窗口; - 最小复现:新建一条流程、一个用户、一份公文,逐步操作,比在复杂数据上排查快得多。
十、把这套老技术迁移到现代栈
如果要用今天的框架重写,对应关系如下:
| 原技术 | 现代替代 |
|---|---|
| Struts 1 + ActionForm | Spring Boot + Spring MVC(注解 + DTO 校验) |
| Hibernate 3 + XDoclet | Spring Data JPA / MyBatis-Plus(注解实体) |
applicationContext-*.xml |
@Configuration 或 Spring Boot 自动配置 |
| jBPM 3 | Flowable / Camunda / Activiti(BPMN 2.0 标准) |
| JSP + JSTL + Dojo | Thymeleaf / Vue / React |
| DWR | REST + JSON + fetch |
| Freemarker 模板渲染表单 | 前端 JSON Schema 驱动的表单引擎(如 form-render) |
| pager-taglib | 前端分页组件 + PageHelper |
值得保留的设计思想:ACL 的三态授权与角色优先级、动态表单的元数据驱动、sn 路径表示树形结构、用流程变量驱动路由。这些与框架无关,属于领域设计层面的经验。
要点小结
- 初始化数据导入时报中文异常,99% 是字符集问题,按上面三步处理即可。
- | 现象 | 原因 | 解法 | |---|---|---| | 提交表单后中文变
???| 请求未按指定编码解析 |web.xml配置 `CharacterE… - | 现象 | 原因 | 解法 | |---|---|---| |
No bean named '/org' is defined| `applicationContex… - | 现象 | 原因 | 解法 | |---|---|---| | 翻页后莫名跳到别的页 | ThreadLocal 未清理 |
PagerFilter的 `finall…
由站内小编编辑整理