很多剛接觸 Spring 的后端同學(xué)都栽在“請(qǐng)求參數(shù)傳遞”這一關(guān)上。明明前端把參數(shù)傳了后端卻收到 null明明寫(xiě)了RequestParam卻報(bào)了 400明明 Postman 里測(cè)得好好的一接 axios 就崩。這些問(wèn)題的根源往往不是參數(shù)寫(xiě)錯(cuò)了而是根本沒(méi)有搞清楚 Spring 底層是怎樣把 HTTP 請(qǐng)求里的數(shù)據(jù)“翻譯”成 Java 方法參數(shù)的。所以這篇博文我就結(jié)合自己多年 Java EE 經(jīng)驗(yàn)把 Spring 請(qǐng)求參數(shù)傳遞這件事徹底講透從 HTTP 請(qǐng)求本身的參數(shù)存放位置到 Spring MVC 的參數(shù)綁定原理再到RequestParam、PathVariable、RequestBody等注解的細(xì)節(jié)以及前后端聯(lián)調(diào)中的經(jīng)典坑位和排查思路。無(wú)論你是剛?cè)腴T(mén) Spring Boot 的新人還是寫(xiě)了好幾年業(yè)務(wù)代碼但一直靠“試錯(cuò)”調(diào)參的老手這篇文章都值得你完整讀一遍。1. 請(qǐng)求參數(shù)傳遞的整體設(shè)計(jì)思路1.1 先從 HTTP 請(qǐng)求說(shuō)起參數(shù)到底放在哪里每次請(qǐng)求從客戶端發(fā)到服務(wù)端本質(zhì)上就是一個(gè) HTTP 報(bào)文。報(bào)文的參數(shù)可以藏在三個(gè)位置URL 路徑、URL 查詢字符串、請(qǐng)求體。這三個(gè)位置對(duì)應(yīng)了三種最典型的攜帶方式我先用一張表把它們的關(guān)系和典型場(chǎng)景說(shuō)清楚。參數(shù)位置典型形式常見(jiàn)場(chǎng)景對(duì)應(yīng) Spring 注解路徑Path/user/1001RESTful 風(fēng)格定位資源PathVariable查詢字符串Query/user?age18GET 請(qǐng)求的過(guò)濾條件RequestParam請(qǐng)求體Body{name:Tom}POST/PUT 提交數(shù)據(jù)RequestBody請(qǐng)求頭HeaderX-Token: abc身份認(rèn)證、元信息RequestHeaderCookieJSESSIONIDxxx會(huì)話保持、登錄態(tài)CookieValue很多新手容易忽略的是同一個(gè)接口完全可能同時(shí)從多個(gè)位置取參數(shù)。比如一個(gè)分頁(yè)查詢接口路徑里傳用戶 ID查詢字符串里傳頁(yè)碼和大小請(qǐng)求頭里帶 token三個(gè)位置的數(shù)據(jù)都需要。Spring MVC 天生支持這種多來(lái)源綁定關(guān)鍵是你得把注解寫(xiě)對(duì)。再補(bǔ)充一個(gè)基礎(chǔ)但高頻的疑問(wèn)GET和POST并不是參數(shù)位置的唯一決定因素。GET 也能帶 BodyPOST 也能把參數(shù)放在查詢字符串里。只是 HTTP 規(guī)范和瀏覽器、代理服務(wù)器對(duì) GET 帶 Body 支持得不好所以實(shí)際開(kāi)發(fā)中約定俗成GET 用查詢字符串POST 用 Body。用 Spring 注解時(shí)RequestParam可以同時(shí)接收查詢字符串和表單 Body 參數(shù)RequestBody則是把整個(gè) Body 反序列化成對(duì)象二者用途完全不同。1.2 Spring MVC 參數(shù)綁定機(jī)制你的參數(shù)是如何“自動(dòng)”進(jìn)方法的假設(shè)你寫(xiě)了一個(gè)接口GetMapping(/user) public String getUser(RequestParam(id) Long id) { return user: id; }當(dāng)瀏覽器請(qǐng)求/user?id123時(shí)Spring 并不是變魔術(shù)它內(nèi)部經(jīng)歷了這樣幾步DispatcherServlet接收到請(qǐng)求根據(jù) URL 找到匹配的HandlerMethod。然后交給HandlerMethodArgumentResolver這個(gè)“解析器軍團(tuán)”挨個(gè)判斷當(dāng)前方法每個(gè)參數(shù)需要哪種解析器。對(duì)于RequestParam注解的參數(shù)會(huì)由RequestParamMethodArgumentResolver處理。它把request.getParameter(id)拿到的字符串123交給ConversionService做類型轉(zhuǎn)換變成Long。轉(zhuǎn)換成功后把值反射注入到方法參數(shù)里然后執(zhí)行方法。這個(gè)過(guò)程聽(tīng)起來(lái)簡(jiǎn)單但里面藏著兩個(gè)關(guān)鍵點(diǎn)恰恰是各種 bug 的來(lái)源。第一類型轉(zhuǎn)換。Spring 默認(rèn)提供了一套強(qiáng)大的類型轉(zhuǎn)換器字符串轉(zhuǎn)數(shù)字、轉(zhuǎn)布爾、轉(zhuǎn)日期都能搞定。但如果傳入的值本身不是合法格式比如給Long傳abc就會(huì)拋MethodArgumentTypeMismatchException表現(xiàn)成 400 錯(cuò)誤。所以前端傳參時(shí)類型必須匹配。第二參數(shù)名匹配。Spring 默認(rèn)要求請(qǐng)求里的參數(shù)名和方法注解里寫(xiě)的名字一致。比如RequestParam(id)請(qǐng)求里就必須有id。一旦前端傳的是userId那拿到的就是 null如果沒(méi)配置 required或者直接報(bào)錯(cuò)如果 requiredtrue 默認(rèn)就是 true。理解了這層機(jī)制再看各種注解就會(huì)很容易。PathVariable是靠“模板變量名”匹配路徑片段RequestBody是用HttpMessageConverter反序列化 JSON 字符串為 Java 對(duì)象RequestHeader則是從請(qǐng)求頭里取值后走同樣的類型轉(zhuǎn)換流程。本質(zhì)上都是“取出字符串 - 類型轉(zhuǎn)換 - 綁定到參數(shù)”只是取值位置不同。2. 常見(jiàn)傳參方式全面拆解2.1 RequestParam查詢參數(shù)和表單參數(shù)的“萬(wàn)金油”RequestParam是使用頻率最高的傳參注解它可以接收查詢字符串參數(shù)也可以接收表單格式的 Body 參數(shù)application/x-www-form-urlencoded。我一般把它當(dāng)作“非 JSON 體的簡(jiǎn)單參數(shù)入口”。基本寫(xiě)法GetMapping(/search) public String search(RequestParam(keyword) String keyword, RequestParam(value page, defaultValue 1) Integer page, RequestParam(value size, required false) Integer size) { return keyword keyword , page page , size size; }這里有幾個(gè)細(xì)節(jié)值得強(qiáng)調(diào)。value指定參數(shù)名如果前端傳的參數(shù)名和變量名一致可以省略比如寫(xiě)成RequestParam String keyword。但我不建議省略尤其項(xiàng)目里出現(xiàn)縮寫(xiě)或語(yǔ)義不直觀的變量名時(shí)顯式寫(xiě)名字能避免聯(lián)調(diào)時(shí)被前端坑。defaultValue表示默認(rèn)值一旦設(shè)置required會(huì)自動(dòng)變?yōu)?false。它的值在 Spring 里是字符串最終會(huì)走類型轉(zhuǎn)換器轉(zhuǎn)成目標(biāo)類型。所以defaultValue 1可以給Integer用defaultValue true可以給boolean用。required false表示可選參數(shù)。不傳時(shí)參數(shù)值為 null。但如果required true默認(rèn)且沒(méi)傳會(huì)直接拋MissingServletRequestParameterException返回 400。這個(gè)異常在全局異常處理器里需要特殊處理否則前端收到的是默認(rèn)的錯(cuò)誤 JSON很不友好。另外RequestParam支持接收一個(gè)集合或數(shù)組。比如前端傳?id1id2id3后端可以這樣接收GetMapping(/batch) public String batch(RequestParam(id) ListLong ids) { return ids ids; }Spring 遇到同名參數(shù)多次出現(xiàn)時(shí)會(huì)自動(dòng)把多個(gè)值組裝成 List。這個(gè)能力在處理多選條件、批量操作時(shí)非常好用。2.2 PathVariableRESTful 風(fēng)格里的路徑參數(shù)如果你的接口是 RESTful 風(fēng)格比如/user/{id}那必須用PathVariable。它從 URL 路徑中提取模板變量而不是查詢字符串。GetMapping(/user/{id}) public User getUser(PathVariable(id) Long id) { return userService.getById(id); }和RequestParam一樣PathVariable也會(huì)做類型轉(zhuǎn)換。如果傳了/user/abc而參數(shù)類型是Long一樣會(huì)報(bào) 400。實(shí)際項(xiàng)目中路徑參數(shù)常和查詢參數(shù)混合使用。比如GetMapping(/order/{orderId}/items) public ListItem getOrderItems(PathVariable(orderId) Long orderId, RequestParam(required false) String status) { // ... }這時(shí)候orderId從路徑取status從查詢字符串取互不干擾。一個(gè)容易踩的坑是路徑參數(shù)包含特殊字符比如/file/{name}如果name是report.pdfpdf會(huì)被當(dāng)成路徑的一部分沒(méi)問(wèn)題但如果name是a/b.pdf斜杠可能被服務(wù)器解析成路徑分隔符導(dǎo)致無(wú)法匹配到接口。解決方法是使用 URL 編碼前端把a(bǔ)/b.pdf編碼成a%2Fb.pdf。但有些代理服務(wù)器默認(rèn)不會(huì)解碼%2F所以設(shè)計(jì)接口時(shí)最好避開(kāi)這種場(chǎng)景或者用查詢參數(shù)傳文件名。2.3 RequestBody接收 JSON 數(shù)據(jù)體的正確姿勢(shì)當(dāng)前后端約定用 JSON 格式交互時(shí)RequestBody是核心注解。它把請(qǐng)求體中的 JSON 字符串反序列化成 Java 對(duì)象。Spring Boot 默認(rèn)依賴 Jackson 庫(kù)絕大多數(shù)情況下不用額外配置。PostMapping(/user) public User createUser(RequestBody UserCreateDTO dto) { return userService.create(dto); }UserCreateDTO中的字段名需要和 JSON 中的 key 對(duì)應(yīng)。默認(rèn)情況下Jackson 會(huì)把 JSON 的userName映射到 Java 的userName字段。如果前端傳的是username下劃線風(fēng)格而后端是userName駝峰就會(huì)映射失敗。解決方式有兩種在實(shí)體字段上用JsonProperty(username)顯式指定。在 Spring Boot 配置文件中統(tǒng)一開(kāi)啟駝峰轉(zhuǎn)換spring: jackson: property-naming-strategy: SNAKE_CASE我推薦方案一因?yàn)榕渲梦募侨稚У暮芸赡馨褎e的字段也帶偏。而JsonProperty精確到字段最可控。RequestBody還有一個(gè)高頻坑傳空 Body 或 Body 不是合法 JSON 時(shí)會(huì)報(bào)HttpMessageNotReadableException。建議在接口上加上參數(shù)校驗(yàn)注解比如Validated配合 DTO 里的NotNull、Size等把錯(cuò)誤提前攔截在入口。此外RequestBody接收的數(shù)據(jù)類型不一定非是 POJO也可以是MapString, Object或者JsonNode。對(duì)于不確定字段結(jié)構(gòu)的外部回調(diào)或透?jìng)鹘涌谖医?jīng)常直接用Map接收等摸清字段再改成 DTO。2.4 RequestHeader 和 CookieValue藏在“附屬信息”里的參數(shù)請(qǐng)求頭參數(shù)常被用來(lái)傳遞認(rèn)證信息、追蹤 ID、客戶端類型等。獲取方式如下GetMapping(/info) public String info(RequestHeader(X-Request-Id) String requestId, RequestHeader(value X-User-Agent, required false) String userAgent) { return requestId requestId , userAgent userAgent; }注意請(qǐng)求頭的名字不區(qū)分大小寫(xiě)但建議保持一致性。這個(gè)注解同樣支持required和defaultValue。如果請(qǐng)求頭缺失且required trueSpring 會(huì)直接拋異常。CookieValue用來(lái)讀取 Cookie 中的值GetMapping(/session) public String session(CookieValue(value SESSIONID, required false) String sessionId) { return sessionId sessionId; }我在微服務(wù)網(wǎng)關(guān)層做透?jìng)鲿r(shí)經(jīng)常用RequestHeader獲取內(nèi)部定義的調(diào)用方標(biāo)識(shí)再把它繼續(xù)往下一個(gè)服務(wù)傳遞。這里有個(gè)細(xì)節(jié)從請(qǐng)求頭取出來(lái)的字符串如果包含非法特殊字符某些網(wǎng)關(guān)會(huì)拒絕所以自定義請(qǐng)求頭時(shí)盡量用字母、數(shù)字、中劃線。3. 復(fù)雜場(chǎng)景下的參數(shù)處理與配置3.1 參數(shù)校驗(yàn)與類型轉(zhuǎn)換別讓臟數(shù)據(jù)進(jìn)入 Service 層如果接口只接收基礎(chǔ)類型Spring 的ConversionService能處理大部分轉(zhuǎn)換。但遇到枚舉、日期、自定義對(duì)象時(shí)你得主動(dòng)介入。日期參數(shù)是最典型的例子。前端傳2024-06-01后端用Date接收直接在參數(shù)上寫(xiě)GetMapping(/date) public String date(RequestParam(date) Date date) { return date.toString(); }Spring Boot 默認(rèn)的日期格式是yyyy/MM/dd如果你的前端傳的是2024-06-01就會(huì)報(bào)轉(zhuǎn)換錯(cuò)誤。解決辦法是在配置文件中指定格式spring: mvc: format: date: yyyy-MM-dd date-time: yyyy-MM-dd HH:mm:ss如果你用的是RequestBody加 DTO里面包含LocalDate字段則需要在字段上加格式化注解public class QueryDTO { DateTimeFormat(pattern yyyy-MM-dd) private LocalDate startDate; }或者配合JsonFormat(pattern yyyy-MM-dd, timezone GMT8)后者專門(mén)處理 Jackson 的 JSON 反序列化。記住一個(gè)原則查詢參數(shù)用DateTimeFormatJSON Body 用JsonFormat兩者場(chǎng)景不同別混用。枚舉轉(zhuǎn)換也很容易踩坑。假設(shè)有個(gè)枚舉Gender { MALE, FEMALE }前端傳的是MALESpring 默認(rèn)按枚舉名轉(zhuǎn)換沒(méi)問(wèn)題。但如果前端傳的是male或1就不行了。這時(shí)候要么前端改要么寫(xiě)一個(gè)自定義Converter把字符串映射成枚舉。我通常建議后端兜底因?yàn)榍岸瞬豢煽匾蛩靥?。參?shù)校驗(yàn)方面我習(xí)慣在 DTO 上直接使用javax.validation注解比如public class UserCreateDTO { NotBlank(message 用戶名不能為空) private String username; Min(value 1, message 年齡最小為1) private Integer age; }然后在 Controller 參數(shù)上加Valid或ValidatedPostMapping(/user) public User createUser(Valid RequestBody UserCreateDTO dto) { // ... }這樣校驗(yàn)失敗時(shí)Spring 會(huì)拋出MethodArgumentNotValidException你可以在全局異常處理器里統(tǒng)一捕獲把每條錯(cuò)誤信息包裝成統(tǒng)一的響應(yīng)結(jié)構(gòu)返回前端。3.2 數(shù)組、集合與嵌套對(duì)象傳參從URL到復(fù)雜DTOGET 請(qǐng)求傳數(shù)組的場(chǎng)景很常見(jiàn)比如批量刪除、多選篩選。剛才提到了同名多值另一種常見(jiàn)寫(xiě)法是使用逗號(hào)分隔/user?ids1,2,3后端接收GetMapping(/user) public String getUser(RequestParam(ids) ListLong ids) { return ids ids; }Spring 對(duì)ListLong類型參數(shù)會(huì)自動(dòng)按逗號(hào)分隔解析并逐個(gè)轉(zhuǎn)換類型。實(shí)測(cè)下來(lái)很穩(wěn)省去了手動(dòng) split 的麻煩。嵌套對(duì)象在表單傳參中比較棘手。比如public class SearchDTO { private String keyword; private PageParam page; } public class PageParam { private Integer current; private Integer size; }前端傳參時(shí)要寫(xiě)成/search?keywordtestpage.current1page.size10Spring 能夠自動(dòng)將page.current綁定到SearchDTO對(duì)象里的page對(duì)象的current字段。這種用點(diǎn)號(hào)分隔的傳參方式非常適合復(fù)雜查詢條件的拼接而且不需要額外注解只要在方法參數(shù)上寫(xiě)SearchDTO dto就行。但要注意這種方式只適用于 GET 請(qǐng)求的查詢字符串或表單請(qǐng)求。如果是 JSON Body你直接傳嵌套 JSON 對(duì)象RequestBody自動(dòng)處理不需要顧慮點(diǎn)號(hào)問(wèn)題。兩種方式不要混用否則前端會(huì)迷糊。3.3 文件上傳與 Multipart 參數(shù)不只是 MultipartFile文件上傳是后端繞不開(kāi)的場(chǎng)景。Spring MVC 對(duì)multipart/form-data有原生支持。接口寫(xiě)法如下PostMapping(/upload) public String upload(RequestParam(file) MultipartFile file, RequestParam(description) String description) { // 處理文件 return fileName file.getOriginalFilename() , desc description; }前端用 FormData 提交時(shí)文件字段名必須和RequestParam(file)的 value 對(duì)應(yīng)。除了文件表單里還可以帶普通字段如上例的description。在 Spring Boot 中上傳文件還需要配置大小限制否則超過(guò)默認(rèn) 1MB 會(huì)被靜默丟棄或報(bào)錯(cuò)。常見(jiàn)配置spring: servlet: multipart: max-file-size: 10MB max-request-size: 20MB這里有兩個(gè)參數(shù)max-file-size限制單個(gè)文件大小max-request-size限制整個(gè)請(qǐng)求的大小。如果你上傳多個(gè)文件后者更重要。多文件上傳用ListMultipartFile或MultipartFile[]PostMapping(/upload/batch) public String batchUpload(RequestParam(files) ListMultipartFile files) { // ... }前端表單里多個(gè)input typefile namefiles即可。文件上傳有個(gè)隱蔽問(wèn)題如果上傳時(shí)還帶了 JSON 結(jié)構(gòu)的業(yè)務(wù)參數(shù)MultipartFile和RequestBody不能同時(shí)出現(xiàn)在同一個(gè)方法里因?yàn)镽equestBody會(huì)嘗試把整個(gè)請(qǐng)求體當(dāng)作 JSON 解析而 multipart 請(qǐng)求體是分段的二者沖突。正確做法是文件走 multipart業(yè)務(wù)參數(shù)用RequestParam逐字段接收或者在上傳 JSON 里用 Base64 編碼嵌入文件。實(shí)際項(xiàng)目中我遇到復(fù)雜的“文件嵌套對(duì)象”場(chǎng)景時(shí)會(huì)建議前端先把對(duì)象字段序列化成 JSON 字符串后端再用字符串接收后手動(dòng)parseObject這樣既避開(kāi) multipart 和 JSON 的兼容問(wèn)題也保留靈活性。3.4 自定義參數(shù)解析器當(dāng)標(biāo)準(zhǔn)注解不夠用時(shí)的殺手锏有些參數(shù)傳遞需求很特殊比如每次請(qǐng)求都要從請(qǐng)求頭里解析出用戶信息然后注入到每個(gè) Controller 方法里。雖然可以通過(guò)攔截器 ThreadLocal 實(shí)現(xiàn)但如果想直接在方法參數(shù)上拿到對(duì)象標(biāo)準(zhǔn)注解做不到這時(shí)可以自定義HandlerMethodArgumentResolver。實(shí)現(xiàn)步驟不算復(fù)雜。定義一個(gè)注解例如CurrentUser再寫(xiě)一個(gè)解析器public class CurrentUserArgumentResolver implements HandlerMethodArgumentResolver { Override public boolean supportsParameter(MethodParameter parameter) { return parameter.hasParameterAnnotation(CurrentUser.class) parameter.getParameterType().equals(UserInfo.class); } Override public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer, NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception { HttpServletRequest request webRequest.getNativeRequest(HttpServletRequest.class); // 從請(qǐng)求頭或Token中解析用戶信息 UserInfo userInfo parseUser(request.getHeader(X-User)); return userInfo; } }然后在配置類中注冊(cè)Configuration public class WebConfig implements WebMvcConfigurer { Override public void addArgumentResolvers(ListHandlerMethodArgumentResolver resolvers) { resolvers.add(new CurrentUserArgumentResolver()); } }之后 Controller 方法里直接寫(xiě)GetMapping(/me) public UserInfo getMe(CurrentUser UserInfo user) { return user; }這個(gè)思路適合那些“每個(gè)接口都要用到但又不屬于業(yè)務(wù)參數(shù)”的數(shù)據(jù)比如當(dāng)前登錄用戶、網(wǎng)關(guān)透?jìng)鞯?client 信息。自定義解析器寫(xiě)好后一勞永逸也避免在每個(gè)方法里重復(fù)寫(xiě)解析代碼。手寫(xiě) Spring 的朋友看到這里應(yīng)該有親切感Spring Boot 本質(zhì)上是把大量的解析器做成了可插拔組件。4. 聯(lián)調(diào)中的常見(jiàn)問(wèn)題與排查技巧4.1 參數(shù)名、類型和編碼三大經(jīng)典翻車(chē)現(xiàn)場(chǎng)第一種翻車(chē)參數(shù)名對(duì)不上。前端傳userName后端寫(xiě)RequestParam(name)結(jié)果拿到 null。排查時(shí)先確認(rèn)前后端接口文檔建議讓前端直接用后端定義的參數(shù)名字或者在 Swagger/OpenAPI 里導(dǎo)出規(guī)范。第二種翻車(chē)類型不匹配。前端傳18后端是Integer多數(shù)能正常轉(zhuǎn)換。但前端傳18.5就會(huì) 400。有些前端會(huì)把長(zhǎng)整型 ID 改成字符串因?yàn)?JS 的 Number 精度不夠比如雪花 ID 超過(guò) 16 位時(shí)后端返回給前端會(huì)丟精度。解決方法是后端把 ID 序列化為 String或在 DTO 中將 ID 聲明為 String 類型。不要盲目讓前端轉(zhuǎn)寧可后端多設(shè)計(jì)一層 DTO。第三種翻車(chē)中文亂碼。GET 請(qǐng)求的中文很容易亂碼因?yàn)?URL 里默認(rèn)只允許 ASCII。前端沒(méi)做 URL 編碼時(shí)中文拼接進(jìn)來(lái)會(huì)亂。解決方法是前端用encodeURIComponent后端容器設(shè)置 UTF-8。Spring Boot 大多已默認(rèn) UTF-8但如果你手動(dòng)改了server.servlet.encoding要注意請(qǐng)求和響應(yīng)兩個(gè) charset 都配置正確。4.2 GET 和 POST 的混用誤區(qū)為什么 Postman 能通而 axios 不能很多時(shí)候 Postman 測(cè)接口沒(méi)問(wèn)題切到 axios 就報(bào)錯(cuò)。原因往往是 Postman 自動(dòng)幫你設(shè)置了Content-Type而 axios 沒(méi)有。比如你寫(xiě)了一個(gè)接口接收RequestParam同時(shí)在 Spring Security 或攔截器里限制了POST那么 axios 用POST時(shí)默認(rèn)會(huì)發(fā)送application/x-www-form-urlencoded嗎不一定。axios 常見(jiàn)的三種傳參方式params放在查詢字符串對(duì)應(yīng) GET。data放在請(qǐng)求體對(duì)應(yīng) POST。如果data里直接放一個(gè)普通對(duì)象axios 默認(rèn)會(huì)序列化成 JSON 并設(shè)置Content-Type: application/json。舉例axios.post(/api/user, { id: 1 }) // 這種是 JSON Body但是后端如果是PostMapping(/api/user) public String getUser(RequestParam(id) Long id) { ... }那么后端會(huì)報(bào)缺參因?yàn)镽equestParam只從查詢字符串或表單里取不讀 JSON Body。要么前端改成axios.post(/api/user, null, { params: { id: 1 } })要么后端改用RequestBody接收。這屬于最常見(jiàn)的混用錯(cuò)誤。排查思路很簡(jiǎn)單把請(qǐng)求在瀏覽器 Network 里打開(kāi)看Query String Parameters和Request Payload的區(qū)別。如果參數(shù)在 Payload 里是 JSON就要用RequestBody如果在 Query 里就用RequestParam。4.3 Postman 與 curl如何快速驗(yàn)證接口參數(shù)調(diào)試接口時(shí)使用 Postman 或 curl 能很大程度提高定位效率。比如一個(gè) POST 接口要傳 JSONcurl 寫(xiě)法curl -X POST http://localhost:8080/user \ -H Content-Type: application/json \ -d {username:Tom,age:18}如果要傳表單curl -X POST http://localhost:8080/user \ -d usernameTomage18如果要傳文件和普通字段curl -X POST http://localhost:8080/upload \ -F filetest.txt \ -F descriptionhello這三個(gè) curl 命令對(duì)應(yīng)的 Content-Type 分別是 JSON、表單、multipart。我用 curl 驗(yàn)證接口時(shí)會(huì)特意觀察請(qǐng)求頭里的Content-Type是否正確因?yàn)楹芏鄨?bào)錯(cuò)都和這個(gè)頭有關(guān)。Postman 里也一樣Body 區(qū)域有 none、form-data、x-www-form-urlencoded、raw 四種模式。選錯(cuò)模式就相當(dāng)于換了 Content-Type接口自然不通。曾經(jīng)有個(gè)同事把 JSON 放到了 form-data 里后端怎么接都接不到改成 raw 并選擇 JSON 后立刻通了。這類問(wèn)題在聯(lián)調(diào)中出現(xiàn)的頻率極高建議后端同學(xué)把常見(jiàn)三種模式都測(cè)一遍。4.4 攔截器與過(guò)濾器中的參數(shù)處理增刪改查之后的隱形關(guān)卡有時(shí)參數(shù)在進(jìn)入 Controller 之前已經(jīng)在攔截器或過(guò)濾器里被處理過(guò)了。比如一個(gè)Filter讀取了請(qǐng)求體的輸入流而RequestBody也需要讀輸入流但流只能讀一次。如果過(guò)濾器里先調(diào)用了getInputStream()或getReader()再進(jìn)入 Controller 后RequestBody就會(huì)讀到空流導(dǎo)致接口拿不到參數(shù)報(bào)HttpMessageNotReadableException。解決方案是使用ContentCachingRequestWrapper包裝請(qǐng)求讓后續(xù)可以重復(fù)讀取 Body。Spring 提供了現(xiàn)成的類但應(yīng)用時(shí)要小心WebFilter(/*) public class RequestWrapperFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest (HttpServletRequest) request; ContentCachingRequestWrapper wrapper new ContentCachingRequestWrapper(httpRequest); chain.doFilter(wrapper, response); } }不過(guò)ContentCachingRequestWrapper默認(rèn)不緩存到一定條件下才生效如果你想完整讀取 Body最好直接自定義一個(gè)包裝類把 Body 字節(jié)數(shù)組緩存到內(nèi)存里再重寫(xiě)getInputStream和getReader方法。這類問(wèn)題不僅發(fā)生在過(guò)濾器也發(fā)生在 Spring Cloud Gateway 等網(wǎng)關(guān)層。如果你在網(wǎng)關(guān)里改了請(qǐng)求體比如把明文改成密文下游服務(wù)接收前必須重新包裝。所以排查參數(shù)問(wèn)題時(shí)不要只盯 Controller還要看有沒(méi)有攔截器、過(guò)濾器、AOP 切面對(duì)HttpServletRequest做了額外操作。另一個(gè)和攔截器相關(guān)的坑是參數(shù)被加密或簽名。比如前端把token放在自定義請(qǐng)求頭里而后端使用了 Spring Security 時(shí)非白名單的請(qǐng)求會(huì)被攔截看起來(lái)像是參數(shù)沒(méi)傳到實(shí)際上是安全框架先拒絕了。排查時(shí)先把 Spring Security 的日志調(diào)成 DEBUG逐步定位請(qǐng)求在哪一步被拒絕。常見(jiàn)錯(cuò)誤是把自定義請(qǐng)求頭當(dāng)成普通參數(shù)處理導(dǎo)致過(guò)濾規(guī)則識(shí)別不到。養(yǎng)成先看日志、再看中間件的習(xí)慣能省大量時(shí)間。5. 我對(duì)傳參設(shè)計(jì)的一點(diǎn)個(gè)人經(jīng)驗(yàn)回頭再看 Spring 請(qǐng)求傳參這件事其實(shí)難的不是某個(gè)注解的用法而是貫穿全流程的“參數(shù)契約”。我在實(shí)際項(xiàng)目中總結(jié)出幾條建議分享給大家。第一個(gè)建議接口參數(shù)文檔先行。前后端聯(lián)調(diào)之前把每個(gè)接口的參數(shù)位置、類型、是否必填、默認(rèn)值列清楚。哪怕只是一個(gè)小接口也最好在 Swagger 注解里標(biāo)注完整。許多傳參問(wèn)題是溝通問(wèn)題不是代碼問(wèn)題。第二個(gè)建議拒絕超多參數(shù)的接口。如果一個(gè)像是十幾個(gè)字段再加上十幾個(gè)查詢條件建議拆散成 DTO。DTO 帶來(lái)的可維護(hù)性遠(yuǎn)勝于參數(shù)列表的“直觀性”。多個(gè)接口共用同一個(gè) DTO 時(shí)也要注意不要頻繁改動(dòng) DTO否則影響面很大。第三個(gè)建議保持參數(shù)命名風(fēng)格一致。后端字段統(tǒng)一駝峰前端傳參也統(tǒng)一駝峰不要一會(huì)userName一會(huì)username。如果團(tuán)隊(duì)已經(jīng)習(xí)慣了蛇形命名那就通過(guò)JsonProperty統(tǒng)一映射。不一致是 chaos 的源頭。第四個(gè)建議全局異常處理中兜住參數(shù)異常。至少處理MethodArgumentNotValidException、MissingServletRequestParameterException、MethodArgumentTypeMismatchException、HttpMessageNotReadableException這幾類統(tǒng)一返回結(jié)構(gòu)化的錯(cuò)誤信息。否則前端拿到 400 的默認(rèn)響應(yīng)一頭霧水聯(lián)調(diào)效率大打折扣。第五個(gè)建議調(diào)試時(shí)善用瀏覽器開(kāi)發(fā)者工具。Network 面板能看到真實(shí)發(fā)出的請(qǐng)求包括請(qǐng)求行、請(qǐng)求頭、請(qǐng)求體。很多前后端爭(zhēng)議打開(kāi) Network 一看便知。最后再分享一個(gè)小技巧在開(kāi)發(fā)環(huán)境給 Spring Boot 開(kāi)啟spring.mvc.log-request-detailstrue或配置一個(gè)打印請(qǐng)求參數(shù)的過(guò)濾器就能在日志里看到每個(gè)接口收到的完整參數(shù)。這個(gè)習(xí)慣幫我定位了無(wú)數(shù)“前端說(shuō)傳了、后端說(shuō)沒(méi)收到”的懸案。你要不要試著在下一個(gè)接口里加上這個(gè)日志過(guò)濾器我保證你排查參數(shù)問(wèn)題的效率會(huì)翻倍。