JavaEE项目全局异常处理实战：从Filter到ExceptionMapper的演进

我发现很多同学做JavaEE项目时，异常处理还停留在“每个Service方法都try-catch，每个Controller方法都自己处理异常”的阶段。代码里充斥着重复的错误处理逻辑，一旦业务规则调整，所有方法的异常响应格式都要跟着改一遍，维护起来苦不堪言。更麻烦的是，DAO层抛出的异常、Service层封装后的异常、Controller层拦截到的异常，它们的处理方式各不相同，返回给前端的结构很难统一，测试同学每次都要针对不同情况写不同的断言。

全局异常处理解决的就是这个问题：把“捕获异常”和“响应异常”的职责从业务代码里剥离出来，集中在一个地方统一处理。JavaEE生态和流行的Spring全家桶不同，它没有Spring Boot里那种@RestControllerAdvice的便捷注解，需要我们基于Servlet规范和JAX-RS规范自己动手。我梳理了一条从传统Filter拦截到ExceptionMapper映射的演进路径，每一步都踩过坑，今天把实战过程完整分享一下。

1. 内容整体设计与思路拆解

1.1 为什么需要独立的全局异常处理层

先看一个典型的传统写法。假设现在要设计一个用户注册接口，没有全局异常处理时，代码大概长这样：

@WebServlet("/api/user/register") public class RegisterServlet extends HttpServlet { protected void doPost(HttpServletRequest req, HttpServletResponse resp) { try { String username = req.getParameter("username"); UserService service = new UserService(); service.register(username); resp.setStatus(HttpServletResponse.SC_OK); resp.getWriter().write("{\"code\": 0, \"msg\": \"success\"}"); } catch (UserAlreadyExistsException e) { resp.setStatus(HttpServletResponse.SC_CONFLICT); resp.getWriter().write("{\"code\": 1001, \"msg\": \"用户已存在\"}"); } catch (IllegalArgumentException e) { resp.setStatus(HttpServletResponse.SC_BAD_REQUEST); resp.getWriter().write("{\"code\": 1002, \"msg\": e.getMessage()}"); } catch (Exception e) { resp.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR); resp.getWriter().write("{\"code\": 500, \"msg\": \"系统异常\"}"); } } }

这段代码的问题一眼就能看出来：第一，每个Servlet都要重复写这一套catch逻辑，一个系统如果有几十个接口，就是几十份重复代码。第二，业务异常和系统异常混在同一个catch块里，日志打点散落各处，排障时只能靠人工搜索关键词。第三，一旦前端要求把响应结构从{"code":0,"msg":"success"}改成{"code":"OK","message":"success","data":null}，所有Servlet都得改一遍，漏改一个地方，联调就出问题。

把异常处理抽成独立层次之后，业务代码里不再有任何try-catch，异常向上抛出，由统一的地方决定“怎么响应、记什么日志、返回什么状态码”。这符合单一职责原则：业务方法只关心业务逻辑，异常处理层只关心异常翻译和响应输出。结合它的演进过程来看，不同的实现方案带来的收益差别也很明显。

1.2 三条技术路线的取舍分析

针对JavaEE项目，全局异常处理有三种常见实现路线：

这三条路线的核心差别在异常捕获的位置和粒度。Filter的方案是在最外层包裹全部请求，好处是不管底层是Servlet、Filter还是JAX-RS资源方法，只要异常冒泡到Filter就能统一处理。坏处是它拿不到被调用方法的具体元数据，比如某个资源方法上打的业务注解、方法参数等信息，想要针对特定异常做差异化处理时比较吃力。

JAX-RS的ExceptionMapper则是注册在JAX-RS运行时内部的映射器，当资源方法抛出的异常会被运行时捕获，然后按照异常类型匹配最合适的ExceptionMapper来处理。这种方式能够拿到完整的资源方法上下文，可以精准定制“某类异常返回什么样的响应结构、什么样的HTTP状态码”，在REST接口场景下是最优雅的。

至于web.xml错误页配置，定位在“页面级”的错误展示，适合用户直接访问JSP页面报错时给出一个友好的错误页，不适合做JSON接口的异常响应。

基于这个对比，我的做法是：线上项目如果是纯REST接口，直接用ExceptionMapper；如果老项目里面既有Servlet也有JAX-RS资源，先用Filter兜底，再用ExceptionMapper精细化处理，两种结合。接下来详细拆解每一步的细节。

2. 核心细节解析与实操要点

2.1 设计一套统一的异常响应结构

不管用什么方案，先要定义一套统一的异常响应结构，让前端不管是登录失败、参数校验失败还是服务器内部错误，都能用同一套格式解析。我习惯用下面这个结构：

{ "code": 1001, "message": "用户已存在", "path": "/api/user/register", "timestamp": 1733456789012, "traceId": "8f3a2b1c-6d4e-4f0a-9c2b-5e6d7f8a9b0c" }

字段含义：

• code：业务错误码，用于前端逻辑分支判断。0表示成功，非0表示各种业务异常。不要直接用HTTP状态码当业务码，因为HTTP状态码只有几十个标准值，业务错误码需要更精细。
• message：给用户看的提示文案。注意这里不能直接把异常堆栈返回给前端，否则会暴露内部实现细节，属于安全隐患。
• path：当前请求的URI，便于前端定位是哪个接口报错。
• timestamp：毫秒时间戳。
• traceId：链路追踪ID，这个字段非常重要，后面排查问题全靠它。

有了这个结构，还要配套一个自定义异常基类：

public class BusinessException extends RuntimeException { private final int code; private final String message; public BusinessException(int code, String message) { super(message); this.code = code; this.message = message; } public int getCode() { return code; } @Override public String getMessage() { return message; } }

所有业务异常都继承BusinessException，例如：

public class UserAlreadyExistsException extends BusinessException { public UserAlreadyExistsException() { super(1001, "用户已存在"); } } public class InvalidParamException extends BusinessException { public InvalidParamException(String message) { super(1002, message); } }

2.2 设计错误码枚举与异常映射表

错误码不建议散落在一个个魔法数字里，而是统一维护在一张枚举里。我见过很多项目，错误码定义在各自的常量类中，1001在A模块表示“用户已存在”，在B模块又表示“订单已取消”，排查问题时跨模块沟通成本极高。维护一张全局错误码映射表是更靠谱的做法：

错误码分段的规则可以是：通用错误码用1000~1999，用户模块用2000~2999，订单模块用3000~3999，支付模块用4000~4999，系统级错误用5000~5999。规范一旦确定，前后端都要遵守，新增错误码必须走评审，避免重复和歧义。

对应这个映射关系，可以设计一个枚举类：

public enum ErrorCode { USER_EXISTS(1001, "用户已存在", 409), INVALID_PARAM(1002, "参数不合法", 400), UNAUTHORIZED(1003, "认证失败", 401), FORBIDDEN(1004, "权限不足", 403), NOT_FOUND(1005, "资源不存在", 404), RATE_LIMITED(1007, "操作过于频繁", 429), INTERNAL_ERROR(5000, "系统内部异常", 500); private final int code; private final String message; private final int httpStatus; ErrorCode(int code, String message, int httpStatus) { this.code = code; this.message = message; this.httpStatus = httpStatus; } // getter... }

有了这个枚举，ExceptionMapper里做异常映射时就不用每个异常单独写一坨代码。

2.3 基于业务场景的日志与监控埋点

全局异常处理不只是返回一个JSON响应，更重要的是在捕获异常的同时记录足够的日志上下文。我见过太多线上事故，报错信息只有一行NullPointerException，连是哪个接口、哪个参数为空都看不出来。要做好异常处理，第一部分就是日志埋点。

建议在全局异常处理层统一完成以下日志工作：

• 打印完整的异常堆栈，级别为ERROR。
• 记录请求路径、请求方法、请求参数（注意脱敏，密码、令牌等敏感字段不要打）。
• 记录当前登录用户ID（如果有）。
• 记录traceId。
• 记录耗时。

基于这个思路，日志输出格式可以统一成这样：

ERROR [http-nio-8080-exec-8] [8f3a2b1c-6d4e-4f0a-9c2b-5e6d7f8a9b0c] 【全局异常】uri=/api/user/register method=POST userId=10086 cost=35ms 业务异常: code=1001, msg=用户已存在 java.lang.RuntimeException: 用户已存在 at com.example.service.UserService.register(UserService.java:58) ...

这样的日志在排查问题时价值极大，一行就能定位到接口、用户、耗时和异常类型。

3. 实操过程与核心环节实现

3.1 方案一：Filter方式——最外层兜底

先说一下Filter方案的实现。Filter是Servlet规范里的标准组件，在请求进入Servlet之前执行，在响应返回客户端之前也可以拦截。用Filter做全局异常处理的思路是：用一个Filter包裹整个请求链路，在doFilter方法外层的try-catch捕获所有异常。

一个基础版本的实现长这样：

@WebFilter("/*") public class ExceptionFilter implements Filter { private static final ObjectMapper MAPPER = new ObjectMapper(); @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest req = (HttpServletRequest) request; HttpServletResponse resp = (HttpServletResponse) response; long start = System.currentTimeMillis(); try { chain.doFilter(req, resp); } catch (BusinessException e) { handleBusinessException(req, resp, e, start); } catch (Exception e) { handleException(req, resp, e, start); } } private void handleBusinessException(HttpServletRequest req, HttpServletResponse resp, BusinessException e, long start) throws IOException { writeErrorResponse(req, resp, e.getCode(), e.getMessage(), e, start); } private void handleException(HttpServletRequest req, HttpServletResponse resp, Exception e, long start) throws IOException { writeErrorResponse(req, resp, 5000, "系统内部异常", e, start); } private void writeErrorResponse(HttpServletRequest req, HttpServletResponse resp, int code, String message, Exception e, long start) throws IOException { // 关键：保证响应编码统一，避免中文乱码 resp.setCharacterEncoding("UTF-8"); resp.setContentType("application/json;charset=UTF-8"); resp.setStatus(resolveHttpStatus(code)); String traceId = UUID.randomUUID().toString(); ErrorResponse body = new ErrorResponse(code, message, req.getRequestURI(), System.currentTimeMillis(), traceId); LOGGER.error("【全局异常】uri={} method={} cost={}ms，业务code={}，msg={}", req.getRequestURI(), req.getMethod(), System.currentTimeMillis() - start, code, message, e); if (!resp.isCommitted()) { resp.getWriter().write(MAPPER.writeValueAsString(body)); } } }

这里有几个细节需要注意。

Filter方式能捕获到Servlet和Service层抛出的异常，但有个坑：如果异常发生在RESTEasy或Jersey这类JAX-RS框架内部，而Filter在JAX-RS的前置链之外，需要确认Filter的执行顺序。如果Filter注册在JAX-RS的DispatcherServlet之前，那么它包裹的是整个Servlet，可以捕获所有异常。但如果某个JAX-RS框架内部自己处理了异常，Filter可能拿不到。这种情况下，单用Filter不够，需要配合ExceptionMapper。

另外，resp.isCommitted()这个判断很重要。如果响应已经提交给客户端了，这时候再写数据会报IllegalStateException。在高并发下响应流已经部分写出时，全局异常处理层要做的只是记录日志，不要再试图修改响应。

Filter方案还可以做一件事：统一给响应头注入CORS跨域配置、XSS防护头等安全响应头。顺手把这些通用逻辑也放在这里，这个Filter的价值就更大了。

3.2 方案二：ExceptionMapper——精细化异常映射

如果项目使用JAX-RS开发REST接口，比如基于Jersey或RESTEasy，那么更优雅的方案是使用ExceptionMapper。这是JAX-RS规范专门用来处理异常映射的机制。它的原理是：JAX-RS运行时捕获到资源方法抛出的异常后，会根据异常类型找到与之匹配的ExceptionMapper实现，调用其toResponse方法生成响应。

先看一个最简单的mapper：

@Provider public class BusinessExceptionMapper implements ExceptionMapper<BusinessException> { @Override public Response toResponse(BusinessException exception) { ErrorResponse body = new ErrorResponse( exception.getCode(), exception.getMessage(), "/api/unknown", System.currentTimeMillis(), TraceIdHolder.get() ); return Response.status(exception.getHttpStatus()) .entity(body) .type(MediaType.APPLICATION_JSON_TYPE) .build(); } }

这里有一个关键点：ExceptionMapper<BusinessException>中的泛型参数决定了它能处理哪些异常。运行时匹配时，如果有多个mapper都能处理同一个异常，JAX-RS会找最具体的那个。比如UserAlreadyExistsException继承自BusinessException，同时为这两个异常都定义了mapper，那么抛UserAlreadyExistsException时，会优先使用针对该异常类的mapper。

再看一个处理通用异常的mapper：

@Provider public class GenericExceptionMapper implements ExceptionMapper<Throwable> { private static final Logger LOGGER = LoggerFactory.getLogger(GenericExceptionMapper.class); @Override public Response toResponse(Throwable exception) { // 由于某些框架异常可能会被包装，需要先解开最内层的异常 Throwable cause = exception; while (cause.getCause() != null && cause.getCause() != cause) { cause = cause.getCause(); } LOGGER.error("【全局异常】未捕获异常: ", exception); ErrorResponse body = new ErrorResponse( 5000, "系统内部异常", UriHolder.getRequestUri(), System.currentTimeMillis(), TraceIdHolder.get() ); return Response.status(Response.Status.INTERNAL_SERVER_ERROR) .entity(body) .type(MediaType.APPLICATION_JSON_TYPE) .build(); } }

注意Throwable这个泛型，它的含义是“兜底mapper”，任何没有匹配到更具体mapper的异常都会落到这里。所以一个成熟的JAX-RS项目，必须至少有一个ExceptionMapper<Throwable>，否则会有大量异常逃出JAX-RS运行时，以一种不可控的方式返回给客户端。

在JAX-RS的toResponse方法里，拿到的是异常对象，但默认拿不到当前请求的URI、Header、用户信息等上下文。为了在异常处理层记录这些信息，需要借助JAX-RS的@Context注入，不过不同版本的JAX-RS注入方式有差异。Jersey 2.x中可以用@Context UriInfo，但ExceptionMapper本身是否能注入UriInfo取决于实现。所以在实际架构中，我更倾向用一套拦截器把请求上下文放进ThreadLocal和MDC里，然后ExceptionMapper从ThreadLocal中取。

3.3 请求上下文统一维护ThreadLocal与TraceId

前面已经两处提到TraceIdHolder和UriHolder，这个设计很关键。实现思路是：在Filter或JAX-RS的ContainerRequestFilter中，为每个请求生成或透传traceId，并把它绑定到当前线程的MDC中。日志框架的MDC自动把traceId附带在每行日志里，排障效率会大幅提升。

先看traceId的来源规则：

• 如果前端传了X-Request-Id请求头，沿用这个值做traceId，便于前后端日志关联。
• 如果前端没传，后端生成一个UUID。
• 在响应头里把traceId带回去，前端把traceId展示在错误提示里，用户上报问题时就能直接定位。

核心实现：

@WebFilter("/*") public class TraceIdFilter implements Filter { private static final String TRACE_ID_HEADER = "X-Request-Id"; private static final String TRACE_ID_MDC_KEY = "traceId"; @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest req = (HttpServletRequest) request; HttpServletResponse resp = (HttpServletResponse) response; String traceId = req.getHeader(TRACE_ID_HEADER); if (StringUtils.isBlank(traceId) || traceId.length() > 64) { traceId = UUID.randomUUID().toString().replace("-", ""); } MDC.put(TRACE_ID_MDC_KEY, traceId); resp.setHeader(TRACE_ID_HEADER, traceId); TraceIdHolder.set(traceId); try { chain.doFilter(req, resp); } finally { MDC.remove(TRACE_ID_MDC_KEY); TraceIdHolder.clear(); } } }

MDC的操作必须在finally中清理，否则线程池复用时traceId会串到下一个请求上，日志就全乱了。这个坑我踩过，排查了半天才发现是MDC没清理导致的“串线程”问题。

除了traceId，请求URI、用户ID等信息也要放进一个ThreadLocal对象里，统一管理：

public class RequestContext { private static final ThreadLocal<Context> HOLDER = new ThreadLocal<>(); public static void init(String uri, String method, Long userId) { Context ctx = new Context(uri, method, userId); HOLDER.set(ctx); } public static Context get() { return HOLDER.get(); } public static void clear() { HOLDER.remove(); } public static class Context { private final String uri; private final String method; private final Long userId; // constructor, getter... } }

这里用的是ThreadLocal，但要注意：在异步Servlet、线程池、异步JAX-RS场景下，ThreadLocal变量是无法跨线程传递的。如果需要支持异步处理，就得考虑使用TransmittableThreadLocal或者把traceId显式传递到异步线程中。这是我这几年遇到的最隐蔽的问题之一，希望各位尽量提前注意。

3.4 配合Filter链式处理与链上优先级控制

实际项目里，一个请求会经过多个Filter，每个Filter关注的点不同。以我最近接手的一个支付网关项目为例，它的Filter链顺序是这样的：

1. TraceIdFilter：生成/透传traceId
2. CorsFilter：处理跨域
3. AuthFilter：登录态校验
4. RateLimitFilter：限流
5. ExceptionFilter：异常兜底

关键点：ExceptionFilter要在所有Filter的最外层，或者放在所有可能抛出异常的业务型Filter后面。如果在AuthFilter里抛出了未登录异常，而ExceptionFilter放在AuthFilter前面，异常就无法被捕获到。所以我在项目里把ExceptionFilter放在Filter链的最后一个位置（即最早执行），确保它能包裹住后面所有Filter。

但这样又带来另一个问题：如果ExceptionFilter在链条最外层，它如何知道某个异常是哪个Filter抛出的？其实不需要知道，因为Filter抛出的异常会向上冒泡，在ExceptionFilter里捕获的是整个链路中冒泡上来的第一个异常。这个位置靠前一点，反而能捕获更多类型的异常。

还有一个细节：某些Filter可能自己内部处理了异常，没有往上层抛，这时ExceptionFilter永远捕获不到。比如AuthFilter如果自己catch了异常并直接返回401 JSON，那ExceptionFilter只需要处理真正的系统异常，业务异常已经由AuthFilter处理了。这不算错误设计，但要注意保持一致性，不要让“模块内处理一部分、全局处理一部分”的边界模糊。

在设计Filter链时，建议明确列出每个Filter的职责边界：

3.5 集成RESTEasy/Jersey时的注册配置细节

如果你用的是JAX-RS实现框架，要注意注册ExceptionMapper的方式。不同框架的注册方式略有不同：

RESTEasy中使用resteasy-jaxrs时，可以通过@Provider注解自动发现，或者通过Application子类手动注册：

@ApplicationPath("/api") public class RestApplication extends Application { @Override public Set<Class<?>> getClasses() { Set<Class<?>> classes = new HashSet<>(); classes.add(BusinessExceptionMapper.class); classes.add(GenericExceptionMapper.class); classes.add(ValidationExceptionMapper.class); classes.add(UserResource.class); return classes; } }

Jersey中类似，也是通过ResourceConfig扫描或注册：

public class JerseyConfig extends ResourceConfig { public JerseyConfig() { register(BusinessExceptionMapper.class); register(GenericExceptionMapper.class); register(ValidationExceptionMapper.class); packages("com.example.api"); } }

这里要特别提醒：用packages("com.example.api")自动扫描时，@Provider注解的类会被自动注册。但有时会因为包扫描范围不够，导致某个Mapper没被扫描到，运行时异常直接以默认HTML格式返回，前端拿到一个HTML页面会懵掉。所以改成显式注册会更可控——注册了哪些Mapper一目了然，出问题时也容易排查。

4. 常见问题与排查技巧实录

4.1 异常被JAX-RS框架“吞掉”，没进你的Mapper

这个问题是我在集成Jersey时遇到的。如果某个异常在进入你的ExceptionMapper之前，已经被JAX-RS运行时内部当作“不可映射异常”处理了，你的Mapper可能根本没机会执行。尤其当异常类型是WebApplicationException时，JAX-RS允许不经过任何mapper就直接生成响应。

解决办法：给WebApplicationException也注册一个mapper。虽然JAX-RS自带默认处理，但默认处理返回的结构不是你自定义的JSON格式。注册一个自定义mapper，把WebApplicationException也纳管：

@Provider public class WebApplicationExceptionMapper implements ExceptionMapper<WebApplicationException> { @Override public Response toResponse(WebApplicationException exception) { Response original = exception.getResponse(); int status = original.getStatus(); Object entity = original.getEntity(); // 构造统一格式的响应，保留原始status ErrorResponse body = new ErrorResponse( mapStatusToCode(status), resolveMessage(entity, status), UriHolder.getRequestUri(), System.currentTimeMillis(), TraceIdHolder.get() ); return Response.status(status) .entity(body) .type(MediaType.APPLICATION_JSON_TYPE) .build(); } }

mapStatusToCode是把HTTP状态码映射到业务错误码，比如404映射到1005，401映射到1003。resolveMessage是提取原始响应实体里的消息，优先用原始消息，原始实体不再打印的时候用默认文案兜底。

4.2 异步线程池里的异常无法被ExceptionMapper捕获

上面提到过：ExceptionMapper默认是同步处理的，如果你在资源方法里用了异步线程池（比如ExecutorService），子线程里抛出的异常不会回到JAX-RS运行时，更不会进入ExceptionMapper。实际表现是：接口返回成功，但后台日志里躺着一条未被处理的异常。

场景示例：

@GET @Path("/async-job/{id}") public Response submitJob(@PathParam("id") Long id) { executorService.submit(() -> { // 这里抛异常，无法被全局异常处理器捕获 process(id); }); return Response.accepted().build(); }

办法有两种。一种是把异常捕获范围放到异步任务内部，手动包一层，异常发生时记录日志并发送告警；另一种是使用JAX-RS的@Suspended和AsyncResponse，把异步结果回调给JAX-RS运行时处理。第二种做法可以让异常回到JAX-RS的异常处理链路，前提是你把AsyncResponse.resume(exception)调用的地方放到try-catch外面。

@GET @Path("/async-job/{id}") public void submitJob(@PathParam("id") Long id, @Suspended AsyncResponse asyncResponse) { executorService.submit(() -> { try { String result = process(id); asyncResponse.resume(result); } catch (Exception e) { asyncResponse.resume(e); // 异常回到JAX-RS运行时，交给ExceptionMapper } }); }

4.3 返回结构“串格式”：JSON和HTML互串

在Filter方式里，如果异常过滤器在某个Filter已经设置过响应的ContentType为HTML之后触发，那么响应头里的ContentType可能还是HTML，即使body里写的是JSON，前端解析也会报错。这个问题出现的频率比我预想的高得多。

原因在于：resp.setContentType("application/json;charset=UTF-8")只在响应未提交时有效，一旦响应提交了，再设置ContentType不会生效。所以全局异常过滤器通常放在最外层，能拿到还没提交的响应。如果发现响应已经提交，那么不建议继续写数据，只记录日志即可。

还有一种情况：Servlet容器里的web.xml配置了error-page重定向，异常发生时会走容器错误页逻辑，导致自定义的JSON响应被容器的错误页替换。解决办法是确保全局异常过滤器把异常全部吞掉后再返回，让容器认为没有异常发生；或者把error-page的location指定为一个JSON接口。

4.4 参数校验异常没有统一返回结构

JAX-RS里参数校验（Bean Validation）抛出的异常类型是ConstraintViolationException，它不会自动映射到你的BusinessExceptionMapper或GenericExceptionMapper，如果没有专门处理，则可能返回400但响应体是框架默认的格式。现象是业务错误码规则失效，body里是ConstraintViolationExceptionImpl之类的堆栈片段。

解决方法是注册一个专门的ConstraintViolationExceptionMapper：

@Provider public class ConstraintViolationExceptionMapper implements ExceptionMapper<ConstraintViolationException> { @Override public Response toResponse(ConstraintViolationException exception) { Set<ConstraintViolation<?>> violations = exception.getConstraintViolations(); List<String> messages = violations.stream() .map(v -> v.getPropertyPath() + ": " + v.getMessage()) .collect(Collectors.toList()); String message = messages.isEmpty() ? "参数校验失败" : String.join(", ", messages); ErrorResponse body = new ErrorResponse( 1002, message, UriHolder.getRequestUri(), System.currentTimeMillis(), TraceIdHolder.get() ); return Response.status(Response.Status.BAD_REQUEST) .entity(body) .type(MediaType.APPLICATION_JSON_TYPE) .build(); } }

4.5 常见问题速查表

4.6 分环境差异化处理

线上环境和本地开发环境的异常处理策略应该不同。本地开发时，全局异常处理层可以把完整异常堆栈直接放在响应体的detail字段里，方便前端联调和后端排查。线上环境则不要返回堆栈，只返回message和traceId。

实现方式是根据环境配置判断：

private ErrorResponse buildErrorResponse(int code, String message, Exception e) { ErrorResponse response = new ErrorResponse(code, message, uri, timestamp, traceId); if (ENV.isDev()) { response.setDetail(e.toString()); } return response; }

生产环境里不要试图把堆栈返回客户端，也别用printStackTrace，全部走日志框架，否则大量异常堆栈打在控制台，日志收集时会被刷屏，真正需要关注的信息反而被淹没。

5. 进阶实践：从单体异常处理到分布式异常追踪

5.1 全局异常处理与链路追踪的配合

JavaEE单体应用发展到分布式体系时，全局异常处理层除了返回统一格式的JSON，还要承担“把traceId透传到下游服务”的职责。这块在网关层、服务提供方、服务消费方各有一份实现，目标只有一个：一个请求从网关到下游多个服务，整条链路上使用的traceId是同一个。

在服务消费方，请求外发之前要取出MDC里的traceId，设置到HTTP头里：

String traceId = MDC.get("traceId"); if (StringUtils.isNotBlank(traceId)) { httpRequest.setHeader("X-Request-Id", traceId); }

在服务提供方，就是前面TraceIdFilter里的逻辑：优先读取X-Request-Id头，沿用而不是另生成。

一旦全链路都在透传同一个traceId，全局异常处理层打出的日志日志里就带着这条traceId，跳板机上输入traceId就能把整个链路的日志拉出来，排障效率天差地别。

5.2 告警策略与关键指标

全局异常处理层除了记录日志，还应该做指标统计。常见的统计维度包括：

• 每分钟异常捕获总数
• 各错误码占比
• 各类异常的发生趋势
• 异常发生时对应接口的耗时

用这些指标配合监控告警，可以对“异常突增”做出快速响应。比如平时每分钟异常捕获数在个位数，突然涨到几百，不需要等待用户反馈，告警已经发出来了。这一点在生产环境有巨大价值。

统计做法不复杂，用一个环形的计数器或直接在日志里打点：

LOGGER.info("【异常指标】uri={} code={} type={} cost={}ms", uri, code, exception.getClass().getSimpleName(), cost);

监控系统收集日志后按关键字聚合，就能画出异常趋势图。

5.3 万能兜底：最后一道防线

在设计全局异常处理时，有一个原则必须坚持：前端展示的友好错误信息可以缺失，但服务端绝对不能因为没有正确处理异常而崩溃或丢失日志。换句话说：全局异常处理层本身绝不能抛出异常。一旦它在处理异常时抛了新异常，原始异常信息可能丢失，响应也可能变成500空页面。

所以建议在所有Mapper和Filter的异常处理分支里再加一个最终保底：catch住所有Throwable，只记日志，返回最基础的错误结构。

try { writeErrorResponse(req, resp, code, message, e, start); } catch (Exception ex) { LOGGER.error("全局异常处理自身失败", ex); if (!resp.isCommitted()) { resp.setStatus(500); resp.setContentType("text/plain;charset=UTF-8"); resp.getWriter().write("{\"code\": 5000, \"message\": \"系统繁忙\"}"); } }

有人可能会说，写响应怎么可能失败？在真实运行环境下，连接被客户端断开、缓冲区溢出、字符编码不支持等原因都可能触发IO异常，不要让兜底逻辑变成“二次炸弹”。

5.4 一个完整的配置清单

项目里落地这套东西，建议按下面的清单自查：

6. 个人经验总结与扩展思路

实操做下来，我最深的感受是：全局异常处理不只是写几个Mapper类那么简单，它是一个系统性设计。体系一旦搭好，后续每新增一种异常类型，都只是加一个异常类和一个Mapper的问题，业务代码的整洁度会大幅提升。

有一个比较实用的扩展思路：如果项目已经使用Swagger/OpenAPI，可以让全局异常处理层把ErrorResponse结构自动注入到OpenAPI文档中。这样前端生成的SDK里，所有接口的错误响应结构就是同一个类型，联调时前端基本不会问“这个接口报错返回什么格式”这种问题。

另外一个方向是按微服务拆分错误码段。每个微服务模块有自己独立的错误码区间，网关做一次统一聚合，将内部错误码翻译成对客户端合适的错误码。这个工作做与不做，直接决定BFF层对接成本的高低。

多写一句：不要想着一口气引入过多“优雅”特性。先让Filter兜底跑起来，把统一响应结构固化下来，再引入ExceptionMapper精细控制，逐步演进。一个能跑、能排查、能告警的处理体系，比文档里再优美的设计，都更有价值。