通用基础设施:分页、异常与日志
导读
「通用基础设施:分页、异常与日志」常被追问到细节层面,这里把结论、原因和易错点一次讲清楚。
一个系统能不能写得舒服,取决于基础设施扎不扎实。本项目的"基础设施"只有四个小类:PagerModel、SystemContext、PagerFilter、AbstractManager,加上一个异常处理器和一个日期转换器。它们解决的是:分页参数如何优雅传递、异常如何统一呈现、Session 如何在页面渲染时仍然可用。
一、分页:从"参数满天飞"到 ThreadLocal
1.1 最原始的做法
第一版实现是标准的"传参分页":Action 里从请求里取 pager.offset,算好 pagesize,再传给 Manager 方法。
// 呈现层:Action
int offset = Integer.parseInt(request.getParameter("pager.offset"));
int pagesize = 10;
request.setAttribute("pm", orgManager.findOrgs(parentId, offset, pagesize));
// 业务层:Manager
public PagerModel findOrgs(int parentId, int offset, int pagesize) { ... }
问题很明显:每个查询方法都要多带两个参数,而这两个参数跟业务毫无关系,纯粹是"呈现层的事"。方法签名被污染,业务接口不再干净。
1.2 PagerModel:统一分页结果
public class PagerModel {
private int total; // 总记录数
private List datas; // 当前页结果集
// getter / setter
}
1.3 SystemContext:用 ThreadLocal 传递分页参数
既然 offset/pagesize 是"这一次请求"的上下文,那就把它放进线程局部变量,业务层自己去取,不需要调用方传:
public class SystemContext {
private static ThreadLocal offset = new ThreadLocal();
private static ThreadLocal pagesize = new ThreadLocal();
public static int getOffset() {
Integer os = (Integer) offset.get();
return os == null ? 0 : os;
}
public static void setOffset(int offsetvalue) { offset.set(offsetvalue); }
public static void removeOffset() { offset.remove(); }
public static int getPagesize() {
Integer ps = (Integer) pagesize.get();
return ps == null ? Integer.MAX_VALUE : ps; // 未设置时不分页
}
public static void setPagesize(int pagesizevalue) { pagesize.set(pagesizevalue); }
public static void removePagesize() { pagesize.remove(); }
}
1.4 PagerFilter:写入与清理
public class PagerFilter implements Filter {
public void doFilter(ServletRequest request, ServletResponse response,
FilterChain chain) throws IOException, ServletException {
HttpServletRequest httpRequest = (HttpServletRequest) request;
SystemContext.setOffset(getOffset(httpRequest));
SystemContext.setPagesize(getPagesize(httpRequest));
try {
chain.doFilter(request, response);
} finally {
// 必须清理,否则线程复用(Tomcat 线程池)会串数据
SystemContext.removeOffset();
SystemContext.removePagesize();
}
}
protected int getOffset(HttpServletRequest request) {
int offset = 0;
try {
offset = Integer.parseInt(request.getParameter("pager.offset"));
} catch (NumberFormatException ignore) { }
return offset;
}
protected int getPagesize(HttpServletRequest request) {
return 10; // 每页固定 10 条,可改为读配置或请求参数
}
}
为什么一定要 finally 里 remove? Web 容器的线程是池化复用的,ThreadLocal 不清理会让上一次请求的分页参数泄漏到下一次请求,表现为"莫名其妙翻到了第 7 页"。
1.5 AbstractManager:一次封装,处处复用
public class AbstractManager extends HibernateDaoSupport {
public PagerModel searchPaginated(String hql) {
return searchPaginated(hql, null,
SystemContext.getOffset(), SystemContext.getPagesize());
}
public PagerModel searchPaginated(String hql, Object param) {
return searchPaginated(hql, new Object[]{param},
SystemContext.getOffset(), SystemContext.getPagesize());
}
public PagerModel searchPaginated(String hql, Object[] params) {
return searchPaginated(hql, params,
SystemContext.getOffset(), SystemContext.getPagesize());
}
public PagerModel searchPaginated(String hql, Object[] params,
int offset, int pagesize) {
// 1. 查总数
String countHql = getCountQuery(hql);
Query query = getSession().createQuery(countHql);
if (params != null && params.length > 0) {
for (int i = 0; i < params.length; i++) query.setParameter(i, params[i]);
}
int total = ((Long) query.uniqueResult()).intValue();
// 2. 查当前页
query = getSession().createQuery(hql);
if (params != null && params.length > 0) {
for (int i = 0; i < params.length; i++) query.setParameter(i, params[i]);
}
query.setFirstResult(offset);
query.setMaxResults(pagesize);
List datas = query.list();
PagerModel pm = new PagerModel();
pm.setTotal(total);
pm.setDatas(datas);
return pm;
}
/** 把 "select ... from Xxx x where ..." 转成 "select count(*) from Xxx x where ..." */
private String getCountQuery(String hql) {
int index = hql.indexOf("from");
if (index != -1) {
return "select count(*) " + hql.substring(index);
}
throw new SystemException("无效的HQL查询语句!");
}
}
于是业务方法退化成一行:
public PagerModel findOrgs(int parentId) {
if (parentId == 0) {
return searchPaginated("from Organization o where o.parent is null");
}
return searchPaginated("from Organization o where o.parent.id = ?", parentId);
}
重构前后对比:
| 重构前 | 重构后 | |
|---|---|---|
| 业务方法签名 | findOrgs(int parentId, int offset, int pagesize) |
findOrgs(int parentId) |
| Action 职责 | 计算 offset/pagesize 并传参 | 只调方法 |
| 新增查询 | 每个都要写 count 查询 | 直接复用 searchPaginated |
1.6 页面端:pager-taglib
<pg:pager url="org.do" items="${pm.total}" export="currentPageNumber=pageNumber">
<pg:param name="parentId"/> <!-- 翻页时保持 parentId 参数 -->
<pg:first><a href="${pageUrl}">首页</a></pg:first>
<pg:prev><a href="${pageUrl}">前页</a></pg:prev>
<pg:pages>
<c:choose>
<c:when test="${currentPageNumber eq pageNumber}">
<font color="red">${pageNumber}</font>
</c:when>
<c:otherwise><a href="${pageUrl}">${pageNumber}</a></c:otherwise>
</c:choose>
</pg:pages>
<pg:next><a href="${pageUrl}">后页</a></pg:next>
<pg:last><a href="${pageUrl}">尾页</a></pg:last>
</pg:pager>
url填的是 Action 路径(不带.do后缀由 taglib 处理,按实际配置来)items="${pm.total}"传总记录数- 需要跨页保留的参数用
<pg:param name="xxx"/>
二、OpenSessionInView:解决懒加载的"Session 已关闭"
Hibernate 的关联对象默认是懒加载的。业务方法返回后事务结束、Session 关闭,JSP 里再去取 org.children 就会抛 LazyInitializationException。
解决办法是把 Session 的关闭推迟到一次请求渲染完毕:
<filter>
<filter-name>hibernateFilter</filter-name>
<filter-class>org.springframework.orm.hibernate3.support.OpenSessionInViewFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>hibernateFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
需要注意:
- 该 Filter 必须放在
pagerFilter之前还是之后没有硬性要求,但一定要在业务调用之前生效,所以映射/*即可。 - 开启后,JSP 里的懒加载会触发额外 SQL(N+1 问题),列表页建议用显式
fetch join或批量抓取优化。 - 它只是把 Session 打开,不带事务;写操作仍由
txAdvice管理。
三、字符编码过滤器
老版本 Tomcat + MySQL 环境下,中文乱码是最常见的问题。统一在 Filter 层解决:
<filter>
<filter-name>Spring character encoding filter</filter-name>
<filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
<init-param><param-name>encoding</param-name><param-value>GBK</param-value></init-param>
</filter>
<filter-mapping>
<filter-name>Spring character encoding filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
配套还要做三件事:
- JSP 页面头部声明
<%@ page contentType="text/html;charset=GBK" %>; - MySQL 连接串加参数:
jdbc:mysql://127.0.0.1/oa?useUnicode=true&characterEncoding=GBK; - 数据库本身字符集一致(老版本 MySQL 可在
my.ini设default-character-set=gb2312)。
四、统一异常处理
4.1 SystemException:带错误码的业务异常
public class SystemException extends RuntimeException {
private String key; // 对应资源文件中的 key
private Object[] values; // 消息占位符参数
public SystemException(String message) { super(message); }
public SystemException(String message, String key) { super(message); this.key = key; }
public SystemException(String message, String key, Object value) {
super(message); this.key = key; this.values = new Object[]{value};
}
public SystemException(String message, String key, Object[] values) { ... }
}
业务代码里这样抛:
if (org.getChildren().size() > 0) {
throw new SystemException("存在子机构,不允许删除", "exception.org.del", org.getId());
}
第一个参数是开发调试用的明文,第二个是国际化 key,第三个是填充占位符的值。这样既方便排查,又能向用户展示友好且可本地化的提示。
4.2 SystemExceptionHandler:一处兜底
public class SystemExceptionHandler extends ExceptionHandler {
private static Log logger = LogFactory.getLog(SystemExceptionHandler.class);
@Override
public ActionForward execute(Exception ex, ExceptionConfig ae, ActionMapping mapping,
ActionForm formInstance, HttpServletRequest request,
HttpServletResponse response) throws ServletException {
ActionForward forward = ae.getPath() != null
? new ActionForward(ae.getPath())
: mapping.getInputForward();
logger.debug("出现异常", ex); // 记录日志,但不在页面上暴露堆栈
if (ex instanceof SystemException) {
SystemException se = (SystemException) ex;
ActionMessage error = se.getKey() == null
? new ActionMessage(ae.getKey(), se.getMessage())
: (se.getValues() != null
? new ActionMessage(se.getKey(), se.getValues())
: new ActionMessage(se.getKey()));
this.storeException(request, se.getKey(), error, forward, ae.getScope());
return forward;
}
return super.execute(ex, ae, mapping, formInstance, request, response);
}
}
在 struts-config.xml 里注册为全局异常处理(见《SSH 环境搭建与工程结构》),此后所有 Action 都不需要写 try-catch。
异常页 common/exception.jsp 用 <html:errors/> 输出消息即可。
五、日期类型转换
Struts 默认无法把 2026-10-25 这样的字符串转成 java.util.Date,需要注册 Converter:
public class UtilDateConverter implements Converter {
private static SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
public Object convert(Class type, Object value) {
if (value == null) return value;
if (value instanceof Date) return value;
if (value instanceof String) {
try { return format.parse((String) value); }
catch (ParseException e) { e.printStackTrace(); }
}
return null;
}
}
注册要赶在第一次请求之前完成,所以用一个 load-on-startup 的 Servlet:
public class UtilDateConverterInitServlet extends HttpServlet {
@Override
public void init() throws ServletException {
ConvertUtils.register(new UtilDateConverter(), Date.class);
}
}
<servlet>
<servlet-name>utilDateConverter</servlet-name>
<servlet-class>com.oa.web.UtilDateConverterInitServlet</servlet-class>
<load-on-startup>3</load-on-startup>
</servlet>
ConvertUtils.register是全局静态注册,也可以改成带init()的 ActionServlet 插件或ServletContextListener,效果一样。
六、日志
log4j.properties 放在类路径根即可。建议的分级策略:
log4j.rootLogger=INFO, stdout, file
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n
log4j.appender.file=org.apache.log4j.RollingFileAppender
log4j.appender.file.File=${catalina.home}/logs/oa.log
log4j.appender.file.MaxFileSize=10MB
log4j.appender.file.MaxBackupIndex=10
log4j.appender.file.layout=org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern=%d %-5p %c - %m%n
# 调试期打开:看 Hibernate SQL
log4j.logger.org.hibernate.SQL=DEBUG
log4j.logger.org.hibernate.type=TRACE
# jBPM 日志较多,可单独调高
log4j.logger.org.jbpm=INFO
几个约定:
- 业务异常用
logger.debug/warn,不要printStackTrace(); - 调试期打开
show_sql,上线关闭; - 抛异常时带上业务标识(如机构 ID),方便排查。
七、小结
| 设施 | 解决的问题 | 关键类/配置 |
|---|---|---|
| 分页封装 | 分页参数污染业务接口 | PagerModel + SystemContext + PagerFilter + AbstractManager |
| 视图层 Session | 懒加载 LazyInitializationException |
OpenSessionInViewFilter |
| 编码 | 中文乱码 | CharacterEncodingFilter + 连接串 + 页面声明 |
| 异常 | 到处 try-catch、堆栈暴露给用户 | SystemException + SystemExceptionHandler + global-exceptions |
| 类型转换 | 日期字符串转 Date 失败 | UtilDateConverter + UtilDateConverterInitServlet |
| 日志 | 线上无迹可寻 | log4j.properties 分级输出 |
要点小结
- Hibernate 的关联对象默认是懒加载的。
-
- 它只是把 Session 打开,不带事务
- 老版本 Tomcat + MySQL 环境下,中文乱码是最常见的问题。
- Struts 默认无法把
2026-10-25这样的字符串转成java.util.Date,需要注册Converter: ```java public c…
由站内小编编辑整理