A
📖 知识库
🌐

通用基础设施:分页、异常与日志

📄 框架与环境 32 分钟阅读 98 次浏览 更新于 2026-10-25

导读

「通用基础设施:分页、异常与日志」常被追问到细节层面,这里把结论、原因和易错点一次讲清楚。

一个系统能不能写得舒服,取决于基础设施扎不扎实。本项目的"基础设施"只有四个小类: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>

配套还要做三件事:

  1. JSP 页面头部声明 <%@ page contentType="text/html;charset=GBK" %>;
  2. MySQL 连接串加参数:jdbc:mysql://127.0.0.1/oa?useUnicode=true&characterEncoding=GBK;
  3. 数据库本身字符集一致(老版本 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…

由站内小编编辑整理

相关条目