我發(fā)現(xiàn)很多同學(xué)做JavaEE項(xiàng)目時(shí)異常處理還停留在“每個(gè)Service方法都try-catch每個(gè)Controller方法都自己處理異常”的階段。代碼里充斥著重復(fù)的錯(cuò)誤處理邏輯一旦業(yè)務(wù)規(guī)則調(diào)整所有方法的異常響應(yīng)格式都要跟著改一遍維護(hù)起來(lái)苦不堪言。更麻煩的是DAO層拋出的異常、Service層封裝后的異常、Controller層攔截到的異常它們的處理方式各不相同返回給前端的結(jié)構(gòu)很難統(tǒng)一測(cè)試同學(xué)每次都要針對(duì)不同情況寫(xiě)不同的斷言。全局異常處理解決的就是這個(gè)問(wèn)題把“捕獲異?！焙汀绊憫?yīng)異?！钡穆氊?zé)從業(yè)務(wù)代碼里剝離出來(lái)集中在一個(gè)地方統(tǒng)一處理。JavaEE生態(tài)和流行的Spring全家桶不同它沒(méi)有Spring Boot里那種RestControllerAdvice的便捷注解需要我們基于Servlet規(guī)范和JAX-RS規(guī)范自己動(dòng)手。我梳理了一條從傳統(tǒng)Filter攔截到ExceptionMapper映射的演進(jìn)路徑每一步都踩過(guò)坑今天把實(shí)戰(zhàn)過(guò)程完整分享一下。1. 內(nèi)容整體設(shè)計(jì)與思路拆解1.1 為什么需要獨(dú)立的全局異常處理層先看一個(gè)典型的傳統(tǒng)寫(xiě)法。假設(shè)現(xiàn)在要設(shè)計(jì)一個(gè)用戶注冊(cè)接口沒(méi)有全局異常處理時(shí)代碼大概長(zhǎng)這樣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\: \系統(tǒng)異常\}); } } }這段代碼的問(wèn)題一眼就能看出來(lái)第一每個(gè)Servlet都要重復(fù)寫(xiě)這一套catch邏輯一個(gè)系統(tǒng)如果有幾十個(gè)接口就是幾十份重復(fù)代碼。第二業(yè)務(wù)異常和系統(tǒng)異?；煸谕粋€(gè)catch塊里日志打點(diǎn)散落各處排障時(shí)只能靠人工搜索關(guān)鍵詞。第三一旦前端要求把響應(yīng)結(jié)構(gòu)從{code:0,msg:success}改成{code:OK,message:success,data:null}所有Servlet都得改一遍漏改一個(gè)地方聯(lián)調(diào)就出問(wèn)題。把異常處理抽成獨(dú)立層次之后業(yè)務(wù)代碼里不再有任何try-catch異常向上拋出由統(tǒng)一的地方?jīng)Q定“怎么響應(yīng)、記什么日志、返回什么狀態(tài)碼”。這符合單一職責(zé)原則業(yè)務(wù)方法只關(guān)心業(yè)務(wù)邏輯異常處理層只關(guān)心異常翻譯和響應(yīng)輸出。結(jié)合它的演進(jìn)過(guò)程來(lái)看不同的實(shí)現(xiàn)方案帶來(lái)的收益差別也很明顯。1.2 三條技術(shù)路線的取舍分析針對(duì)JavaEE項(xiàng)目全局異常處理有三種常見(jiàn)實(shí)現(xiàn)路線方案適用場(chǎng)景侵入性是否推薦Filter包裹所有請(qǐng)求try-catch全鏈路老項(xiàng)目快速改造Servlet與JAX-RS混用低過(guò)渡可用JAX-RS ExceptionMapper純RESTful接口項(xiàng)目使用JAX-RS開(kāi)發(fā)低首選容器級(jí)配置與web.xml錯(cuò)誤頁(yè)傳統(tǒng)JSP項(xiàng)目頁(yè)面級(jí)錯(cuò)誤展示中頁(yè)面場(chǎng)景這三條路線的核心差別在異常捕獲的位置和粒度。Filter的方案是在最外層包裹全部請(qǐng)求好處是不管底層是Servlet、Filter還是JAX-RS資源方法只要異常冒泡到Filter就能統(tǒng)一處理。壞處是它拿不到被調(diào)用方法的具體元數(shù)據(jù)比如某個(gè)資源方法上打的業(yè)務(wù)注解、方法參數(shù)等信息想要針對(duì)特定異常做差異化處理時(shí)比較吃力。JAX-RS的ExceptionMapper則是注冊(cè)在JAX-RS運(yùn)行時(shí)內(nèi)部的映射器當(dāng)資源方法拋出的異常會(huì)被運(yùn)行時(shí)捕獲然后按照異常類(lèi)型匹配最合適的ExceptionMapper來(lái)處理。這種方式能夠拿到完整的資源方法上下文可以精準(zhǔn)定制“某類(lèi)異常返回什么樣的響應(yīng)結(jié)構(gòu)、什么樣的HTTP狀態(tài)碼”在REST接口場(chǎng)景下是最優(yōu)雅的。至于web.xml錯(cuò)誤頁(yè)配置定位在“頁(yè)面級(jí)”的錯(cuò)誤展示適合用戶直接訪問(wèn)JSP頁(yè)面報(bào)錯(cuò)時(shí)給出一個(gè)友好的錯(cuò)誤頁(yè)不適合做JSON接口的異常響應(yīng)?；谶@個(gè)對(duì)比我的做法是線上項(xiàng)目如果是純REST接口直接用ExceptionMapper如果老項(xiàng)目里面既有Servlet也有JAX-RS資源先用Filter兜底再用ExceptionMapper精細(xì)化處理兩種結(jié)合。接下來(lái)詳細(xì)拆解每一步的細(xì)節(jié)。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 設(shè)計(jì)一套統(tǒng)一的異常響應(yīng)結(jié)構(gòu)不管用什么方案先要定義一套統(tǒng)一的異常響應(yīng)結(jié)構(gòu)讓前端不管是登錄失敗、參數(shù)校驗(yàn)失敗還是服務(wù)器內(nèi)部錯(cuò)誤都能用同一套格式解析。我習(xí)慣用下面這個(gè)結(jié)構(gòu){ code: 1001, message: 用戶已存在, path: /api/user/register, timestamp: 1733456789012, traceId: 8f3a2b1c-6d4e-4f0a-9c2b-5e6d7f8a9b0c }字段含義code業(yè)務(wù)錯(cuò)誤碼用于前端邏輯分支判斷。0表示成功非0表示各種業(yè)務(wù)異常。不要直接用HTTP狀態(tài)碼當(dāng)業(yè)務(wù)碼因?yàn)镠TTP狀態(tài)碼只有幾十個(gè)標(biāo)準(zhǔn)值業(yè)務(wù)錯(cuò)誤碼需要更精細(xì)。message給用戶看的提示文案。注意這里不能直接把異常堆棧返回給前端否則會(huì)暴露內(nèi)部實(shí)現(xiàn)細(xì)節(jié)屬于安全隱患。path當(dāng)前請(qǐng)求的URI便于前端定位是哪個(gè)接口報(bào)錯(cuò)。timestamp毫秒時(shí)間戳。traceId鏈路追蹤ID這個(gè)字段非常重要后面排查問(wèn)題全靠它。有了這個(gè)結(jié)構(gòu)還要配套一個(gè)自定義異?；?lèi)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; } }所有業(yè)務(wù)異常都繼承BusinessException例如public class UserAlreadyExistsException extends BusinessException { public UserAlreadyExistsException() { super(1001, 用戶已存在); } } public class InvalidParamException extends BusinessException { public InvalidParamException(String message) { super(1002, message); } }2.2 設(shè)計(jì)錯(cuò)誤碼枚舉與異常映射表錯(cuò)誤碼不建議散落在一個(gè)個(gè)魔法數(shù)字里而是統(tǒng)一維護(hù)在一張枚舉里。我見(jiàn)過(guò)很多項(xiàng)目錯(cuò)誤碼定義在各自的常量類(lèi)中1001在A模塊表示“用戶已存在”在B模塊又表示“訂單已取消”排查問(wèn)題時(shí)跨模塊溝通成本極高。維護(hù)一張全局錯(cuò)誤碼映射表是更靠譜的做法錯(cuò)誤碼含義HTTP狀態(tài)碼所屬模塊1001用戶已存在409用戶模塊1002參數(shù)不合法400通用1003認(rèn)證失敗401通用1004權(quán)限不足403通用1005資源不存在404通用1006資源已鎖定423訂單模塊1007操作過(guò)于頻繁429通用5000系統(tǒng)內(nèi)部異常500通用錯(cuò)誤碼分段的規(guī)則可以是通用錯(cuò)誤碼用1000~1999用戶模塊用2000~2999訂單模塊用3000~3999支付模塊用4000~4999系統(tǒng)級(jí)錯(cuò)誤用5000~5999。規(guī)范一旦確定前后端都要遵守新增錯(cuò)誤碼必須走評(píng)審避免重復(fù)和歧義。對(duì)應(yīng)這個(gè)映射關(guān)系可以設(shè)計(jì)一個(gè)枚舉類(lèi)public enum ErrorCode { USER_EXISTS(1001, 用戶已存在, 409), INVALID_PARAM(1002, 參數(shù)不合法, 400), UNAUTHORIZED(1003, 認(rèn)證失敗, 401), FORBIDDEN(1004, 權(quán)限不足, 403), NOT_FOUND(1005, 資源不存在, 404), RATE_LIMITED(1007, 操作過(guò)于頻繁, 429), INTERNAL_ERROR(5000, 系統(tǒng)內(nèi)部異常, 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... }有了這個(gè)枚舉ExceptionMapper里做異常映射時(shí)就不用每個(gè)異常單獨(dú)寫(xiě)一坨代碼。2.3 基于業(yè)務(wù)場(chǎng)景的日志與監(jiān)控埋點(diǎn)全局異常處理不只是返回一個(gè)JSON響應(yīng)更重要的是在捕獲異常的同時(shí)記錄足夠的日志上下文。我見(jiàn)過(guò)太多線上事故報(bào)錯(cuò)信息只有一行NullPointerException連是哪個(gè)接口、哪個(gè)參數(shù)為空都看不出來(lái)。要做好異常處理第一部分就是日志埋點(diǎn)。建議在全局異常處理層統(tǒng)一完成以下日志工作打印完整的異常堆棧級(jí)別為ERROR。記錄請(qǐng)求路徑、請(qǐng)求方法、請(qǐng)求參數(shù)注意脫敏密碼、令牌等敏感字段不要打。記錄當(dāng)前登錄用戶ID如果有。記錄traceId。記錄耗時(shí)?；谶@個(gè)思路日志輸出格式可以統(tǒng)一成這樣ERROR [http-nio-8080-exec-8] [8f3a2b1c-6d4e-4f0a-9c2b-5e6d7f8a9b0c] 【全局異?！縰ri/api/user/register methodPOST userId10086 cost35ms 業(yè)務(wù)異常: code1001, msg用戶已存在 java.lang.RuntimeException: 用戶已存在 at com.example.service.UserService.register(UserService.java:58) ...這樣的日志在排查問(wèn)題時(shí)價(jià)值極大一行就能定位到接口、用戶、耗時(shí)和異常類(lèi)型。3. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)3.1 方案一Filter方式——最外層兜底先說(shuō)一下Filter方案的實(shí)現(xiàn)。Filter是Servlet規(guī)范里的標(biāo)準(zhǔn)組件在請(qǐng)求進(jìn)入Servlet之前執(zhí)行在響應(yīng)返回客戶端之前也可以攔截。用Filter做全局異常處理的思路是用一個(gè)Filter包裹整個(gè)請(qǐng)求鏈路在doFilter方法外層的try-catch捕獲所有異常。一個(gè)基礎(chǔ)版本的實(shí)現(xiàn)長(zhǎng)這樣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, 系統(tǒng)內(nèi)部異常, e, start); } private void writeErrorResponse(HttpServletRequest req, HttpServletResponse resp, int code, String message, Exception e, long start) throws IOException { // 關(guān)鍵保證響應(yīng)編碼統(tǒng)一避免中文亂碼 resp.setCharacterEncoding(UTF-8); resp.setContentType(application/json;charsetUTF-8); resp.setStatus(resolveHttpStatus(code)); String traceId UUID.randomUUID().toString(); ErrorResponse body new ErrorResponse(code, message, req.getRequestURI(), System.currentTimeMillis(), traceId); LOGGER.error(【全局異?！縰ri{} method{} cost{}ms業(yè)務(wù)code{}msg{}, req.getRequestURI(), req.getMethod(), System.currentTimeMillis() - start, code, message, e); if (!resp.isCommitted()) { resp.getWriter().write(MAPPER.writeValueAsString(body)); } } }這里有幾個(gè)細(xì)節(jié)需要注意。Filter方式能捕獲到Servlet和Service層拋出的異常但有個(gè)坑如果異常發(fā)生在RESTEasy或Jersey這類(lèi)JAX-RS框架內(nèi)部而Filter在JAX-RS的前置鏈之外需要確認(rèn)Filter的執(zhí)行順序。如果Filter注冊(cè)在JAX-RS的DispatcherServlet之前那么它包裹的是整個(gè)Servlet可以捕獲所有異常。但如果某個(gè)JAX-RS框架內(nèi)部自己處理了異常Filter可能拿不到。這種情況下單用Filter不夠需要配合ExceptionMapper。另外resp.isCommitted()這個(gè)判斷很重要。如果響應(yīng)已經(jīng)提交給客戶端了這時(shí)候再寫(xiě)數(shù)據(jù)會(huì)報(bào)IllegalStateException。在高并發(fā)下響應(yīng)流已經(jīng)部分寫(xiě)出時(shí)全局異常處理層要做的只是記錄日志不要再試圖修改響應(yīng)。Filter方案還可以做一件事統(tǒng)一給響應(yīng)頭注入CORS跨域配置、XSS防護(hù)頭等安全響應(yīng)頭。順手把這些通用邏輯也放在這里這個(gè)Filter的價(jià)值就更大了。3.2 方案二ExceptionMapper——精細(xì)化異常映射如果項(xiàng)目使用JAX-RS開(kāi)發(fā)REST接口比如基于Jersey或RESTEasy那么更優(yōu)雅的方案是使用ExceptionMapper。這是JAX-RS規(guī)范專(zhuān)門(mén)用來(lái)處理異常映射的機(jī)制。它的原理是JAX-RS運(yùn)行時(shí)捕獲到資源方法拋出的異常后會(huì)根據(jù)異常類(lèi)型找到與之匹配的ExceptionMapper實(shí)現(xiàn)調(diào)用其toResponse方法生成響應(yīng)。先看一個(gè)最簡(jiǎn)單的mapperProvider public class BusinessExceptionMapper implements ExceptionMapperBusinessException { 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(); } }這里有一個(gè)關(guān)鍵點(diǎn)ExceptionMapperBusinessException中的泛型參數(shù)決定了它能處理哪些異常。運(yùn)行時(shí)匹配時(shí)如果有多個(gè)mapper都能處理同一個(gè)異常JAX-RS會(huì)找最具體的那個(gè)。比如UserAlreadyExistsException繼承自BusinessException同時(shí)為這兩個(gè)異常都定義了mapper那么拋UserAlreadyExistsException時(shí)會(huì)優(yōu)先使用針對(duì)該異常類(lèi)的mapper。再看一個(gè)處理通用異常的mapperProvider public class GenericExceptionMapper implements ExceptionMapperThrowable { private static final Logger LOGGER LoggerFactory.getLogger(GenericExceptionMapper.class); Override public Response toResponse(Throwable exception) { // 由于某些框架異?？赡軙?huì)被包裝需要先解開(kāi)最內(nèi)層的異常 Throwable cause exception; while (cause.getCause() ! null cause.getCause() ! cause) { cause cause.getCause(); } LOGGER.error(【全局異常】未捕獲異常: , exception); ErrorResponse body new ErrorResponse( 5000, 系統(tǒng)內(nèi)部異常, UriHolder.getRequestUri(), System.currentTimeMillis(), TraceIdHolder.get() ); return Response.status(Response.Status.INTERNAL_SERVER_ERROR) .entity(body) .type(MediaType.APPLICATION_JSON_TYPE) .build(); } }注意Throwable這個(gè)泛型它的含義是“兜底mapper”任何沒(méi)有匹配到更具體mapper的異常都會(huì)落到這里。所以一個(gè)成熟的JAX-RS項(xiàng)目必須至少有一個(gè)ExceptionMapperThrowable否則會(huì)有大量異常逃出JAX-RS運(yùn)行時(shí)以一種不可控的方式返回給客戶端。在JAX-RS的toResponse方法里拿到的是異常對(duì)象但默認(rèn)拿不到當(dāng)前請(qǐng)求的URI、Header、用戶信息等上下文。為了在異常處理層記錄這些信息需要借助JAX-RS的Context注入不過(guò)不同版本的JAX-RS注入方式有差異。Jersey 2.x中可以用Context UriInfo但ExceptionMapper本身是否能注入U(xiǎn)riInfo取決于實(shí)現(xiàn)。所以在實(shí)際架構(gòu)中我更傾向用一套攔截器把請(qǐng)求上下文放進(jìn)ThreadLocal和MDC里然后ExceptionMapper從ThreadLocal中取。3.3 請(qǐng)求上下文統(tǒng)一維護(hù)ThreadLocal與TraceId前面已經(jīng)兩處提到TraceIdHolder和UriHolder這個(gè)設(shè)計(jì)很關(guān)鍵。實(shí)現(xiàn)思路是在Filter或JAX-RS的ContainerRequestFilter中為每個(gè)請(qǐng)求生成或透?jìng)鱰raceId并把它綁定到當(dāng)前線程的MDC中。日志框架的MDC自動(dòng)把traceId附帶在每行日志里排障效率會(huì)大幅提升。先看traceId的來(lái)源規(guī)則如果前端傳了X-Request-Id請(qǐng)求頭沿用這個(gè)值做traceId便于前后端日志關(guān)聯(lián)。如果前端沒(méi)傳后端生成一個(gè)UUID。在響應(yīng)頭里把traceId帶回去前端把traceId展示在錯(cuò)誤提示里用戶上報(bào)問(wèn)題時(shí)就能直接定位。核心實(shí)現(xiàn)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中清理否則線程池復(fù)用時(shí)traceId會(huì)串到下一個(gè)請(qǐng)求上日志就全亂了。這個(gè)坑我踩過(guò)排查了半天才發(fā)現(xiàn)是MDC沒(méi)清理導(dǎo)致的“串線程”問(wèn)題。除了traceId請(qǐng)求URI、用戶ID等信息也要放進(jìn)一個(gè)ThreadLocal對(duì)象里統(tǒng)一管理public class RequestContext { private static final ThreadLocalContext 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場(chǎng)景下ThreadLocal變量是無(wú)法跨線程傳遞的。如果需要支持異步處理就得考慮使用TransmittableThreadLocal或者把traceId顯式傳遞到異步線程中。這是我這幾年遇到的最隱蔽的問(wèn)題之一希望各位盡量提前注意。3.4 配合Filter鏈?zhǔn)教幚砼c鏈上優(yōu)先級(jí)控制實(shí)際項(xiàng)目里一個(gè)請(qǐng)求會(huì)經(jīng)過(guò)多個(gè)Filter每個(gè)Filter關(guān)注的點(diǎn)不同。以我最近接手的一個(gè)支付網(wǎng)關(guān)項(xiàng)目為例它的Filter鏈順序是這樣的TraceIdFilter生成/透?jìng)鱰raceIdCorsFilter處理跨域AuthFilter登錄態(tài)校驗(yàn)RateLimitFilter限流ExceptionFilter異常兜底關(guān)鍵點(diǎn)ExceptionFilter要在所有Filter的最外層或者放在所有可能拋出異常的業(yè)務(wù)型Filter后面。如果在AuthFilter里拋出了未登錄異常而ExceptionFilter放在AuthFilter前面異常就無(wú)法被捕獲到。所以我在項(xiàng)目里把ExceptionFilter放在Filter鏈的最后一個(gè)位置即最早執(zhí)行確保它能包裹住后面所有Filter。但這樣又帶來(lái)另一個(gè)問(wèn)題如果ExceptionFilter在鏈條最外層它如何知道某個(gè)異常是哪個(gè)Filter拋出的其實(shí)不需要知道因?yàn)镕ilter拋出的異常會(huì)向上冒泡在ExceptionFilter里捕獲的是整個(gè)鏈路中冒泡上來(lái)的第一個(gè)異常。這個(gè)位置靠前一點(diǎn)反而能捕獲更多類(lèi)型的異常。還有一個(gè)細(xì)節(jié)某些Filter可能自己內(nèi)部處理了異常沒(méi)有往上層拋這時(shí)ExceptionFilter永遠(yuǎn)捕獲不到。比如AuthFilter如果自己catch了異常并直接返回401 JSON那ExceptionFilter只需要處理真正的系統(tǒng)異常業(yè)務(wù)異常已經(jīng)由AuthFilter處理了。這不算錯(cuò)誤設(shè)計(jì)但要注意保持一致性不要讓“模塊內(nèi)處理一部分、全局處理一部分”的邊界模糊。在設(shè)計(jì)Filter鏈時(shí)建議明確列出每個(gè)Filter的職責(zé)邊界Filter名稱(chēng)職責(zé)拋出異常時(shí)由誰(shuí)處理TraceIdFilter生成traceId、設(shè)置響應(yīng)頭不拋異?；虍惓Ｏ蛏蠏伣o異常過(guò)濾器CorsFilter添加CORS響應(yīng)頭異常向上拋給異常過(guò)濾器AuthFilter登錄態(tài)校驗(yàn)拋401異常由異常過(guò)濾器統(tǒng)一轉(zhuǎn)JSONRateLimitFilter限流拋429異常由異常過(guò)濾器統(tǒng)一轉(zhuǎn)JSONExceptionFilter全局兜底自身處理所有冒泡上來(lái)的異常3.5 集成RESTEasy/Jersey時(shí)的注冊(cè)配置細(xì)節(jié)如果你用的是JAX-RS實(shí)現(xiàn)框架要注意注冊(cè)ExceptionMapper的方式。不同框架的注冊(cè)方式略有不同RESTEasy中使用resteasy-jaxrs時(shí)可以通過(guò)Provider注解自動(dòng)發(fā)現(xiàn)或者通過(guò)Application子類(lèi)手動(dòng)注冊(cè)ApplicationPath(/api) public class RestApplication extends Application { Override public SetClass? getClasses() { SetClass? classes new HashSet(); classes.add(BusinessExceptionMapper.class); classes.add(GenericExceptionMapper.class); classes.add(ValidationExceptionMapper.class); classes.add(UserResource.class); return classes; } }Jersey中類(lèi)似也是通過(guò)ResourceConfig掃描或注冊(cè)public class JerseyConfig extends ResourceConfig { public JerseyConfig() { register(BusinessExceptionMapper.class); register(GenericExceptionMapper.class); register(ValidationExceptionMapper.class); packages(com.example.api); } }這里要特別提醒用packages(com.example.api)自動(dòng)掃描時(shí)Provider注解的類(lèi)會(huì)被自動(dòng)注冊(cè)。但有時(shí)會(huì)因?yàn)榘鼟呙璺秶粔驅(qū)е履硞€(gè)Mapper沒(méi)被掃描到運(yùn)行時(shí)異常直接以默認(rèn)HTML格式返回前端拿到一個(gè)HTML頁(yè)面會(huì)懵掉。所以改成顯式注冊(cè)會(huì)更可控——注冊(cè)了哪些Mapper一目了然出問(wèn)題時(shí)也容易排查。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 異常被JAX-RS框架“吞掉”沒(méi)進(jìn)你的Mapper這個(gè)問(wèn)題是我在集成Jersey時(shí)遇到的。如果某個(gè)異常在進(jìn)入你的ExceptionMapper之前已經(jīng)被JAX-RS運(yùn)行時(shí)內(nèi)部當(dāng)作“不可映射異常”處理了你的Mapper可能根本沒(méi)機(jī)會(huì)執(zhí)行。尤其當(dāng)異常類(lèi)型是WebApplicationException時(shí)JAX-RS允許不經(jīng)過(guò)任何mapper就直接生成響應(yīng)。解決辦法給WebApplicationException也注冊(cè)一個(gè)mapper。雖然JAX-RS自帶默認(rèn)處理但默認(rèn)處理返回的結(jié)構(gòu)不是你自定義的JSON格式。注冊(cè)一個(gè)自定義mapper把WebApplicationException也納管Provider public class WebApplicationExceptionMapper implements ExceptionMapperWebApplicationException { Override public Response toResponse(WebApplicationException exception) { Response original exception.getResponse(); int status original.getStatus(); Object entity original.getEntity(); // 構(gòu)造統(tǒng)一格式的響應(yīng)保留原始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狀態(tài)碼映射到業(yè)務(wù)錯(cuò)誤碼比如404映射到1005401映射到1003。resolveMessage是提取原始響應(yīng)實(shí)體里的消息優(yōu)先用原始消息原始實(shí)體不再打印的時(shí)候用默認(rèn)文案兜底。4.2 異步線程池里的異常無(wú)法被ExceptionMapper捕獲上面提到過(guò)ExceptionMapper默認(rèn)是同步處理的如果你在資源方法里用了異步線程池比如ExecutorService子線程里拋出的異常不會(huì)回到JAX-RS運(yùn)行時(shí)更不會(huì)進(jìn)入ExceptionMapper。實(shí)際表現(xiàn)是接口返回成功但后臺(tái)日志里躺著一條未被處理的異常。場(chǎng)景示例GET Path(/async-job/{id}) public Response submitJob(PathParam(id) Long id) { executorService.submit(() - { // 這里拋異常無(wú)法被全局異常處理器捕獲 process(id); }); return Response.accepted().build(); }辦法有兩種。一種是把異常捕獲范圍放到異步任務(wù)內(nèi)部手動(dòng)包一層異常發(fā)生時(shí)記錄日志并發(fā)送告警另一種是使用JAX-RS的Suspended和AsyncResponse把異步結(jié)果回調(diào)給JAX-RS運(yùn)行時(shí)處理。第二種做法可以讓異?；氐絁AX-RS的異常處理鏈路前提是你把AsyncResponse.resume(exception)調(diào)用的地方放到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); // 異?；氐絁AX-RS運(yùn)行時(shí)交給ExceptionMapper } }); }4.3 返回結(jié)構(gòu)“串格式”JSON和HTML互串在Filter方式里如果異常過(guò)濾器在某個(gè)Filter已經(jīng)設(shè)置過(guò)響應(yīng)的ContentType為HTML之后觸發(fā)那么響應(yīng)頭里的ContentType可能還是HTML即使body里寫(xiě)的是JSON前端解析也會(huì)報(bào)錯(cuò)。這個(gè)問(wèn)題出現(xiàn)的頻率比我預(yù)想的高得多。原因在于resp.setContentType(application/json;charsetUTF-8)只在響應(yīng)未提交時(shí)有效一旦響應(yīng)提交了再設(shè)置ContentType不會(huì)生效。所以全局異常過(guò)濾器通常放在最外層能拿到還沒(méi)提交的響應(yīng)。如果發(fā)現(xiàn)響應(yīng)已經(jīng)提交那么不建議繼續(xù)寫(xiě)數(shù)據(jù)只記錄日志即可。還有一種情況Servlet容器里的web.xml配置了error-page重定向異常發(fā)生時(shí)會(huì)走容器錯(cuò)誤頁(yè)邏輯導(dǎo)致自定義的JSON響應(yīng)被容器的錯(cuò)誤頁(yè)替換。解決辦法是確保全局異常過(guò)濾器把異常全部吞掉后再返回讓容器認(rèn)為沒(méi)有異常發(fā)生或者把error-page的location指定為一個(gè)JSON接口。4.4 參數(shù)校驗(yàn)異常沒(méi)有統(tǒng)一返回結(jié)構(gòu)JAX-RS里參數(shù)校驗(yàn)Bean Validation拋出的異常類(lèi)型是ConstraintViolationException它不會(huì)自動(dòng)映射到你的BusinessExceptionMapper或GenericExceptionMapper如果沒(méi)有專(zhuān)門(mén)處理則可能返回400但響應(yīng)體是框架默認(rèn)的格式。現(xiàn)象是業(yè)務(wù)錯(cuò)誤碼規(guī)則失效body里是ConstraintViolationExceptionImpl之類(lèi)的堆棧片段。解決方法是注冊(cè)一個(gè)專(zhuān)門(mén)的ConstraintViolationExceptionMapperProvider public class ConstraintViolationExceptionMapper implements ExceptionMapperConstraintViolationException { Override public Response toResponse(ConstraintViolationException exception) { SetConstraintViolation? violations exception.getConstraintViolations(); ListString messages violations.stream() .map(v - v.getPropertyPath() : v.getMessage()) .collect(Collectors.toList()); String message messages.isEmpty() ? 參數(shù)校驗(yàn)失敗 : 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 常見(jiàn)問(wèn)題速查表現(xiàn)象可能原因排查方法解決方案異常格式不是自定義JSONMapper未注冊(cè)或未生效檢查Application類(lèi)顯式注冊(cè)看啟動(dòng)日志有無(wú)掃描到類(lèi)顯式注冊(cè)避免僅靠包掃描返回了HTML錯(cuò)誤頁(yè)面容器默認(rèn)error-page攔截了響應(yīng)查看web.xml檢查Filter是否吞掉異常自定義error-page或讓Filter吞掉異常traceId在多線程下線ThreadLocal跨線程失效檢查異步場(chǎng)景使用TransmittableThreadLocal或顯式傳遞響應(yīng)已經(jīng)提交后還試圖寫(xiě)bodyresponse被提前提交檢查CORS、Auth等Filter是否先寫(xiě)了響應(yīng)在異常過(guò)濾器最外層處理或僅記錄日志參數(shù)校驗(yàn)異常格式不統(tǒng)一缺ConstraintViolationExceptionMapper打印異常類(lèi)型添加對(duì)應(yīng)Mapper日志中找不到請(qǐng)求上下文ThreadLocal未在finally清理檢查是否存在串線程清理或使用委托包裝清理邏輯4.6 分環(huán)境差異化處理線上環(huán)境和本地開(kāi)發(fā)環(huán)境的異常處理策略應(yīng)該不同。本地開(kāi)發(fā)時(shí)全局異常處理層可以把完整異常堆棧直接放在響應(yīng)體的detail字段里方便前端聯(lián)調(diào)和后端排查。線上環(huán)境則不要返回堆棧只返回message和traceId。實(shí)現(xiàn)方式是根據(jù)環(huán)境配置判斷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; }生產(chǎn)環(huán)境里不要試圖把堆棧返回客戶端也別用printStackTrace全部走日志框架否則大量異常堆棧打在控制臺(tái)日志收集時(shí)會(huì)被刷屏真正需要關(guān)注的信息反而被淹沒(méi)。5. 進(jìn)階實(shí)踐從單體異常處理到分布式異常追蹤5.1 全局異常處理與鏈路追蹤的配合JavaEE單體應(yīng)用發(fā)展到分布式體系時(shí)全局異常處理層除了返回統(tǒng)一格式的JSON還要承擔(dān)“把traceId透?jìng)鞯较掠畏?wù)”的職責(zé)。這塊在網(wǎng)關(guān)層、服務(wù)提供方、服務(wù)消費(fèi)方各有一份實(shí)現(xiàn)目標(biāo)只有一個(gè)一個(gè)請(qǐng)求從網(wǎng)關(guān)到下游多個(gè)服務(wù)整條鏈路上使用的traceId是同一個(gè)。在服務(wù)消費(fèi)方請(qǐng)求外發(fā)之前要取出MDC里的traceId設(shè)置到HTTP頭里String traceId MDC.get(traceId); if (StringUtils.isNotBlank(traceId)) { httpRequest.setHeader(X-Request-Id, traceId); }在服務(wù)提供方就是前面TraceIdFilter里的邏輯優(yōu)先讀取X-Request-Id頭沿用而不是另生成。一旦全鏈路都在透?jìng)魍粋€(gè)traceId全局異常處理層打出的日志日志里就帶著這條traceId跳板機(jī)上輸入traceId就能把整個(gè)鏈路的日志拉出來(lái)排障效率天差地別。5.2 告警策略與關(guān)鍵指標(biāo)全局異常處理層除了記錄日志還應(yīng)該做指標(biāo)統(tǒng)計(jì)。常見(jiàn)的統(tǒng)計(jì)維度包括每分鐘異常捕獲總數(shù)各錯(cuò)誤碼占比各類(lèi)異常的發(fā)生趨勢(shì)異常發(fā)生時(shí)對(duì)應(yīng)接口的耗時(shí)用這些指標(biāo)配合監(jiān)控告警可以對(duì)“異常突增”做出快速響應(yīng)。比如平時(shí)每分鐘異常捕獲數(shù)在個(gè)位數(shù)突然漲到幾百不需要等待用戶反饋告警已經(jīng)發(fā)出來(lái)了。這一點(diǎn)在生產(chǎn)環(huán)境有巨大價(jià)值。統(tǒng)計(jì)做法不復(fù)雜用一個(gè)環(huán)形的計(jì)數(shù)器或直接在日志里打點(diǎn)LOGGER.info(【異常指標(biāo)】uri{} code{} type{} cost{}ms, uri, code, exception.getClass().getSimpleName(), cost);監(jiān)控系統(tǒng)收集日志后按關(guān)鍵字聚合就能畫(huà)出異常趨勢(shì)圖。5.3 萬(wàn)能兜底最后一道防線在設(shè)計(jì)全局異常處理時(shí)有一個(gè)原則必須堅(jiān)持前端展示的友好錯(cuò)誤信息可以缺失但服務(wù)端絕對(duì)不能因?yàn)闆](méi)有正確處理異常而崩潰或丟失日志。換句話說(shuō)全局異常處理層本身絕不能拋出異常。一旦它在處理異常時(shí)拋了新異常原始異常信息可能丟失響應(yīng)也可能變成500空頁(yè)面。所以建議在所有Mapper和Filter的異常處理分支里再加一個(gè)最終保底catch住所有Throwable只記日志返回最基礎(chǔ)的錯(cuò)誤結(jié)構(gòu)。try { writeErrorResponse(req, resp, code, message, e, start); } catch (Exception ex) { LOGGER.error(全局異常處理自身失敗, ex); if (!resp.isCommitted()) { resp.setStatus(500); resp.setContentType(text/plain;charsetUTF-8); resp.getWriter().write({\code\: 5000, \message\: \系統(tǒng)繁忙\}); } }有人可能會(huì)說(shuō)寫(xiě)響應(yīng)怎么可能失敗在真實(shí)運(yùn)行環(huán)境下連接被客戶端斷開(kāi)、緩沖區(qū)溢出、字符編碼不支持等原因都可能觸發(fā)IO異常不要讓兜底邏輯變成“二次炸彈”。5.4 一個(gè)完整的配置清單項(xiàng)目里落地這套東西建議按下面的清單自查檢查項(xiàng)是否完成統(tǒng)一了ErrorResponse結(jié)構(gòu)是/否定義了全局錯(cuò)誤碼枚舉是/否業(yè)務(wù)異常繼承統(tǒng)一基類(lèi)是/否注冊(cè)了業(yè)務(wù)異常Mapper是/否注冊(cè)了通用異常Mapper(Throwable)是/否注冊(cè)了參數(shù)校驗(yàn)異常Mapper是/否生成并透?jìng)鱰raceId是/否MDC在finally中清理是/否響應(yīng)統(tǒng)一為UTF-8編碼是/否生產(chǎn)環(huán)境不返回堆棧是/否異步場(chǎng)景有異常處理策略是/否全局異常處理自身有兜底是/否6. 個(gè)人經(jīng)驗(yàn)總結(jié)與擴(kuò)展思路實(shí)操做下來(lái)我最深的感受是全局異常處理不只是寫(xiě)幾個(gè)Mapper類(lèi)那么簡(jiǎn)單它是一個(gè)系統(tǒng)性設(shè)計(jì)。體系一旦搭好后續(xù)每新增一種異常類(lèi)型都只是加一個(gè)異常類(lèi)和一個(gè)Mapper的問(wèn)題業(yè)務(wù)代碼的整潔度會(huì)大幅提升。有一個(gè)比較實(shí)用的擴(kuò)展思路如果項(xiàng)目已經(jīng)使用Swagger/OpenAPI可以讓全局異常處理層把ErrorResponse結(jié)構(gòu)自動(dòng)注入到OpenAPI文檔中。這樣前端生成的SDK里所有接口的錯(cuò)誤響應(yīng)結(jié)構(gòu)就是同一個(gè)類(lèi)型聯(lián)調(diào)時(shí)前端基本不會(huì)問(wèn)“這個(gè)接口報(bào)錯(cuò)返回什么格式”這種問(wèn)題。另外一個(gè)方向是按微服務(wù)拆分錯(cuò)誤碼段。每個(gè)微服務(wù)模塊有自己獨(dú)立的錯(cuò)誤碼區(qū)間網(wǎng)關(guān)做一次統(tǒng)一聚合將內(nèi)部錯(cuò)誤碼翻譯成對(duì)客戶端合適的錯(cuò)誤碼。這個(gè)工作做與不做直接決定BFF層對(duì)接成本的高低。多寫(xiě)一句不要想著一口氣引入過(guò)多“優(yōu)雅”特性。先讓Filter兜底跑起來(lái)把統(tǒng)一響應(yīng)結(jié)構(gòu)固化下來(lái)再引入ExceptionMapper精細(xì)控制逐步演進(jìn)。一個(gè)能跑、能排查、能告警的處理體系比文檔里再優(yōu)美的設(shè)計(jì)都更有價(jià)值。