A
📖 Wiki
中

常见问题与排错手册

📄 数据与运维 17 min read 89 views Updated 2026-10-25 Chinese only

导读

关于「常见问题与排错手册」,这里按「结论 → 原理 → 追问」的顺序梳理,方便随时查阅。

这一篇汇总开发这套系统时最容易踩的坑,按现象分类,给出原因与解法。


一、中文乱码

现象 原因 解法
提交表单后中文变 ??? 请求未按指定编码解析 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&amp;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 已关闭,懒加载对象取不到数据。

解法:

  1. 确认 OpenSessionInViewFilter 已配置且映射 /*;
  2. 或在集合映射上加 lazy="false"(如 Organization.children);
  3. 或在 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 属性

九、排错的一般方法

  1. 先看日志:log4j 打开 org.hibernate.SQL=DEBUG,把 SQL 抄到 MySQL 里跑一遍;
  2. 二分定位:Controller 打桩 → Manager 打桩 → 直接写 JUnit 测 Manager;
  3. 查数据:权限问题查 T_ACL,流程问题查 JBPM_*,表单问题查 T_Document_Properties;
  4. 用调试页:DWR 的 /dwr/、jBPM 的日志表,都是现成的观测窗口;
  5. 最小复现:新建一条流程、一个用户、一份公文,逐步操作,比在复杂数据上排查快得多。

十、把这套老技术迁移到现代栈

如果要用今天的框架重写,对应关系如下:

原技术 现代替代
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…

由站内小编编辑整理

Related