)
1. 為什么值得花時間啃透HandlerAdapter很多人第一次翻Spring MVC源碼都是從DispatcherServlet的doDispatch方法開始的。那段代碼里有一行特別不起眼但極其關鍵的調(diào)用mappedHandler getHandler(processedRequest)拿到HandlerExecutionChain之后緊接著就是HandlerAdapter ha getHandlerAdapter(mappedHandler.getHandler())。絕大多數(shù)人掃一眼就過去了覺得無非是找個適配器來執(zhí)行handler。但真正在項目里踩過坑的人都清楚Spring MVC最靈活、最容易出問題、也最能體現(xiàn)框架設計功力的地方恰恰就在這個接口上。你寫的RequestMapping方法能被執(zhí)行、ResponseBody能自動轉(zhuǎn)JSON、HttpEntity參數(shù)能自動綁定、ResponseEntity能自動處理狀態(tài)碼背后全是HandlerAdapter在干活。這篇文章不打算復述官方文檔而是從一個實際維護過多個Spring MVC定制化項目的開發(fā)者視角把HandlerAdapter這個接口從設計動機、源碼實現(xiàn)、擴展點到實戰(zhàn)踩坑完整地拆一遍。適合已經(jīng)用過Spring MVC、能寫Controller、但想搞清楚請求到底是怎么被路由到我的方法上的中高級開發(fā)者。看完之后你應該能自己寫一個自定義的HandlerAdapter也能在遇到參數(shù)綁定失敗返回值處理異常這類問題時快速定位到是哪一環(huán)出了問題。2. HandlerAdapter接口的整體設計與思路拆解2.1 從DispatcherServlet的視角看適配器模式要理解HandlerAdapter得先理解DispatcherServlet的困境。作為一個前端控制器它需要處理各種各樣的處理器有Controller注解的普通Bean、有實現(xiàn)了Controller接口的老式Bean、有HttpRequestHandler、還有RequestMapping標注的方法。這些處理器的調(diào)用方式完全不同——有的需要反射調(diào)用方法有的直接調(diào)handleRequest有的還要處理參數(shù)解析和返回值。如果DispatcherServlet里寫一堆if-else判斷類型再分別調(diào)用代碼會爛到無法維護。所以Spring用了適配器模式DispatcherServlet只認HandlerAdapter接口所有具體的調(diào)用邏輯封裝在各自的適配器實現(xiàn)里。這樣新增一種處理器類型只需要新增一個適配器DispatcherServlet一行都不用改。這個設計思路在Spring里反復出現(xiàn)但HandlerAdapter是最典型的一個。它的接口定義極其簡潔public interface HandlerAdapter { boolean supports(Object handler); ModelAndView handle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception; long getLastModified(HttpServletRequest request, Object handler); }三個方法各司其職。supports負責判斷這個適配器能不能處理當前handlerhandle負責真正的執(zhí)行getLastModified用于處理HTTP緩存。看起來簡單但每個方法背后都有講究。2.2 supports方法的判斷邏輯與性能考量supports方法看似只是類型判斷但它的調(diào)用時機很關鍵。在DispatcherServlet.getHandlerAdapter里是遍歷所有已注冊的HandlerAdapter逐個調(diào)用supports第一個返回true的就用它。這意味著適配器的注冊順序會影響匹配結果如果有多個適配器都支持同一個handler先注冊的勝出supports會被頻繁調(diào)用實現(xiàn)必須足夠輕量判斷邏輯要精確不能出現(xiàn)誤判導致用錯適配器以RequestMappingHandlerAdapter為例它的supports實現(xiàn)是Override public boolean supports(Object handler) { return handler instanceof HandlerMethod; }就一行instanceof非常輕。而HttpRequestHandlerAdapter的判斷是handler instanceof HttpRequestHandler。這種設計保證了即使注冊了七八個適配器每次匹配的開銷也可以忽略不計。注意如果你自己寫適配器supports里千萬不要做數(shù)據(jù)庫查詢、反射掃描這類重操作否則每個請求都會付出代價。2.3 handle方法的返回值設計為什么是ModelAndViewhandle方法返回ModelAndView這個設計經(jīng)常被吐槽過時因為現(xiàn)在大部分接口都是返回JSON。但理解這個設計要回到Spring MVC的早期定位它首先是一個MVC框架視圖渲染是核心職責。ModelAndView承載了模型數(shù)據(jù)視圖名這兩個渲染必需的信息。那返回JSON的接口怎么辦答案是返回null。RequestResponseBodyMethodProcessor在處理ResponseBody時會直接把數(shù)據(jù)寫進response的output stream然后返回null的ModelAndView。DispatcherServlet拿到null之后就知道響應已經(jīng)處理完了不需要渲染視圖直接走processDispatchResult的后續(xù)邏輯。這個設計其實很巧妙用一個統(tǒng)一的返回值類型同時支持了視圖渲染和直接寫響應兩種模式。代價是null的語義不夠明確讀源碼時容易困惑。2.4 getLastModified與HTTP緩存的關聯(lián)getLastModified是三個方法里最容易被忽略的。它對應HTTP協(xié)議里的Last-Modified頭用于協(xié)商緩存。如果handler實現(xiàn)了LastModified接口適配器會返回其getLastModified值DispatcherServlet會據(jù)此判斷是否返回304。大部分現(xiàn)代項目用ETag或者干脆不做緩存所以這個方法經(jīng)常返回-1表示不支持。但如果你做的是內(nèi)容型網(wǎng)站靜態(tài)資源或者變化不頻繁的頁面用好這個方法能顯著降低帶寬。HttpRequestHandlerAdapter就完整實現(xiàn)了這個邏輯因為它處理的HttpRequestHandler本身就繼承了LastModified接口。3. 核心實現(xiàn)類的源碼細節(jié)與實操要點3.1 RequestMappingHandlerAdapter最核心也最復雜RequestMappingHandlerAdapter是日常開發(fā)中99%的請求最終會走到的適配器。它的handle方法核心邏輯是Override protected ModelAndView handleInternal(HttpServletRequest request, HttpServletResponse response, HandlerMethod handlerMethod) throws Exception { ModelAndView mav; checkRequest(request); if (this.synchronizeOnSession) { HttpSession session request.getSession(false); if (session ! null) { Object mutex WebUtils.getSessionMutex(session); synchronized (mutex) { mav invokeHandlerMethod(request, response, handlerMethod); } } else { mav invokeHandlerMethod(request, response, handlerMethod); } } else { mav invokeHandlerMethod(request, response, handlerMethod); } if (!response.containsHeader(HEADER_CACHE_CONTROL)) { if (getSessionAttributesHandler(handlerMethod).hasSessionAttributes()) { applyCacheSeconds(response, this.cacheSecondsForSessionAttributeHandlers); } else { prepareResponse(response); } } return mav; }這段代碼里有幾個關鍵點值得展開。第一是checkRequest它會校驗請求方法是否被支持。如果你在RequestMapping里限定了method RequestMethod.POST但用GET請求訪問就會在這里拋出HttpRequestMethodNotSupportedException。這個異常最終會被DefaultHandlerExceptionResolver處理成405響應。第二是session同步邏輯。synchronizeOnSession默認是false如果開啟同一個session的請求會串行執(zhí)行。這個特性在早期處理并發(fā)問題時用過但現(xiàn)在基本不推薦——它會嚴重拖累性能而且用session鎖解決并發(fā)本身就是個壞味道。第三是緩存頭的處理。prepareResponse會根據(jù)配置設置Cache-Control頭。默認情況下如果沒有顯式配置Spring不會設置任何緩存頭這也是為什么很多接口在瀏覽器里默認不緩存。3.2 invokeHandlerMethod的參數(shù)解析鏈路invokeHandlerMethod是整個適配器最核心的方法它要完成參數(shù)解析、方法調(diào)用、返回值處理三件事。參數(shù)解析依賴HandlerMethodArgumentResolver鏈返回值處理依賴HandlerMethodReturnValueHandler鏈。ServletInvocableHandlerMethod invocableMethod createInvocableHandlerMethod(handlerMethod); if (this.argumentResolvers ! null) { invocableMethod.setHandlerMethodArgumentResolvers(this.argumentResolvers); } if (this.returnValueHandlers ! null) { invocableMethod.setHandlerMethodReturnValueHandlers(this.returnValueHandlers); } invocableMethod.invokeAndHandle(webRequest, mavContainer);argumentResolvers和returnValueHandlers是在afterPropertiesSet里初始化的默認會加載一長串解析器。這個順序非常重要因為解析器也是第一個支持的就用。默認的參數(shù)解析器順序大致是RequestParamMethodArgumentResolver、RequestParamMapMethodArgumentResolver、PathVariableMethodArgumentResolver、ServletModelAttributeMethodProcessor、RequestResponseBodyMethodProcessor等等。如果你自定義了一個解析器想讓它優(yōu)先于內(nèi)置的必須通過setArgumentResolvers或者setCustomArgumentResolvers調(diào)整順序。實操心得自定義參數(shù)解析器時最常見的坑是我的解析器沒生效。90%的情況是因為內(nèi)置解析器先匹配上了。比如你想解析一個自定義注解標注的參數(shù)但參數(shù)類型是StringRequestParamMethodArgumentResolver可能會先把它當成普通參數(shù)處理。解決辦法是讓自定義解析器的supportsParameter判斷更精確或者用setCustomArgumentResolvers確保優(yōu)先級。3.3 SimpleControllerHandlerAdapter與老式ControllerSimpleControllerHandlerAdapter處理的是實現(xiàn)了Controller接口的Bean。它的handle方法簡單到極致Override public ModelAndView handle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { return ((Controller) handler).handleRequest(request, response); }這種老式寫法現(xiàn)在幾乎沒人用了但在一些遺留系統(tǒng)里還能見到。它的優(yōu)勢是簡單直接沒有反射開銷劣勢是每個Controller只能處理一個URL而且參數(shù)綁定要自己寫。如果你在維護老項目看到這種寫法不要驚訝它和Controller是可以共存的因為兩個適配器都注冊了各管各的。3.4 HttpRequestHandlerAdapter與靜態(tài)資源處理HttpRequestHandlerAdapter處理HttpRequestHandler最典型的應用是ResourceHttpRequestHandler——也就是Spring MVC處理靜態(tài)資源的機制。當你配置了mvc:resources或者addResourceHandlers請求靜態(tài)文件時走的就是這個適配器。它的handle方法會調(diào)用handler.handleRequest而ResourceHttpRequestHandler會去查找資源文件、設置Content-Type、處理Last-Modified和ETag、支持Range請求。這也是為什么Spring MVC處理靜態(tài)資源的性能其實不差——它做了完整的HTTP緩存協(xié)商。3.5 適配器的注冊與初始化順序在WebMvcConfigurationSupport里默認適配器的注冊順序是Bean public HandlerAdapter requestMappingHandlerAdapter() { ... } Bean public HandlerAdapter httpRequestHandlerAdapter() { ... } Bean public HandlerAdapter simpleControllerHandlerAdapter() { ... }注意requestMappingHandlerAdapter排在最前面。這個順序決定了當handler同時滿足多個適配器的supports時優(yōu)先用哪個。實際上HandlerMethod只被RequestMappingHandlerAdapter支持所以順序影響不大但理解這個機制對自定義適配器很重要。4. 自定義HandlerAdapter的完整實操過程4.1 什么場景下需要自定義適配器大部分項目一輩子都不需要自定義HandlerAdapter。但以下幾種場景自定義是合理的你有一套自己的處理器抽象比如基于注解的RPC方法想復用Spring MVC的請求分發(fā)機制你想對特定類型的handler做統(tǒng)一的預處理比如統(tǒng)一的日志、鑒權、限流你在做框架層面的擴展比如實現(xiàn)一個輕量級的API網(wǎng)關需要強調(diào)的是如果你的需求只是在Controller執(zhí)行前后做點事用HandlerInterceptor就夠了不要上適配器。適配器的粒度更粗它是如何調(diào)用handler層面的擴展不是調(diào)用前后層面的。4.2 定義自定義handler與適配器假設我們要實現(xiàn)一個簡單的場景某些類實現(xiàn)了ApiHandler接口它們的handle方法接收一個MapString, Object參數(shù)返回一個Map結果框架自動把結果序列化成JSON。先定義handler接口public interface ApiHandler { MapString, Object handle(MapString, Object params); }然后寫適配器public class ApiHandlerAdapter implements HandlerAdapter { private final ObjectMapper objectMapper new ObjectMapper(); Override public boolean supports(Object handler) { return handler instanceof ApiHandler; } Override public ModelAndView handle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { ApiHandler apiHandler (ApiHandler) handler; MapString, Object params extractParams(request); MapString, Object result apiHandler.handle(params); response.setContentType(application/json;charsetUTF-8); response.setStatus(HttpServletResponse.SC_OK); objectMapper.writeValue(response.getWriter(), result); return null; } Override public long getLastModified(HttpServletRequest request, Object handler) { return -1; } private MapString, Object extractParams(HttpServletRequest request) { MapString, Object params new HashMap(); EnumerationString names request.getParameterNames(); while (names.hasMoreElements()) { String name names.nextElement(); params.put(name, request.getParameter(name)); } return params; } }這個適配器做了三件事從請求里提取參數(shù)、調(diào)用handler、把結果寫成JSON。返回null的ModelAndView告訴DispatcherServlet不需要渲染視圖。4.3 注冊適配器到Spring MVC注冊方式取決于你的配置方式。如果是Java ConfigConfiguration EnableWebMvc public class WebConfig implements WebMvcConfigurer { Override public void addArgumentResolvers(ListHandlerMethodArgumentResolver resolvers) { // 參數(shù)解析器擴展 } Bean public ApiHandlerAdapter apiHandlerAdapter() { return new ApiHandlerAdapter(); } }但這里有個坑Bean注冊的HandlerAdapter會被加到默認適配器列表里但順序不確定。如果你想確保它在特定位置需要更精細的控制。更可靠的方式是重寫requestMappingHandlerAdapter的配置或者直接操作RequestMappingHandlerMapping。實際上Spring MVC的適配器列表是在DispatcherServlet.initHandlerAdapters里初始化的它會從容器里拿所有HandlerAdapter類型的Bean然后按Order排序。所以給自定義適配器加Order注解可以控制順序Bean Order(0) public ApiHandlerAdapter apiHandlerAdapter() { return new ApiHandlerAdapter(); }4.4 讓自定義handler被HandlerMapping發(fā)現(xiàn)光有適配器還不夠DispatcherServlet得先通過HandlerMapping找到你的handler。默認的RequestMappingHandlerMapping只認Controller和RequestMapping。要讓ApiHandler被識別需要自定義HandlerMappingpublic class ApiHandlerMapping extends AbstractHandlerMapping { private final MapString, ApiHandler handlerMap new HashMap(); public void registerHandler(String path, ApiHandler handler) { handlerMap.put(path, handler); } Override protected Object getHandlerInternal(HttpServletRequest request) throws Exception { String path request.getRequestURI(); return handlerMap.get(path); } }然后在配置里注冊這個HandlerMapping。注意HandlerMapping和HandlerAdapter是配套的HandlerMapping負責找到handlerHandlerAdapter負責執(zhí)行handler。兩者通過handler對象關聯(lián)但彼此不知道對方的存在這是Spring MVC解耦的關鍵。4.5 參數(shù)提取的健壯性處理上面extractParams的實現(xiàn)很粗糙只處理了query參數(shù)。實際項目中要考慮POST請求的body解析JSON、form-data文件上傳字符編碼參數(shù)類型轉(zhuǎn)換如果這些都要自己寫工作量不小。這也是為什么大部分場景下直接用RequestMapping更劃算——Spring已經(jīng)幫你處理好了所有這些細節(jié)。自定義適配器的價值在于特殊場景的定制不是重新造輪子。實操心得寫自定義適配器時參數(shù)提取和結果序列化這兩塊最容易出問題。建議先用最簡單的實現(xiàn)跑通流程再逐步增加復雜度。不要一上來就想著支持所有Content-Type先把application/json和application/x-www-form-urlencoded搞定覆蓋80%的場景。5. 常見問題與排查技巧實錄5.1 參數(shù)綁定失敗從異常棧定位到解析器參數(shù)綁定失敗是最高頻的問題。典型異常是MissingServletRequestParameterException、MethodArgumentTypeMismatchException、HttpMessageNotReadableException。排查思路是看異常類型確定是哪個解析器拋的看異常信息里的參數(shù)名確認是哪個參數(shù)檢查請求實際發(fā)送的內(nèi)容用抓包工具或日志對照解析器的supportsParameter邏輯判斷為什么匹配到了這個解析器比如HttpMessageNotReadableException通常是RequestResponseBodyMethodProcessor拋的說明RequestBody的JSON解析失敗。原因可能是請求體為空、JSON格式錯誤、目標類型沒有默認構造函數(shù)、字段類型不匹配。這時候打開DEBUG日志看Jackson的具體報錯信息比看異常棧有用得多。5.2 返回值處理異常ResponseBody的坑ResponseBody返回對象時如果序列化失敗會拋HttpMessageNotWritableException。常見原因?qū)ο罄镉醒h(huán)引用比如雙向關聯(lián)的實體對象里有無法序列化的類型比如InputStream返回的是null但配置了不允許null循環(huán)引用是最隱蔽的。比如Order里有ListOrderItemOrderItem里又有Order的引用Jackson序列化時會無限遞歸。解決辦法是用JsonIgnore或者JsonManagedReference/JsonBackReference。5.3 適配器不生效supports返回false的排查自定義適配器不生效第一步是確認supports有沒有被調(diào)用?？梢栽趕upports里打日志看請求進來時有沒有打印。如果沒有說明HandlerMapping沒找到你的handler或者handler類型不對。如果有打印但返回false檢查instanceof判斷。還有一種情況適配器被調(diào)用了但用的是別的適配器。這時候看DispatcherServlet的DEBUG日志它會打印Using handler adapter [xxx]。如果用的是內(nèi)置適配器說明你的handler被內(nèi)置適配器先匹配上了。5.4 常見問題速查表問題現(xiàn)象可能原因排查方向405 Method Not AllowedcheckRequest校驗失敗檢查RequestMapping的method配置415 Unsupported Media TypeContent-Type不匹配檢查consumes配置和請求頭400 Bad Request參數(shù)綁定失敗看異常類型定位解析器500 序列化異常返回值無法序列化檢查循環(huán)引用、null值自定義適配器不生效supports返回false或順序問題打日志確認調(diào)用鏈靜態(tài)資源404ResourceHttpRequestHandler未匹配檢查資源路徑配置5.5 獨家避坑技巧第一個技巧調(diào)試適配器問題時把org.springframework.web.servlet.DispatcherServlet的日志級別調(diào)到DEBUG它會打印handler、adapter、interceptor的完整匹配過程。這比斷點調(diào)試高效得多。第二個技巧RequestMappingHandlerAdapter的argumentResolvers和returnValueHandlers是可以通過Bean覆蓋的。如果你需要全局修改參數(shù)解析行為不要改源碼直接提供一個自定義的RequestMappingHandlerAdapterBean設置你自己的解析器列表。第三個技巧ControllerAdvice配合ExceptionHandler能處理大部分異常但有些異常在適配器層面就拋出了還沒到Controller。比如HttpRequestMethodNotSupportedException它是在checkRequest里拋的ExceptionHandler能捕獲但如果你自定義了適配器要確保異常能正常傳播出去。第四個技巧getLastModified返回-1表示不支持緩存返回具體時間戳表示支持。如果你做的是內(nèi)容型接口實現(xiàn)這個方法能顯著降低服務器壓力。但要注意時間戳的精度是秒級如果內(nèi)容變化頻繁緩存反而會導致數(shù)據(jù)不一致。6. 從適配器看Spring MVC的擴展哲學HandlerAdapter這個接口只有三個方法但它體現(xiàn)了Spring框架一以貫之的設計哲學面向接口編程、職責單一、通過組合而非繼承實現(xiàn)擴展。DispatcherServlet不關心handler是什么只關心有沒有適配器能處理它適配器不關心請求怎么來的只關心怎么調(diào)用handlerhandler不關心框架怎么運作只關心我的業(yè)務邏輯。這種分層讓每一層都可以獨立演化。你可以換掉HandlerMapping而不影響適配器可以新增適配器而不影響DispatcherServlet可以自定義handler而不影響其他組件。理解了這一點再看Spring MVC的其他組件——ViewResolver、HandlerExceptionResolver、MultipartResolver——會發(fā)現(xiàn)它們都是同一個套路的產(chǎn)物。我在實際項目中做過一次比較激進的改造把RequestMappingHandlerAdapter替換成了一個自定義實現(xiàn)在invokeHandlerMethod之前插入了統(tǒng)一的參數(shù)校驗和日志記錄。改造過程比想象中順利因為適配器的邊界非常清晰只要保證handle方法的輸入輸出契約不變內(nèi)部怎么改都不會影響其他組件。這種可替換性正是良好抽象的價值所在。如果你正在維護一個中大型的Spring MVC項目建議花半天時間把DispatcherServlet、HandlerMapping、HandlerAdapter這三者的協(xié)作關系畫一遍。不需要畫得多漂亮關鍵是理清請求進來之后每一步是誰在處理、處理完交給誰。理清之后再遇到路由、參數(shù)、返回值相關的問題定位速度會快一個數(shù)量級。 Spring MVC HandlerAdapter 源碼解析與自定義適配器實戰(zhàn)
1. 為什么值得花時間啃透HandlerAdapter很多人第一次翻Spring MVC源碼都是從DispatcherServlet的doDispatch方法開始的。那段代碼里有一行特別不起眼但極其關鍵的調(diào)用mappedHandler getHandler(processedRequest)拿到HandlerExecutionChain之后緊接著就是HandlerAdapter ha getHandlerAdapter(mappedHandler.getHandler())。絕大多數(shù)人掃一眼就過去了覺得無非是找個適配器來執(zhí)行handler。但真正在項目里踩過坑的人都清楚Spring MVC最靈活、最容易出問題、也最能體現(xiàn)框架設計功力的地方恰恰就在這個接口上。你寫的RequestMapping方法能被執(zhí)行、ResponseBody能自動轉(zhuǎn)JSON、HttpEntity參數(shù)能自動綁定、ResponseEntity能自動處理狀態(tài)碼背后全是HandlerAdapter在干活。這篇文章不打算復述官方文檔而是從一個實際維護過多個Spring MVC定制化項目的開發(fā)者視角把HandlerAdapter這個接口從設計動機、源碼實現(xiàn)、擴展點到實戰(zhàn)踩坑完整地拆一遍。適合已經(jīng)用過Spring MVC、能寫Controller、但想搞清楚請求到底是怎么被路由到我的方法上的中高級開發(fā)者。看完之后你應該能自己寫一個自定義的HandlerAdapter也能在遇到參數(shù)綁定失敗返回值處理異常這類問題時快速定位到是哪一環(huán)出了問題。2. HandlerAdapter接口的整體設計與思路拆解2.1 從DispatcherServlet的視角看適配器模式要理解HandlerAdapter得先理解DispatcherServlet的困境。作為一個前端控制器它需要處理各種各樣的處理器有Controller注解的普通Bean、有實現(xiàn)了Controller接口的老式Bean、有HttpRequestHandler、還有RequestMapping標注的方法。這些處理器的調(diào)用方式完全不同——有的需要反射調(diào)用方法有的直接調(diào)handleRequest有的還要處理參數(shù)解析和返回值。如果DispatcherServlet里寫一堆if-else判斷類型再分別調(diào)用代碼會爛到無法維護。所以Spring用了適配器模式DispatcherServlet只認HandlerAdapter接口所有具體的調(diào)用邏輯封裝在各自的適配器實現(xiàn)里。這樣新增一種處理器類型只需要新增一個適配器DispatcherServlet一行都不用改。這個設計思路在Spring里反復出現(xiàn)但HandlerAdapter是最典型的一個。它的接口定義極其簡潔public interface HandlerAdapter { boolean supports(Object handler); ModelAndView handle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception; long getLastModified(HttpServletRequest request, Object handler); }三個方法各司其職。supports負責判斷這個適配器能不能處理當前handlerhandle負責真正的執(zhí)行getLastModified用于處理HTTP緩存。看起來簡單但每個方法背后都有講究。2.2 supports方法的判斷邏輯與性能考量supports方法看似只是類型判斷但它的調(diào)用時機很關鍵。在DispatcherServlet.getHandlerAdapter里是遍歷所有已注冊的HandlerAdapter逐個調(diào)用supports第一個返回true的就用它。這意味著適配器的注冊順序會影響匹配結果如果有多個適配器都支持同一個handler先注冊的勝出supports會被頻繁調(diào)用實現(xiàn)必須足夠輕量判斷邏輯要精確不能出現(xiàn)誤判導致用錯適配器以RequestMappingHandlerAdapter為例它的supports實現(xiàn)是Override public boolean supports(Object handler) { return handler instanceof HandlerMethod; }就一行instanceof非常輕。而HttpRequestHandlerAdapter的判斷是handler instanceof HttpRequestHandler。這種設計保證了即使注冊了七八個適配器每次匹配的開銷也可以忽略不計。注意如果你自己寫適配器supports里千萬不要做數(shù)據(jù)庫查詢、反射掃描這類重操作否則每個請求都會付出代價。2.3 handle方法的返回值設計為什么是ModelAndViewhandle方法返回ModelAndView這個設計經(jīng)常被吐槽過時因為現(xiàn)在大部分接口都是返回JSON。但理解這個設計要回到Spring MVC的早期定位它首先是一個MVC框架視圖渲染是核心職責。ModelAndView承載了模型數(shù)據(jù)視圖名這兩個渲染必需的信息。那返回JSON的接口怎么辦答案是返回null。RequestResponseBodyMethodProcessor在處理ResponseBody時會直接把數(shù)據(jù)寫進response的output stream然后返回null的ModelAndView。DispatcherServlet拿到null之后就知道響應已經(jīng)處理完了不需要渲染視圖直接走processDispatchResult的后續(xù)邏輯。這個設計其實很巧妙用一個統(tǒng)一的返回值類型同時支持了視圖渲染和直接寫響應兩種模式。代價是null的語義不夠明確讀源碼時容易困惑。2.4 getLastModified與HTTP緩存的關聯(lián)getLastModified是三個方法里最容易被忽略的。它對應HTTP協(xié)議里的Last-Modified頭用于協(xié)商緩存。如果handler實現(xiàn)了LastModified接口適配器會返回其getLastModified值DispatcherServlet會據(jù)此判斷是否返回304。大部分現(xiàn)代項目用ETag或者干脆不做緩存所以這個方法經(jīng)常返回-1表示不支持。但如果你做的是內(nèi)容型網(wǎng)站靜態(tài)資源或者變化不頻繁的頁面用好這個方法能顯著降低帶寬。HttpRequestHandlerAdapter就完整實現(xiàn)了這個邏輯因為它處理的HttpRequestHandler本身就繼承了LastModified接口。3. 核心實現(xiàn)類的源碼細節(jié)與實操要點3.1 RequestMappingHandlerAdapter最核心也最復雜RequestMappingHandlerAdapter是日常開發(fā)中99%的請求最終會走到的適配器。它的handle方法核心邏輯是Override protected ModelAndView handleInternal(HttpServletRequest request, HttpServletResponse response, HandlerMethod handlerMethod) throws Exception { ModelAndView mav; checkRequest(request); if (this.synchronizeOnSession) { HttpSession session request.getSession(false); if (session ! null) { Object mutex WebUtils.getSessionMutex(session); synchronized (mutex) { mav invokeHandlerMethod(request, response, handlerMethod); } } else { mav invokeHandlerMethod(request, response, handlerMethod); } } else { mav invokeHandlerMethod(request, response, handlerMethod); } if (!response.containsHeader(HEADER_CACHE_CONTROL)) { if (getSessionAttributesHandler(handlerMethod).hasSessionAttributes()) { applyCacheSeconds(response, this.cacheSecondsForSessionAttributeHandlers); } else { prepareResponse(response); } } return mav; }這段代碼里有幾個關鍵點值得展開。第一是checkRequest它會校驗請求方法是否被支持。如果你在RequestMapping里限定了method RequestMethod.POST但用GET請求訪問就會在這里拋出HttpRequestMethodNotSupportedException。這個異常最終會被DefaultHandlerExceptionResolver處理成405響應。第二是session同步邏輯。synchronizeOnSession默認是false如果開啟同一個session的請求會串行執(zhí)行。這個特性在早期處理并發(fā)問題時用過但現(xiàn)在基本不推薦——它會嚴重拖累性能而且用session鎖解決并發(fā)本身就是個壞味道。第三是緩存頭的處理。prepareResponse會根據(jù)配置設置Cache-Control頭。默認情況下如果沒有顯式配置Spring不會設置任何緩存頭這也是為什么很多接口在瀏覽器里默認不緩存。3.2 invokeHandlerMethod的參數(shù)解析鏈路invokeHandlerMethod是整個適配器最核心的方法它要完成參數(shù)解析、方法調(diào)用、返回值處理三件事。參數(shù)解析依賴HandlerMethodArgumentResolver鏈返回值處理依賴HandlerMethodReturnValueHandler鏈。ServletInvocableHandlerMethod invocableMethod createInvocableHandlerMethod(handlerMethod); if (this.argumentResolvers ! null) { invocableMethod.setHandlerMethodArgumentResolvers(this.argumentResolvers); } if (this.returnValueHandlers ! null) { invocableMethod.setHandlerMethodReturnValueHandlers(this.returnValueHandlers); } invocableMethod.invokeAndHandle(webRequest, mavContainer);argumentResolvers和returnValueHandlers是在afterPropertiesSet里初始化的默認會加載一長串解析器。這個順序非常重要因為解析器也是第一個支持的就用。默認的參數(shù)解析器順序大致是RequestParamMethodArgumentResolver、RequestParamMapMethodArgumentResolver、PathVariableMethodArgumentResolver、ServletModelAttributeMethodProcessor、RequestResponseBodyMethodProcessor等等。如果你自定義了一個解析器想讓它優(yōu)先于內(nèi)置的必須通過setArgumentResolvers或者setCustomArgumentResolvers調(diào)整順序。實操心得自定義參數(shù)解析器時最常見的坑是我的解析器沒生效。90%的情況是因為內(nèi)置解析器先匹配上了。比如你想解析一個自定義注解標注的參數(shù)但參數(shù)類型是StringRequestParamMethodArgumentResolver可能會先把它當成普通參數(shù)處理。解決辦法是讓自定義解析器的supportsParameter判斷更精確或者用setCustomArgumentResolvers確保優(yōu)先級。3.3 SimpleControllerHandlerAdapter與老式ControllerSimpleControllerHandlerAdapter處理的是實現(xiàn)了Controller接口的Bean。它的handle方法簡單到極致Override public ModelAndView handle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { return ((Controller) handler).handleRequest(request, response); }這種老式寫法現(xiàn)在幾乎沒人用了但在一些遺留系統(tǒng)里還能見到。它的優(yōu)勢是簡單直接沒有反射開銷劣勢是每個Controller只能處理一個URL而且參數(shù)綁定要自己寫。如果你在維護老項目看到這種寫法不要驚訝它和Controller是可以共存的因為兩個適配器都注冊了各管各的。3.4 HttpRequestHandlerAdapter與靜態(tài)資源處理HttpRequestHandlerAdapter處理HttpRequestHandler最典型的應用是ResourceHttpRequestHandler——也就是Spring MVC處理靜態(tài)資源的機制。當你配置了mvc:resources或者addResourceHandlers請求靜態(tài)文件時走的就是這個適配器。它的handle方法會調(diào)用handler.handleRequest而ResourceHttpRequestHandler會去查找資源文件、設置Content-Type、處理Last-Modified和ETag、支持Range請求。這也是為什么Spring MVC處理靜態(tài)資源的性能其實不差——它做了完整的HTTP緩存協(xié)商。3.5 適配器的注冊與初始化順序在WebMvcConfigurationSupport里默認適配器的注冊順序是Bean public HandlerAdapter requestMappingHandlerAdapter() { ... } Bean public HandlerAdapter httpRequestHandlerAdapter() { ... } Bean public HandlerAdapter simpleControllerHandlerAdapter() { ... }注意requestMappingHandlerAdapter排在最前面。這個順序決定了當handler同時滿足多個適配器的supports時優(yōu)先用哪個。實際上HandlerMethod只被RequestMappingHandlerAdapter支持所以順序影響不大但理解這個機制對自定義適配器很重要。4. 自定義HandlerAdapter的完整實操過程4.1 什么場景下需要自定義適配器大部分項目一輩子都不需要自定義HandlerAdapter。但以下幾種場景自定義是合理的你有一套自己的處理器抽象比如基于注解的RPC方法想復用Spring MVC的請求分發(fā)機制你想對特定類型的handler做統(tǒng)一的預處理比如統(tǒng)一的日志、鑒權、限流你在做框架層面的擴展比如實現(xiàn)一個輕量級的API網(wǎng)關需要強調(diào)的是如果你的需求只是在Controller執(zhí)行前后做點事用HandlerInterceptor就夠了不要上適配器。適配器的粒度更粗它是如何調(diào)用handler層面的擴展不是調(diào)用前后層面的。4.2 定義自定義handler與適配器假設我們要實現(xiàn)一個簡單的場景某些類實現(xiàn)了ApiHandler接口它們的handle方法接收一個MapString, Object參數(shù)返回一個Map結果框架自動把結果序列化成JSON。先定義handler接口public interface ApiHandler { MapString, Object handle(MapString, Object params); }然后寫適配器public class ApiHandlerAdapter implements HandlerAdapter { private final ObjectMapper objectMapper new ObjectMapper(); Override public boolean supports(Object handler) { return handler instanceof ApiHandler; } Override public ModelAndView handle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { ApiHandler apiHandler (ApiHandler) handler; MapString, Object params extractParams(request); MapString, Object result apiHandler.handle(params); response.setContentType(application/json;charsetUTF-8); response.setStatus(HttpServletResponse.SC_OK); objectMapper.writeValue(response.getWriter(), result); return null; } Override public long getLastModified(HttpServletRequest request, Object handler) { return -1; } private MapString, Object extractParams(HttpServletRequest request) { MapString, Object params new HashMap(); EnumerationString names request.getParameterNames(); while (names.hasMoreElements()) { String name names.nextElement(); params.put(name, request.getParameter(name)); } return params; } }這個適配器做了三件事從請求里提取參數(shù)、調(diào)用handler、把結果寫成JSON。返回null的ModelAndView告訴DispatcherServlet不需要渲染視圖。4.3 注冊適配器到Spring MVC注冊方式取決于你的配置方式。如果是Java ConfigConfiguration EnableWebMvc public class WebConfig implements WebMvcConfigurer { Override public void addArgumentResolvers(ListHandlerMethodArgumentResolver resolvers) { // 參數(shù)解析器擴展 } Bean public ApiHandlerAdapter apiHandlerAdapter() { return new ApiHandlerAdapter(); } }但這里有個坑Bean注冊的HandlerAdapter會被加到默認適配器列表里但順序不確定。如果你想確保它在特定位置需要更精細的控制。更可靠的方式是重寫requestMappingHandlerAdapter的配置或者直接操作RequestMappingHandlerMapping。實際上Spring MVC的適配器列表是在DispatcherServlet.initHandlerAdapters里初始化的它會從容器里拿所有HandlerAdapter類型的Bean然后按Order排序。所以給自定義適配器加Order注解可以控制順序Bean Order(0) public ApiHandlerAdapter apiHandlerAdapter() { return new ApiHandlerAdapter(); }4.4 讓自定義handler被HandlerMapping發(fā)現(xiàn)光有適配器還不夠DispatcherServlet得先通過HandlerMapping找到你的handler。默認的RequestMappingHandlerMapping只認Controller和RequestMapping。要讓ApiHandler被識別需要自定義HandlerMappingpublic class ApiHandlerMapping extends AbstractHandlerMapping { private final MapString, ApiHandler handlerMap new HashMap(); public void registerHandler(String path, ApiHandler handler) { handlerMap.put(path, handler); } Override protected Object getHandlerInternal(HttpServletRequest request) throws Exception { String path request.getRequestURI(); return handlerMap.get(path); } }然后在配置里注冊這個HandlerMapping。注意HandlerMapping和HandlerAdapter是配套的HandlerMapping負責找到handlerHandlerAdapter負責執(zhí)行handler。兩者通過handler對象關聯(lián)但彼此不知道對方的存在這是Spring MVC解耦的關鍵。4.5 參數(shù)提取的健壯性處理上面extractParams的實現(xiàn)很粗糙只處理了query參數(shù)。實際項目中要考慮POST請求的body解析JSON、form-data文件上傳字符編碼參數(shù)類型轉(zhuǎn)換如果這些都要自己寫工作量不小。這也是為什么大部分場景下直接用RequestMapping更劃算——Spring已經(jīng)幫你處理好了所有這些細節(jié)。自定義適配器的價值在于特殊場景的定制不是重新造輪子。實操心得寫自定義適配器時參數(shù)提取和結果序列化這兩塊最容易出問題。建議先用最簡單的實現(xiàn)跑通流程再逐步增加復雜度。不要一上來就想著支持所有Content-Type先把application/json和application/x-www-form-urlencoded搞定覆蓋80%的場景。5. 常見問題與排查技巧實錄5.1 參數(shù)綁定失敗從異常棧定位到解析器參數(shù)綁定失敗是最高頻的問題。典型異常是MissingServletRequestParameterException、MethodArgumentTypeMismatchException、HttpMessageNotReadableException。排查思路是看異常類型確定是哪個解析器拋的看異常信息里的參數(shù)名確認是哪個參數(shù)檢查請求實際發(fā)送的內(nèi)容用抓包工具或日志對照解析器的supportsParameter邏輯判斷為什么匹配到了這個解析器比如HttpMessageNotReadableException通常是RequestResponseBodyMethodProcessor拋的說明RequestBody的JSON解析失敗。原因可能是請求體為空、JSON格式錯誤、目標類型沒有默認構造函數(shù)、字段類型不匹配。這時候打開DEBUG日志看Jackson的具體報錯信息比看異常棧有用得多。5.2 返回值處理異常ResponseBody的坑ResponseBody返回對象時如果序列化失敗會拋HttpMessageNotWritableException。常見原因?qū)ο罄镉醒h(huán)引用比如雙向關聯(lián)的實體對象里有無法序列化的類型比如InputStream返回的是null但配置了不允許null循環(huán)引用是最隱蔽的。比如Order里有ListOrderItemOrderItem里又有Order的引用Jackson序列化時會無限遞歸。解決辦法是用JsonIgnore或者JsonManagedReference/JsonBackReference。5.3 適配器不生效supports返回false的排查自定義適配器不生效第一步是確認supports有沒有被調(diào)用?？梢栽趕upports里打日志看請求進來時有沒有打印。如果沒有說明HandlerMapping沒找到你的handler或者handler類型不對。如果有打印但返回false檢查instanceof判斷。還有一種情況適配器被調(diào)用了但用的是別的適配器。這時候看DispatcherServlet的DEBUG日志它會打印Using handler adapter [xxx]。如果用的是內(nèi)置適配器說明你的handler被內(nèi)置適配器先匹配上了。5.4 常見問題速查表問題現(xiàn)象可能原因排查方向405 Method Not AllowedcheckRequest校驗失敗檢查RequestMapping的method配置415 Unsupported Media TypeContent-Type不匹配檢查consumes配置和請求頭400 Bad Request參數(shù)綁定失敗看異常類型定位解析器500 序列化異常返回值無法序列化檢查循環(huán)引用、null值自定義適配器不生效supports返回false或順序問題打日志確認調(diào)用鏈靜態(tài)資源404ResourceHttpRequestHandler未匹配檢查資源路徑配置5.5 獨家避坑技巧第一個技巧調(diào)試適配器問題時把org.springframework.web.servlet.DispatcherServlet的日志級別調(diào)到DEBUG它會打印handler、adapter、interceptor的完整匹配過程。這比斷點調(diào)試高效得多。第二個技巧RequestMappingHandlerAdapter的argumentResolvers和returnValueHandlers是可以通過Bean覆蓋的。如果你需要全局修改參數(shù)解析行為不要改源碼直接提供一個自定義的RequestMappingHandlerAdapterBean設置你自己的解析器列表。第三個技巧ControllerAdvice配合ExceptionHandler能處理大部分異常但有些異常在適配器層面就拋出了還沒到Controller。比如HttpRequestMethodNotSupportedException它是在checkRequest里拋的ExceptionHandler能捕獲但如果你自定義了適配器要確保異常能正常傳播出去。第四個技巧getLastModified返回-1表示不支持緩存返回具體時間戳表示支持。如果你做的是內(nèi)容型接口實現(xiàn)這個方法能顯著降低服務器壓力。但要注意時間戳的精度是秒級如果內(nèi)容變化頻繁緩存反而會導致數(shù)據(jù)不一致。6. 從適配器看Spring MVC的擴展哲學HandlerAdapter這個接口只有三個方法但它體現(xiàn)了Spring框架一以貫之的設計哲學面向接口編程、職責單一、通過組合而非繼承實現(xiàn)擴展。DispatcherServlet不關心handler是什么只關心有沒有適配器能處理它適配器不關心請求怎么來的只關心怎么調(diào)用handlerhandler不關心框架怎么運作只關心我的業(yè)務邏輯。這種分層讓每一層都可以獨立演化。你可以換掉HandlerMapping而不影響適配器可以新增適配器而不影響DispatcherServlet可以自定義handler而不影響其他組件。理解了這一點再看Spring MVC的其他組件——ViewResolver、HandlerExceptionResolver、MultipartResolver——會發(fā)現(xiàn)它們都是同一個套路的產(chǎn)物。我在實際項目中做過一次比較激進的改造把RequestMappingHandlerAdapter替換成了一個自定義實現(xiàn)在invokeHandlerMethod之前插入了統(tǒng)一的參數(shù)校驗和日志記錄。改造過程比想象中順利因為適配器的邊界非常清晰只要保證handle方法的輸入輸出契約不變內(nèi)部怎么改都不會影響其他組件。這種可替換性正是良好抽象的價值所在。如果你正在維護一個中大型的Spring MVC項目建議花半天時間把DispatcherServlet、HandlerMapping、HandlerAdapter這三者的協(xié)作關系畫一遍。不需要畫得多漂亮關鍵是理清請求進來之后每一步是誰在處理、處理完交給誰。理清之后再遇到路由、參數(shù)、返回值相關的問題定位速度會快一個數(shù)量級。