作者:不想打工的码农
原创声明:本文基于个人三年企业级项目踩坑经验整理,代码经生产环境验证,转载请注明出处
一、痛点开场:那个深夜加班的我
上周五晚上9点,测试同事甩来一张截图:“用户注册接口返回500,前端白屏了!”
我揉着发胀的太阳穴点开日志——NullPointerException at UserService.java:87。
更扎心的是:异常堆栈直接暴露在前端,用户看到满屏红色错误,而运维根本不知道具体哪台服务器出问题。
作为经历过三个JavaEE项目迭代的老码农,我彻底受够了这种“异常裸奔”状态。今天,就和大家聊聊如何在纯JavaEE(Servlet 3.1+)项目中构建健壮的全局异常处理体系。不吹不黑,全是实战干货。
二、为什么Filter方案是“保底王牌”?
很多同学第一反应是“用Spring的@ControllerAdvice啊”。但现实很骨感:
- 老旧系统用WebLogic+纯Servlet
- 客户要求零第三方框架依赖
- 安全审计禁止异常信息外泄
此时,Servlet Filter 就是你的终极武器。它位于请求链最外层,能捕获所有未处理异常(包括Filter链自身异常)。
核心代码(已脱敏优化):
@WebFilter(filterName = "GlobalExceptionFilter", urlPatterns = "/*")
public class GlobalExceptionFilter implements Filter {
private static final Logger log = LoggerFactory.getLogger(GlobalExceptionFilter.class);
@Override
public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
throws IOException, ServletException {
HttpServletRequest request = (HttpServletRequest) req;
HttpServletResponse response = (HttpServletResponse) res;
try {
chain.doFilter(request, response);
// 处理异步请求异常(关键!很多文章漏掉这点)
if (request.isAsyncStarted()) {
request.getAsyncContext().addListener(new AsyncListener() {
@Override
public void onComplete(AsyncEvent event) {}
@Override
public void onTimeout(AsyncEvent event) { handleAsyncException(event); }
@Override
public void onError(AsyncEvent event) { handleAsyncException(event); }
@Override
public void onStartAsync(AsyncEvent event) {}
});
}
} catch (Exception e) {
handleException(request, response, e);
}
}
private void handleException(HttpServletRequest req, HttpServletResponse res, Throwable ex) {
// 1. 安全脱敏:禁止将堆栈返回前端
String errorMsg = "服务繁忙,请稍后再试";
int statusCode = HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
// 2. 业务异常精细化处理(示例)
if (ex instanceof BusinessException) {
errorMsg = ex.getMessage();
statusCode = HttpServletResponse.SC_BAD_REQUEST;
} else if (ex instanceof AuthenticationException) {
errorMsg = "登录已过期";
statusCode = HttpServletResponse.SC_UNAUTHORIZED;
}
// 3. 关键:记录带上下文的日志(方便定位!)
String traceId = req.getHeader("X-Trace-Id"); // 链路追踪ID
log.error("[全局异常] TraceId:{}, URI:{}, Exception:{}",
traceId, req.getRequestURI(), ex.getMessage(), ex);
// 4. 统一JSON响应(注意字符编码!)
res.setStatus(statusCode);
res.setContentType("application/json;charset=UTF-8");
res.getWriter().write(String.format(
"{\\"code\\":%d,\\"msg\\":\\"%s\\",\\"traceId\\":\\"%s\\"}",
statusCode, errorMsg, traceId != null ? traceId : "N/A"
));
}
private void handleAsyncException(AsyncEvent event) {
try {
if (event.getThrowable() != null) {
// 复用主异常处理逻辑(避免重复造轮子)
handleException(
(HttpServletRequest) event.getSuppliedRequest(),
(HttpServletResponse) event.getSuppliedResponse(),
event.getThrowable()
);
}
} catch (Exception e) {
log.error("异步异常处理二次失败", e);
}
}
}
✨ 实战踩坑点:
三、进阶方案:JAX-RS的ExceptionMapper(RESTful项目首选)
如果你的项目基于JAX-RS(如Jersey、RESTEasy),ExceptionMapper是更优雅的选择——它符合Jakarta EE规范,与业务解耦度更高。
@Provider
public class GlobalExceptionMapper implements ExceptionMapper<Throwable> {
@Override
public Response toResponse(Throwable ex) {
ErrorResponse error = new ErrorResponse();
error.setTimestamp(System.currentTimeMillis());
error.setMessage("服务异常");
// 精细化分类
if (ex instanceof WebApplicationException) {
error.setCode(((WebApplicationException) ex).getResponse().getStatus());
error.setMessage(ex.getMessage());
} else if (ex instanceof PersistenceException) {
error.setCode(500);
error.setMessage("数据库操作失败");
log.error("DB异常", ex); // 单独记录
} else {
error.setCode(500);
log.error("未预期异常", ex);
}
return Response.status(error.getCode())
.entity(error)
.type(MediaType.APPLICATION_JSON)
.build();
}
// 内部类:统一响应结构
@XmlRootElement
public static class ErrorResponse {
private long timestamp;
private int code;
private String message;
// getter/setter…
}
}
✅ 优势:自动注册、类型安全、与资源类完全解耦
⚠️ 注意:需在web.xml或Application子类中启用扫描
四、方案对比与选型指南
表格
| Servlet Filter | 传统MVC/混合架构项目 | 全局覆盖、零框架依赖 | 代码侵入性稍强 |
| ExceptionMapper | 纯RESTful (JAX-RS)项目 | 规范优雅、解耦度高 | 仅处理JAX-RS异常 |
| web.xml error-page | 静态错误页跳转 | 配置简单 | 无法定制JSON响应 |
💡 个人建议:
- 新项目用JAX-RS + ExceptionMapper(拥抱规范)
- 老系统改造首选Filter(改动最小,见效最快)
- 永远不要在Controller里写try-catch返回错误(违背分层原则!)
五、血泪总结:三个必须坚守的原则
结语
写这篇文章时,窗外又飘起加班的夜雨。但想到明天测试同事不会再甩来“500错误”的截图,心里竟有丝欣慰。技术人的价值,不就是让系统更稳健、让协作更顺畅吗?
互动时间:
你在JavaEE项目中遇到过哪些异常处理的坑?
欢迎在评论区分享你的“救命方案”



