戰(zhàn)：MockRestServiceServer與WireMock方案解析)
1. 先別急著寫測試搞清楚 RestClient 到底是什么1.1 版本號這件事6.1 其實(shí)是 Spring Framework 的版本看到標(biāo)題里寫著“Spring Boot 6.1”估計(jì)不少人和我一開始一樣愣了一下因?yàn)?Spring Boot 的版本號目前主線是 3.x而 6.1 是 Spring Framework 的版本號Spring Boot 3.2 開始就是基于 Spring Framework 6.1 的。所以“Spring Boot 6.1”這個(gè)說法如果理解成“Spring Framework 6.1 Spring Boot 3.2”在技術(shù)上是完全成立的RestClient 正是 Spring Framework 6.1 新增的同步 HTTP 客戶端。這個(gè)細(xì)節(jié)不是摳字眼它直接影響你查文檔、搜資料、引依賴時(shí)的準(zhǔn)確性。我在工作中遇到過好幾個(gè)同事在 Maven 里找spring-boot-starter-restclient找了半天發(fā)現(xiàn)沒有這個(gè) starter因?yàn)?RestClient 不在單獨(dú)的 starter 里它跟著spring-web模塊走。Spring Boot 3.2 的spring-boot-starter-web、spring-boot-starter-webflux甚至spring-boot-starter-web-services里都有它但如果你用的是 WebFlux 的 starter又想要同步的 RestClient 行為那就得額外引spring-web的依賴這里面的細(xì)微差別踩坑的人不少。RestClient 的定位非常清晰它要替代的是 RestTemplate。RestTemplate 從 Spring 5.0 開始就被官方標(biāo)記為維護(hù)模式不會再加新功能了但團(tuán)隊(duì)里用它的老項(xiàng)目又特別多因?yàn)榇蠹伊?xí)慣了它那種同步、直接、寫起來不繞彎的風(fēng)格。WebClient 雖然功能強(qiáng)大、異步非阻塞但學(xué)習(xí)成本確實(shí)高對于只想要“發(fā)一個(gè) GET 請求拿個(gè) JSON 回來”這種場景WebClient 顯得有點(diǎn)殺雞用牛刀。RestClient 就是在這個(gè)背景下出現(xiàn)的保留 RestTemplate 那種直觀的同步編碼體驗(yàn)同時(shí)把 API 設(shè)計(jì)得更加鏈?zhǔn)?、流暢?UriBuilder、ExchangeFilterFunction、消息轉(zhuǎn)換器這些 WebClient 的優(yōu)點(diǎn)也吸收了過來。1.2 RestClient 與 RestTemplate、WebClient 怎么選很多朋友問我一個(gè)問題我現(xiàn)在要新寫一個(gè)服務(wù)間調(diào)用到底選哪個(gè)我給團(tuán)隊(duì)定的參考思路是這樣的維度RestTemplateWebClientRestClient編碼風(fēng)格命令式簡單直接響應(yīng)式鏈?zhǔn)交卣{(diào)/流式命令式 鏈?zhǔn)阶罱咏F(xiàn)代寫法異步支持不支持傳統(tǒng)同步阻塞完美支持非阻塞暫不支持異步純同步學(xué)習(xí)成本低中高低與 Spring 生態(tài)契合度低進(jìn)入維護(hù)模式高高官方主推適合場景老項(xiàng)目維護(hù)高并發(fā)、網(wǎng)關(guān)、流式調(diào)用絕大多數(shù)服務(wù)間同步調(diào)用這里多說一句異步的事。RestClient 本身是同步設(shè)計(jì)但 Spring 官方在 6.1 里同時(shí)提供了RestClient的響應(yīng)式兄弟RestClient的 WebClient 變體即用 RestClient 的鏈?zhǔn)秸Z法包著 WebClient 實(shí)現(xiàn)不過日常用不到咱不展開。我的判斷標(biāo)準(zhǔn)很樸素如果你的接口調(diào)用方本身不是高性能網(wǎng)關(guān)也沒有流式推送需求就用 RestClient它寫出來的代碼最好讀、最好維護(hù)。1.3 為什么單元測試這個(gè)主題值得單拎出來寫說實(shí)話我見過太多團(tuán)隊(duì)使用 RestTemplate 或 RestClient 時(shí)測試只有兩種狀態(tài)要么不寫要么寫一個(gè) mock 掉整個(gè) Service 層的“假單元測試”真正到了 HTTP 客戶端這一層就裸奔了。等哪天第三方接口聯(lián)調(diào)出問題線上日志打出來的錯(cuò)誤是ConnectTimeoutException還是ResourceAccessException好多人分不清楚更別提怎么在測試?yán)锬M出這兩種不同的超時(shí)場景。RestClient 引入的新 API 剛出來一年左右網(wǎng)上關(guān)于它的單元測試文章不少但質(zhì)量參差不齊有些直接照搬 WebClient 的測試方案有些用的還是舊版RestTemplate的過時(shí) API照著抄很容易掉坑里。這篇文章我會從方案選型、代碼實(shí)現(xiàn)、常見報(bào)錯(cuò)三個(gè)層面把 RestClient 單元測試這件事掰開揉碎講清楚項(xiàng)目代碼也是我自己在 Spring Boot 3.2.4 基礎(chǔ)上跑通的可以放心抄。2. 設(shè)計(jì)方案單測 RestClient 的 3 種主流思路2.1 思路一MockRestServiceServer 輕量模擬MockRestServiceServer是 Spring 官方專門為 RestTemplate 提供的測試工具在 Spring Framework 6.1 之后它同步支持對 RestClient 的 mock。這個(gè)方案的核心思路非常樸素你家的服務(wù)要去請求第三方接口測試?yán)镂也幌胝嫒フ埱竽俏揖徒o這個(gè)“網(wǎng)絡(luò)請求”套一個(gè)代理測試代碼里預(yù)先定義好“如果收到某個(gè) URL 的 GET 請求就返回指定的 JSON 字符串”。它最大的優(yōu)點(diǎn)是簡單、快速、沒有額外依賴也不需要起一個(gè)真實(shí)的 socket 端口。缺點(diǎn)也明顯它 mock 的是底層 request factory而不是真實(shí)網(wǎng)絡(luò)棧所以它測不到 DNS 解析、連接池、真實(shí)超時(shí)這些網(wǎng)絡(luò)層面的問題。但作為單元測試這完全夠用了因?yàn)槟惚緛砭筒幌朐趩螠y里真的發(fā)起外部調(diào)用。實(shí)現(xiàn)方式上用MockRestServiceServer.bindTo(RestClient.Builder)把測試服務(wù)綁定到 builder 上然后在測試中server.expect(...)寫期望的請求和返回。這里有一個(gè)從 RestTemplate 遷移過來的注意點(diǎn)RestTemplate 時(shí)代調(diào)用MockRestServiceServer.createServer(restTemplate)就夠了但 RestClient 因?yàn)椴扇×?builder 模式你需要把 server 綁定到 builder 再讓 builder 構(gòu)建出 RestClient否則測試?yán)?mock 不生效。2.2 思路二WireMock 模擬真實(shí) HTTP 服務(wù)如果你希望測試盡可能接近真實(shí) HTTP 調(diào)用比如要驗(yàn)證 header 里的認(rèn)證信息、要模擬第三方服務(wù)返回 500/超時(shí)等異常場景WireMock 是更好的選擇。它本質(zhì)上是在測試進(jìn)程里啟動一個(gè)真正的 HTTP 服務(wù)器然后你的 RestClient 像訪問真實(shí)服務(wù)一樣訪問這個(gè)本地端口。WireMock 的優(yōu)勢是“真”RestClient 從連接建立、發(fā)送請求、讀取響應(yīng)到解析 JSON 的完整鏈路都會執(zhí)行一遍如果底層配置有問題比如連接池設(shè)置、超時(shí)邏輯用 WireMock 能暴露出來。缺點(diǎn)是測試啟動稍慢、需要管理端口和生命周期如果項(xiàng)目里所有單測都用它CI 時(shí)長會明顯增加。這兩套方案怎么取舍我的經(jīng)驗(yàn)是純 Service 層的單測用 MockRestServiceServer涉及 HTTP 協(xié)議細(xì)節(jié)的集成測試用 WireMock。還有一種更“重”的方案是用 Testcontainers 起一個(gè)容器化的 MockServer但那種一般留給端到端測試單測階段引入容器反而增加了不穩(wěn)定性不建議一上來就這么豪橫。2.3 要不要拉起來 Spring 容器關(guān)于這個(gè)問題我見過兩種極端一種人寫單測動不動SpringBootTest把所有 Bean 全部加載測一個(gè)小 Client 要等 30 秒另一種人連容器都不碰純手動 new 對象但遇到 RestClient.Builder 注入、依賴別的配置類時(shí)又無從下手。我的建議是分場景如果只是測一個(gè)簡單的 Client 方法、驗(yàn)證 URL/header/body完全不需要啟動 Spring 容器手動RestClient.builder()構(gòu)建然后綁定 MockRestServiceServer 即可。但如果你配置了自定義的ClientHttpRequestInterceptor、Jackson消息轉(zhuǎn)換器或者依賴了配置文件的某些屬性那就用SpringBootTestAutoConfigureMockRestServiceServer讓 Spring 幫你把 builder 注入好測試只關(guān)注業(yè)務(wù)斷言這更符合“集成測試”的定位。2.4 先寫測試還是先寫功能代碼國內(nèi)團(tuán)隊(duì)對這個(gè)問題的態(tài)度兩極分化要么嚴(yán)格執(zhí)行 TDD要么完全跳過測試。我自己的體會是RestClient 這種外部調(diào)用代碼先寫測試的價(jià)值比普通 CRUD 代碼更大因?yàn)樗獙拥慕涌谑悄悴豢煽氐牡谌侥惚仨氃趯憳I(yè)務(wù)代碼前就確定好請求格式、響應(yīng)結(jié)構(gòu)、異常處理邏輯。你先寫一個(gè)“我想讓某個(gè)請求返回什么數(shù)據(jù)”的測試相當(dāng)于先把協(xié)議定下來再寫實(shí)現(xiàn)就不容易跑偏。我常用的節(jié)奏是先定義接口 DTO再寫一個(gè)空實(shí)現(xiàn)然后寫測試用例正常返回、404、500、超時(shí)四種情況最后補(bǔ)實(shí)現(xiàn)代碼讓測試變綠。這樣做的好處是你會在寫測試的過程中發(fā)現(xiàn)很多設(shè)計(jì)上的問題比如響應(yīng)的 JSON 有嵌套字段你沒考慮到、有些 header 是動態(tài)生成的、第三方接口分頁結(jié)構(gòu)和你預(yù)期不一致這些問題提前暴露比聯(lián)調(diào)時(shí)暴露成本低得多。3. 實(shí)操過程MockRestServiceServer 方案一步步落地3.1 準(zhǔn)備環(huán)境和依賴先交代一下工程環(huán)境JDK 17Spring Boot 3.x 的最低要求、Spring Boot 3.2.4、Spring Framework 6.1.5、Maven 3.9。JDK 8 的老項(xiàng)目想用 RestClient 就不用想了升 JDK 17 是硬前提。Maven 依賴不需要額外的測試庫直接用 spring-boot-starter-testdependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency注意如果項(xiàng)目里沒引spring-boot-starter-web只引了spring-boot-starter-webflux那么 RestClient 類在spring-web模塊中已經(jīng)有了但有些 HTTP 客戶端工廠比如 JDK HttpURLConnection 的默認(rèn)實(shí)現(xiàn)在 WebFlux 環(huán)境下的測試行為會有差異建議還是統(tǒng)一用 web starter省得排查半天。3.2 先寫一個(gè)待測的 Client 類假設(shè)我們正在做一個(gè)“上門烹飪預(yù)約服務(wù)”后端其中一個(gè)功能是調(diào)用外部菜單服務(wù)獲取廚師信息。這個(gè)場景取自真實(shí)業(yè)務(wù)很能體現(xiàn) RestClient 的使用方式。package com.example.cooking.client; import com.example.cooking.dto.ChefDto; import org.springframework.beans.factory.annotation.Qualifier; import org.springframework.core.ParameterizedTypeReference; import org.springframework.http.MediaType; import org.springframework.stereotype.Component; import org.springframework.web.client.RestClient; import java.util.List; Component public class ChefServiceClient { private final RestClient restClient; public ChefServiceClient(Qualifier(chefServiceRestClient) RestClient restClient) { this.restClient restClient; } public ChefDto getChefById(Long id) { return restClient.get() .uri(/api/chefs/{id}, id) .accept(MediaType.APPLICATION_JSON) .retrieve() .body(ChefDto.class); } public ListChefDto listChefsByCity(String city) { return restClient.get() .uri(uriBuilder - uriBuilder .path(/api/chefs) .queryParam(city, city) .build()) .accept(MediaType.APPLICATION_JSON) .retrieve() .body(new ParameterizedTypeReferenceListChefDto() {}); } }這里的Qualifier(chefServiceRestClient)是為了區(qū)分不同的 RestClient Bean當(dāng)系統(tǒng)里同時(shí)有多個(gè)服務(wù)需要調(diào)用時(shí)不要都在同一個(gè) RestClient 上疊 baseUrl給每個(gè)下游服務(wù)一個(gè)獨(dú)立配置的 Client 是更清晰的設(shè)計(jì)。3.3 配置 RestClient 的 Bean在Configuration類中定義 RestClient Bean并設(shè)置連接超時(shí)和讀取超時(shí)package com.example.cooking.config; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.http.client.JdkClientHttpRequestFactory; import org.springframework.web.client.RestClient; import java.net.http.HttpClient; import java.time.Duration; Configuration public class RestClientConfig { Bean(chefServiceRestClient) public RestClient chefServiceRestClient( Value(${chef.service.base-url}) String baseUrl) { HttpClient httpClient HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(3)) .build(); JdkClientHttpRequestFactory requestFactory new JdkClientHttpRequestFactory(httpClient); requestFactory.setReadTimeout(Duration.ofSeconds(5)); return RestClient.builder() .baseUrl(baseUrl) .requestFactory(requestFactory) .defaultHeader(X-Request-Source, cooking-platform) .build(); } }這里我選了 JDK 自帶的 HttpClient 作為底層實(shí)現(xiàn)如果你想用 Apache HttpClient 5.x需要額外引入依賴并配置連接池但單測場景沒有區(qū)別。注意JdkClientHttpRequestFactory在啟動時(shí)就會創(chuàng)建一個(gè)HttpClient如果項(xiàng)目中還有復(fù)雜的 HTTP/2 或連接池配置需求建議換成HttpComponentsClientHttpRequestFactory。3.4 核心寫 MockRestServiceServer 測試類終于寫到最關(guān)鍵的部分了。由于 RestClient 使用了 builder 模式MockRestServiceServer 綁定時(shí)有特殊要求我一開始直接套用了 RestTemplate 時(shí)代的寫法結(jié)果發(fā)現(xiàn) mock 根本攔截不到請求后來仔細(xì)看了官方文檔才明白問題出在哪。正確的完整測試代碼如下package com.example.cooking.client; import com.example.cooking.dto.ChefDto; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.springframework.http.MediaType; import org.springframework.test.web.client.MockRestServiceServer; import org.springframework.web.client.RestClient; import java.util.Arrays; import java.util.List; import static org.assertj.core.api.Assertions.assertThat; import static org.springframework.test.web.client.match.MockRestRequestMatchers.*; import static org.springframework.test.web.client.response.MockRestResponseCreators.*; class ChefServiceClientTest { private MockRestServiceServer mockServer; private ChefServiceClient client; BeforeEach void setUp() { RestClient.Builder builder RestClient.builder() .baseUrl(http://chef-service.internal); mockServer MockRestServiceServer.bindTo(builder).build(); client new ChefServiceClient(builder.build()); } Test void testGetChefById_whenThirdPartyReturnsData_shouldDeserializeOk() { // given String json { id: 1001, name: 張師傅, specialty: 川菜, rating: 4.8 } ; mockServer.expect(requestTo(/api/chefs/1001)) .andExpect(method(HttpMethod.GET)) .andExpect(header(X-Request-Source, cooking-platform)) .andRespond(withSuccess(json, MediaType.APPLICATION_JSON)); // when ChefDto result client.getChefById(1001L); // then assertThat(result.getId()).isEqualTo(1001L); assertThat(result.getName()).isEqualTo(張師傅); assertThat(result.getSpecialty()).isEqualTo(川菜); mockServer.verify(); } Test void testListChefsByCity_whenNoData_shouldReturnEmptyList() { // given mockServer.expect(requestToUriStartingWith(/api/chefs?city上海)) .andExpect(method(HttpMethod.GET)) .andRespond(withSuccess([], MediaType.APPLICATION_JSON)); // when ListChefDto result client.listChefsByCity(上海); // then assertThat(result).isEmpty(); mockServer.verify(); } }這個(gè)測試類有個(gè)很重要的細(xì)節(jié)MockRestServiceServer.bindTo(builder).build()會在底層包裝 builder之后任何通過這個(gè) builder 創(chuàng)建的 RestClient 請求都會被它攔截。verify()放在最后斷言所有聲明的期望請求都被匹配到一個(gè)都不能多一個(gè)也不能少。3.5 異常場景怎么測RestClient 默認(rèn)繼承了 RestTemplate 的異常處理方式4xx 拋出HttpClientErrorException5xx 拋出HttpServerErrorException連接失敗拋出ResourceAccessException。這些異常場景在測試中很容易模擬Test void testGetChefById_whenServerReturns500_shouldThrowHttpServerErrorException() { mockServer.expect(requestTo(/api/chefs/2000)) .andExpect(method(HttpMethod.GET)) .andRespond(withServerError()); assertThatThrownBy(() - client.getChefById(2000L)) .isInstanceOf(HttpServerErrorException.class) .hasMessageContaining(500); } Test void testGetChefById_whenThirdPartyTimeout_shouldThrowResourceAccessException() { // 通過 withException 模擬連接異常 mockServer.expect(requestTo(/api/chefs/3000)) .andExpect(method(HttpMethod.GET)) .andRespond(withException(new ConnectTimeoutException(connect timed out))); assertThatThrownBy(() - client.getChefById(3000L)) .isInstanceOf(ResourceAccessException.class) .hasMessageContaining(connect timed out); }這里我想強(qiáng)調(diào)一個(gè)容易混淆的概念讀超時(shí)Read Timeout和連接超時(shí)Connect Timeout是兩個(gè)不同的異常MockRestServiceServer 單測里能模擬的是“連接層”的異常因?yàn)檎埱蟾緵]發(fā)出去。如果你想驗(yàn)證讀超時(shí)的處理邏輯得用 WireMock 或 Testcontainers 起真實(shí)服務(wù)然后讓服務(wù)端故意睡眠超過讀超時(shí)時(shí)間這個(gè)在線上排查特別有用。3.6 配合 SpringBootTest 的寫法如果項(xiàng)目里配置比較多想直接把測試環(huán)境拉起來可以用下面的方式SpringBootTest AutoConfigureMockRestServiceServer class ChefServiceClientIntegrationTest { Autowired private ChefServiceClient client; Autowired private MockRestServiceServer mockServer; Test void testGetChefById_withSpringContext() { mockServer.expect(requestTo(/api/chefs/1001)) .andRespond(withSuccess({\id\:1001,\name\:\李師傅\}, MediaType.APPLICATION_JSON)); ChefDto result client.getChefById(1001L); assertThat(result.getName()).isEqualTo(李師傅); mockServer.verify(); } }用AutoConfigureMockRestServiceServer時(shí)Spring Boot 會自動替換容器里的 RestClient.Builder 為 mock 版你的測試類不需要有任何綁定邏輯。但這個(gè)方案要求被注入的 RestClient 確實(shí)是項(xiàng)目中配置的同一個(gè) builder 構(gòu)建的如果代碼里new RestClient那神仙也攔不住。4. WireMock 方案實(shí)戰(zhàn)連協(xié)議棧一起測4.1 什么時(shí)候必須用 WireMock年初我們團(tuán)隊(duì)對接了一個(gè)第三方“菜品識別服務(wù)”對方文檔沒寫好響應(yīng)里有時(shí)候返回 JSON有時(shí)候返回純文本還有時(shí)候返回的 JSON 字段名大小寫不一致。MockRestServiceServer 這種“模擬”方式在這種場景下就使不上勁了因?yàn)椴还苷鎸?shí)服務(wù)返回什么MockRestServiceServer 給你的 response 都是你定義的字符串它測不到 RestClient 和消息轉(zhuǎn)換器之間的協(xié)商過程。這時(shí)候把請求打到真實(shí)服務(wù)上、然后讓真實(shí)服務(wù)“聽你指揮”才是檢驗(yàn)正確性的唯一標(biāo)準(zhǔn)。WireMock 干的就是這個(gè)事。4.2 引入 WireMock 并編寫測試Maven 添加依賴dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency dependency groupIdcom.github.tomakehurst/groupId artifactIdwiremock-standalone/artifactId version3.3.1/version scopetest/scope /dependency測試代碼package com.example.cooking.client; import com.example.cooking.dto.ChefDto; import com.github.tomakehurst.wiremock.WireMockServer; import com.github.tomakehurst.wiremock.client.WireMock; import org.junit.jupiter.api.AfterEach; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.springframework.http.MediaType; import org.springframework.web.client.RestClient; import static com.github.tomakehurst.wiremock.client.WireMock.*; import static org.assertj.core.api.Assertions.assertThat; class ChefServiceClientWireMockTest { private WireMockServer wireMockServer; private ChefServiceClient client; BeforeEach void setUp() { wireMockServer new WireMockServer(8089); wireMockServer.start(); WireMock.configureFor(localhost, 8089); RestClient restClient RestClient.builder() .baseUrl(http://localhost:8089) .build(); client new ChefServiceClient(restClient); } AfterEach void tearDown() { wireMockServer.stop(); } Test void testGetChefById_withWireMock() { stubFor(get(urlEqualTo(/api/chefs/1001)) .willReturn(aResponse() .withStatus(200) .withHeader(Content-Type, application/json) .withBody({\id\:1001,\name\:\王師傅\,\specialty\:\粵菜\,\rating\:4.9}))); ChefDto result client.getChefById(1001L); assertThat(result.getName()).isEqualTo(王師傅); verify(getRequestedFor(urlEqualTo(/api/chefs/1001))); } }WireMock 跑起來之后RestClient 發(fā)請求就像打真實(shí)服務(wù)一樣DNS、端口、連接、HTTP 協(xié)議全過程都會走一遍這能暴露一些 MockRestServiceServer 永遠(yuǎn)發(fā)現(xiàn)不了的問題。比如我們團(tuán)隊(duì)之前就遇到過ChefDto里有個(gè)LocalDateTime字段普通 JSON 序列化沒問題但第三方服務(wù)返回的是yyyy-MM-dd HH:mm:ss這種非 ISO 格式在 MockRestServiceServer 里因?yàn)?response 直接走消息轉(zhuǎn)換器解析根本沒報(bào)警WireMock 下同樣的 JSON 結(jié)果解析報(bào)錯(cuò)才暴露出問題最后加了JsonFormat注解才解決。4.3 在單元測試?yán)锬M延遲和超時(shí)剛才提到的讀超時(shí)場景WireMock 很容易模擬Test void testReadTimeout() { stubFor(get(urlEqualTo(/api/chefs/slow)) .willReturn(aResponse() .withFixedDelay(6000) // 人為延遲 6 秒 .withBody({}))); RestClient timeoutClient RestClient.builder() .baseUrl(http://localhost:8089) .requestFactory(new JdkClientHttpRequestFactory( HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(3)) .build())) .build(); // 需要單獨(dú)設(shè)置讀超時(shí) JdkClientHttpRequestFactory factory (JdkClientHttpRequestFactory) timeoutClient.getRequestFactory(); factory.setReadTimeout(Duration.ofSeconds(2)); assertThatThrownBy(() - timeoutClient.get() .uri(/api/chefs/slow) .retrieve() .toBodilessEntity()) .isInstanceOf(ResourceAccessException.class) .hasMessageContaining(Read timed out); }有一點(diǎn)要提醒JdkClientHttpRequestFactory的讀超時(shí)必須在構(gòu)建RestClient之后單獨(dú)設(shè)置如果一開始就在HttpClient構(gòu)建時(shí)設(shè)置connectTimeout那只影響連接階段不影響讀取階段。這個(gè)坑我遇到過不止一次線上排查超時(shí)問題時(shí)要分清楚是連接超時(shí)還是讀超時(shí)。5. 常見問題與排查技巧實(shí)錄5.1 報(bào)了Unexpected request是什么原因怎么定位這是 MockRestServiceServer 最經(jīng)典的報(bào)錯(cuò)意思是有請求發(fā)出來了但你測試?yán)餂]有對這次請求做過期望聲明或者期望聲明的 URL/method 對不上。最常見的原因是 RestClient 實(shí)際請求的 URL 和你預(yù)期的不一致。排查技巧把異常堆棧完整拉出來里面會帶著實(shí)際請求的 method 和 URI對照你測試?yán)飁xpect的 matcher 逐項(xiàng)核對。另外特別提醒 URL 里的 query 參數(shù)requestTo(/api/chefs?city上海)這種寫法對中文參數(shù)和你預(yù)期不一致時(shí)很容易誤判建議用queryParam逐項(xiàng)匹配而不是拼字符串。5.2 RestClient 類找不到或者版本不兼容RestClient是 Spring 6.1 引入的類如果你用的 Spring Boot 3.1 或更早即使引了spring-web類也是不存在的。這時(shí)候 IDE 會報(bào)ClassNotFoundException或編譯錯(cuò)誤別糾結(jié)直接升 Spring Boot 到 3.2。還有一個(gè)很少人注意的點(diǎn)如果項(xiàng)目里手動指定了 Spring Framework 版本開發(fā)環(huán)境 Spring Boot 用的 6.1.x但內(nèi)部某個(gè)模塊鎖定了 6.0.x那也會出現(xiàn)類找不到Maven 依賴樹里查一下spring-web的版本即可。5.3 MockRestServiceServer mock 沒生效請求打到了真實(shí)服務(wù)發(fā)生這種情況九成是 RestClient 實(shí)例不是你綁定后那個(gè) builder 創(chuàng)建的。仔細(xì)檢查一下MockRestServiceServer.bindTo(builder).build()之后你的被測類是否用的是這個(gè) builder.build()出來的 RestClient如果被測類自己內(nèi)部RestClient.create()或者 new 了一個(gè)那 mock 自然攔不到。另外檢查是否多個(gè)RestClientBean 有同名的質(zhì)量問題Qualifier指定錯(cuò)了也會導(dǎo)致注入的不是同一個(gè)實(shí)例。5.4 JSON 反序列化報(bào)錯(cuò)但接口文檔明明沒錯(cuò)使用 RestClient 時(shí)./body()的解析依賴消息轉(zhuǎn)換器自動協(xié)商 content-type。如果第三方返回的Content-Type是application/json;charsetUTF-8沒問題但如果第三方服務(wù)不規(guī)范返回了text/plain或者根本沒有 Content-TypeRestClient 會認(rèn)為響應(yīng)不是 JSON走默認(rèn)的消息轉(zhuǎn)換器結(jié)果自然是反序列化失敗或者拿到一個(gè) String。解決辦法在 Client 的請求代碼里顯式指定.accept(MediaType.APPLICATION_JSON)并且與第三方約定響應(yīng)頭必須帶application/json。這個(gè)看著是小事但排查起來最容易讓人懷疑人生我見過有人在這個(gè)問題上卡了兩天。5.5 測試用例之間互相影響如果你在同一個(gè)測試類里寫了多個(gè)測試方法且都用BeforeEach綁定 MockRestServiceServer那么每個(gè)測試方法運(yùn)行前都會新建一個(gè) server 實(shí)例用例之間互不干擾。但如果用了SpringBootTest且測試類標(biāo)注Transactional事務(wù)會貫穿整個(gè)測試此時(shí)第三方服務(wù)調(diào)用不會被事務(wù)回滾影響別指望 mock 會在事務(wù)結(jié)束后自動恢復(fù)需要在BeforeEach里手動重置 server。用 WireMock 時(shí)多個(gè)測試類并行跑可能發(fā)生端口沖突建議每個(gè)測試類指定一個(gè)獨(dú)立端口不要全部用8089這種固定值CI 上爆端口沖突是常事。5.6 “SQL執(zhí)行10秒自動關(guān)閉”這類配置會不會影響 RestClient 測試很多人會把 RestClient 和數(shù)據(jù)庫連接池的超時(shí)概念搞混這里順手捋一下。Spring Boot 中關(guān)于“SQL 執(zhí)行 10 秒自動關(guān)閉”這類說法一般是指連接池的連接回收時(shí)長時(shí)間不歸還或事務(wù)超時(shí)它影響的范圍是數(shù)據(jù)庫連接和 HTTP 客戶端的超時(shí)完全是兩條線。RestClient 的超時(shí)配置在ClientHttpRequestFactory層與 JDBC 無關(guān)。所以你在測試 RestClient 時(shí)不需要也沒必要依賴 Spring 的spring.datasource.*超時(shí)配置連接超時(shí)和讀超時(shí)都在 RestClient 自己的 RequestFactory 里設(shè)置。測試時(shí)為了不等待過久通常把 connectTimeout 設(shè) 1~3 秒、readTimeout 設(shè) 2~5 秒即可線上再根據(jù)接口實(shí)際響應(yīng)時(shí)間放寬。5.7 測試時(shí)遇到JdkClientHttpRequestFactory和 HttpURLConnection 混用Spring Boot 3.2 默認(rèn)的ClientHttpRequestFactory是JdkClientHttpRequestFactory但在某些 Spring Boot 小版本上如果 classpath 里有 Apache HttpClient 或 Jetty 的客戶端自動配置可能選擇其他工廠。這會導(dǎo)致你在本地跑測試時(shí)沒問題一到 CI 就發(fā)現(xiàn) RestClient 行為不一致比如代理設(shè)置、連接池參數(shù)全變了。建議在配置類里顯式指定requestFactory不要依賴容器自動選擇這樣測試和生產(chǎn)環(huán)境行為才一致。如果你像我一樣習(xí)慣在RestClientConfig里手動構(gòu)建就把JdkClientHttpRequestFactory或你選擇的工廠實(shí)現(xiàn)固定寫死。6. 實(shí)操心得我踩過幾次坑之后的幾點(diǎn)體會寫這篇文章之前我把團(tuán)隊(duì)里所有用到 RestClient 的模塊翻了一遍發(fā)現(xiàn)很多測試代碼還在用 RestTemplate 時(shí)代的MockRestServiceServer.createServer()老寫法這讓我挺感慨的?？蚣芨?lián)Q代速度很快但很多人的測試知識還停留在上一代 API 上。我覺得 RestClient 的單元測試核心要把握住三點(diǎn)方案選型看需求——純單元測試用 MockRestServiceServer需要驗(yàn)證 HTTP 細(xì)節(jié)用 WireMock響應(yīng)類型要匹配——單個(gè)對象用ChefDto.class集合用ParameterizedTypeReference不要混用異常要全覆蓋——正常返回、4xx、5xx、連接異常、讀超時(shí)這五類場景都該有測試第三方接口才敢放心調(diào)。最后再分享一個(gè)小技巧MockRestServiceServer的expect支持一次聲明多個(gè)請求的期望如果被測代碼里循環(huán)調(diào)用了多次接口可以用expect(requestTo(...)).andExpect(...).andRespond(...)連續(xù)寫多個(gè)最后統(tǒng)一verify()。但如果你對一個(gè) URL 期望了兩次且兩次返回的內(nèi)容不一樣建議用andRespond的不同響應(yīng)或MockRestResponseCreators的withSuccess參數(shù)變體分別處理不要讓測試變成“最后一次賦值生效”那樣排錯(cuò)會非常痛苦。對于剛接觸 RestClient 的讀者我建議先把 3.4 節(jié)的基礎(chǔ)測試跑通再把 3.5 的異常場景補(bǔ)上最后再去研究 WireMock。測試是寫給未來的自己看的一個(gè)能快速定位問題的測試類比什么架構(gòu)理念都實(shí)在。 Spring Boot RestClient單元測試實(shí)戰(zhàn)：MockRestServiceServer與WireMock方案解析
1. 先別急著寫測試搞清楚 RestClient 到底是什么1.1 版本號這件事6.1 其實(shí)是 Spring Framework 的版本看到標(biāo)題里寫著“Spring Boot 6.1”估計(jì)不少人和我一開始一樣愣了一下因?yàn)?Spring Boot 的版本號目前主線是 3.x而 6.1 是 Spring Framework 的版本號Spring Boot 3.2 開始就是基于 Spring Framework 6.1 的。所以“Spring Boot 6.1”這個(gè)說法如果理解成“Spring Framework 6.1 Spring Boot 3.2”在技術(shù)上是完全成立的RestClient 正是 Spring Framework 6.1 新增的同步 HTTP 客戶端。這個(gè)細(xì)節(jié)不是摳字眼它直接影響你查文檔、搜資料、引依賴時(shí)的準(zhǔn)確性。我在工作中遇到過好幾個(gè)同事在 Maven 里找spring-boot-starter-restclient找了半天發(fā)現(xiàn)沒有這個(gè) starter因?yàn)?RestClient 不在單獨(dú)的 starter 里它跟著spring-web模塊走。Spring Boot 3.2 的spring-boot-starter-web、spring-boot-starter-webflux甚至spring-boot-starter-web-services里都有它但如果你用的是 WebFlux 的 starter又想要同步的 RestClient 行為那就得額外引spring-web的依賴這里面的細(xì)微差別踩坑的人不少。RestClient 的定位非常清晰它要替代的是 RestTemplate。RestTemplate 從 Spring 5.0 開始就被官方標(biāo)記為維護(hù)模式不會再加新功能了但團(tuán)隊(duì)里用它的老項(xiàng)目又特別多因?yàn)榇蠹伊?xí)慣了它那種同步、直接、寫起來不繞彎的風(fēng)格。WebClient 雖然功能強(qiáng)大、異步非阻塞但學(xué)習(xí)成本確實(shí)高對于只想要“發(fā)一個(gè) GET 請求拿個(gè) JSON 回來”這種場景WebClient 顯得有點(diǎn)殺雞用牛刀。RestClient 就是在這個(gè)背景下出現(xiàn)的保留 RestTemplate 那種直觀的同步編碼體驗(yàn)同時(shí)把 API 設(shè)計(jì)得更加鏈?zhǔn)?、流暢?UriBuilder、ExchangeFilterFunction、消息轉(zhuǎn)換器這些 WebClient 的優(yōu)點(diǎn)也吸收了過來。1.2 RestClient 與 RestTemplate、WebClient 怎么選很多朋友問我一個(gè)問題我現(xiàn)在要新寫一個(gè)服務(wù)間調(diào)用到底選哪個(gè)我給團(tuán)隊(duì)定的參考思路是這樣的維度RestTemplateWebClientRestClient編碼風(fēng)格命令式簡單直接響應(yīng)式鏈?zhǔn)交卣{(diào)/流式命令式 鏈?zhǔn)阶罱咏F(xiàn)代寫法異步支持不支持傳統(tǒng)同步阻塞完美支持非阻塞暫不支持異步純同步學(xué)習(xí)成本低中高低與 Spring 生態(tài)契合度低進(jìn)入維護(hù)模式高高官方主推適合場景老項(xiàng)目維護(hù)高并發(fā)、網(wǎng)關(guān)、流式調(diào)用絕大多數(shù)服務(wù)間同步調(diào)用這里多說一句異步的事。RestClient 本身是同步設(shè)計(jì)但 Spring 官方在 6.1 里同時(shí)提供了RestClient的響應(yīng)式兄弟RestClient的 WebClient 變體即用 RestClient 的鏈?zhǔn)秸Z法包著 WebClient 實(shí)現(xiàn)不過日常用不到咱不展開。我的判斷標(biāo)準(zhǔn)很樸素如果你的接口調(diào)用方本身不是高性能網(wǎng)關(guān)也沒有流式推送需求就用 RestClient它寫出來的代碼最好讀、最好維護(hù)。1.3 為什么單元測試這個(gè)主題值得單拎出來寫說實(shí)話我見過太多團(tuán)隊(duì)使用 RestTemplate 或 RestClient 時(shí)測試只有兩種狀態(tài)要么不寫要么寫一個(gè) mock 掉整個(gè) Service 層的“假單元測試”真正到了 HTTP 客戶端這一層就裸奔了。等哪天第三方接口聯(lián)調(diào)出問題線上日志打出來的錯(cuò)誤是ConnectTimeoutException還是ResourceAccessException好多人分不清楚更別提怎么在測試?yán)锬M出這兩種不同的超時(shí)場景。RestClient 引入的新 API 剛出來一年左右網(wǎng)上關(guān)于它的單元測試文章不少但質(zhì)量參差不齊有些直接照搬 WebClient 的測試方案有些用的還是舊版RestTemplate的過時(shí) API照著抄很容易掉坑里。這篇文章我會從方案選型、代碼實(shí)現(xiàn)、常見報(bào)錯(cuò)三個(gè)層面把 RestClient 單元測試這件事掰開揉碎講清楚項(xiàng)目代碼也是我自己在 Spring Boot 3.2.4 基礎(chǔ)上跑通的可以放心抄。2. 設(shè)計(jì)方案單測 RestClient 的 3 種主流思路2.1 思路一MockRestServiceServer 輕量模擬MockRestServiceServer是 Spring 官方專門為 RestTemplate 提供的測試工具在 Spring Framework 6.1 之后它同步支持對 RestClient 的 mock。這個(gè)方案的核心思路非常樸素你家的服務(wù)要去請求第三方接口測試?yán)镂也幌胝嫒フ埱竽俏揖徒o這個(gè)“網(wǎng)絡(luò)請求”套一個(gè)代理測試代碼里預(yù)先定義好“如果收到某個(gè) URL 的 GET 請求就返回指定的 JSON 字符串”。它最大的優(yōu)點(diǎn)是簡單、快速、沒有額外依賴也不需要起一個(gè)真實(shí)的 socket 端口。缺點(diǎn)也明顯它 mock 的是底層 request factory而不是真實(shí)網(wǎng)絡(luò)棧所以它測不到 DNS 解析、連接池、真實(shí)超時(shí)這些網(wǎng)絡(luò)層面的問題。但作為單元測試這完全夠用了因?yàn)槟惚緛砭筒幌朐趩螠y里真的發(fā)起外部調(diào)用。實(shí)現(xiàn)方式上用MockRestServiceServer.bindTo(RestClient.Builder)把測試服務(wù)綁定到 builder 上然后在測試中server.expect(...)寫期望的請求和返回。這里有一個(gè)從 RestTemplate 遷移過來的注意點(diǎn)RestTemplate 時(shí)代調(diào)用MockRestServiceServer.createServer(restTemplate)就夠了但 RestClient 因?yàn)椴扇×?builder 模式你需要把 server 綁定到 builder 再讓 builder 構(gòu)建出 RestClient否則測試?yán)?mock 不生效。2.2 思路二WireMock 模擬真實(shí) HTTP 服務(wù)如果你希望測試盡可能接近真實(shí) HTTP 調(diào)用比如要驗(yàn)證 header 里的認(rèn)證信息、要模擬第三方服務(wù)返回 500/超時(shí)等異常場景WireMock 是更好的選擇。它本質(zhì)上是在測試進(jìn)程里啟動一個(gè)真正的 HTTP 服務(wù)器然后你的 RestClient 像訪問真實(shí)服務(wù)一樣訪問這個(gè)本地端口。WireMock 的優(yōu)勢是“真”RestClient 從連接建立、發(fā)送請求、讀取響應(yīng)到解析 JSON 的完整鏈路都會執(zhí)行一遍如果底層配置有問題比如連接池設(shè)置、超時(shí)邏輯用 WireMock 能暴露出來。缺點(diǎn)是測試啟動稍慢、需要管理端口和生命周期如果項(xiàng)目里所有單測都用它CI 時(shí)長會明顯增加。這兩套方案怎么取舍我的經(jīng)驗(yàn)是純 Service 層的單測用 MockRestServiceServer涉及 HTTP 協(xié)議細(xì)節(jié)的集成測試用 WireMock。還有一種更“重”的方案是用 Testcontainers 起一個(gè)容器化的 MockServer但那種一般留給端到端測試單測階段引入容器反而增加了不穩(wěn)定性不建議一上來就這么豪橫。2.3 要不要拉起來 Spring 容器關(guān)于這個(gè)問題我見過兩種極端一種人寫單測動不動SpringBootTest把所有 Bean 全部加載測一個(gè)小 Client 要等 30 秒另一種人連容器都不碰純手動 new 對象但遇到 RestClient.Builder 注入、依賴別的配置類時(shí)又無從下手。我的建議是分場景如果只是測一個(gè)簡單的 Client 方法、驗(yàn)證 URL/header/body完全不需要啟動 Spring 容器手動RestClient.builder()構(gòu)建然后綁定 MockRestServiceServer 即可。但如果你配置了自定義的ClientHttpRequestInterceptor、Jackson消息轉(zhuǎn)換器或者依賴了配置文件的某些屬性那就用SpringBootTestAutoConfigureMockRestServiceServer讓 Spring 幫你把 builder 注入好測試只關(guān)注業(yè)務(wù)斷言這更符合“集成測試”的定位。2.4 先寫測試還是先寫功能代碼國內(nèi)團(tuán)隊(duì)對這個(gè)問題的態(tài)度兩極分化要么嚴(yán)格執(zhí)行 TDD要么完全跳過測試。我自己的體會是RestClient 這種外部調(diào)用代碼先寫測試的價(jià)值比普通 CRUD 代碼更大因?yàn)樗獙拥慕涌谑悄悴豢煽氐牡谌侥惚仨氃趯憳I(yè)務(wù)代碼前就確定好請求格式、響應(yīng)結(jié)構(gòu)、異常處理邏輯。你先寫一個(gè)“我想讓某個(gè)請求返回什么數(shù)據(jù)”的測試相當(dāng)于先把協(xié)議定下來再寫實(shí)現(xiàn)就不容易跑偏。我常用的節(jié)奏是先定義接口 DTO再寫一個(gè)空實(shí)現(xiàn)然后寫測試用例正常返回、404、500、超時(shí)四種情況最后補(bǔ)實(shí)現(xiàn)代碼讓測試變綠。這樣做的好處是你會在寫測試的過程中發(fā)現(xiàn)很多設(shè)計(jì)上的問題比如響應(yīng)的 JSON 有嵌套字段你沒考慮到、有些 header 是動態(tài)生成的、第三方接口分頁結(jié)構(gòu)和你預(yù)期不一致這些問題提前暴露比聯(lián)調(diào)時(shí)暴露成本低得多。3. 實(shí)操過程MockRestServiceServer 方案一步步落地3.1 準(zhǔn)備環(huán)境和依賴先交代一下工程環(huán)境JDK 17Spring Boot 3.x 的最低要求、Spring Boot 3.2.4、Spring Framework 6.1.5、Maven 3.9。JDK 8 的老項(xiàng)目想用 RestClient 就不用想了升 JDK 17 是硬前提。Maven 依賴不需要額外的測試庫直接用 spring-boot-starter-testdependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency注意如果項(xiàng)目里沒引spring-boot-starter-web只引了spring-boot-starter-webflux那么 RestClient 類在spring-web模塊中已經(jīng)有了但有些 HTTP 客戶端工廠比如 JDK HttpURLConnection 的默認(rèn)實(shí)現(xiàn)在 WebFlux 環(huán)境下的測試行為會有差異建議還是統(tǒng)一用 web starter省得排查半天。3.2 先寫一個(gè)待測的 Client 類假設(shè)我們正在做一個(gè)“上門烹飪預(yù)約服務(wù)”后端其中一個(gè)功能是調(diào)用外部菜單服務(wù)獲取廚師信息。這個(gè)場景取自真實(shí)業(yè)務(wù)很能體現(xiàn) RestClient 的使用方式。package com.example.cooking.client; import com.example.cooking.dto.ChefDto; import org.springframework.beans.factory.annotation.Qualifier; import org.springframework.core.ParameterizedTypeReference; import org.springframework.http.MediaType; import org.springframework.stereotype.Component; import org.springframework.web.client.RestClient; import java.util.List; Component public class ChefServiceClient { private final RestClient restClient; public ChefServiceClient(Qualifier(chefServiceRestClient) RestClient restClient) { this.restClient restClient; } public ChefDto getChefById(Long id) { return restClient.get() .uri(/api/chefs/{id}, id) .accept(MediaType.APPLICATION_JSON) .retrieve() .body(ChefDto.class); } public ListChefDto listChefsByCity(String city) { return restClient.get() .uri(uriBuilder - uriBuilder .path(/api/chefs) .queryParam(city, city) .build()) .accept(MediaType.APPLICATION_JSON) .retrieve() .body(new ParameterizedTypeReferenceListChefDto() {}); } }這里的Qualifier(chefServiceRestClient)是為了區(qū)分不同的 RestClient Bean當(dāng)系統(tǒng)里同時(shí)有多個(gè)服務(wù)需要調(diào)用時(shí)不要都在同一個(gè) RestClient 上疊 baseUrl給每個(gè)下游服務(wù)一個(gè)獨(dú)立配置的 Client 是更清晰的設(shè)計(jì)。3.3 配置 RestClient 的 Bean在Configuration類中定義 RestClient Bean并設(shè)置連接超時(shí)和讀取超時(shí)package com.example.cooking.config; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.http.client.JdkClientHttpRequestFactory; import org.springframework.web.client.RestClient; import java.net.http.HttpClient; import java.time.Duration; Configuration public class RestClientConfig { Bean(chefServiceRestClient) public RestClient chefServiceRestClient( Value(${chef.service.base-url}) String baseUrl) { HttpClient httpClient HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(3)) .build(); JdkClientHttpRequestFactory requestFactory new JdkClientHttpRequestFactory(httpClient); requestFactory.setReadTimeout(Duration.ofSeconds(5)); return RestClient.builder() .baseUrl(baseUrl) .requestFactory(requestFactory) .defaultHeader(X-Request-Source, cooking-platform) .build(); } }這里我選了 JDK 自帶的 HttpClient 作為底層實(shí)現(xiàn)如果你想用 Apache HttpClient 5.x需要額外引入依賴并配置連接池但單測場景沒有區(qū)別。注意JdkClientHttpRequestFactory在啟動時(shí)就會創(chuàng)建一個(gè)HttpClient如果項(xiàng)目中還有復(fù)雜的 HTTP/2 或連接池配置需求建議換成HttpComponentsClientHttpRequestFactory。3.4 核心寫 MockRestServiceServer 測試類終于寫到最關(guān)鍵的部分了。由于 RestClient 使用了 builder 模式MockRestServiceServer 綁定時(shí)有特殊要求我一開始直接套用了 RestTemplate 時(shí)代的寫法結(jié)果發(fā)現(xiàn) mock 根本攔截不到請求后來仔細(xì)看了官方文檔才明白問題出在哪。正確的完整測試代碼如下package com.example.cooking.client; import com.example.cooking.dto.ChefDto; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.springframework.http.MediaType; import org.springframework.test.web.client.MockRestServiceServer; import org.springframework.web.client.RestClient; import java.util.Arrays; import java.util.List; import static org.assertj.core.api.Assertions.assertThat; import static org.springframework.test.web.client.match.MockRestRequestMatchers.*; import static org.springframework.test.web.client.response.MockRestResponseCreators.*; class ChefServiceClientTest { private MockRestServiceServer mockServer; private ChefServiceClient client; BeforeEach void setUp() { RestClient.Builder builder RestClient.builder() .baseUrl(http://chef-service.internal); mockServer MockRestServiceServer.bindTo(builder).build(); client new ChefServiceClient(builder.build()); } Test void testGetChefById_whenThirdPartyReturnsData_shouldDeserializeOk() { // given String json { id: 1001, name: 張師傅, specialty: 川菜, rating: 4.8 } ; mockServer.expect(requestTo(/api/chefs/1001)) .andExpect(method(HttpMethod.GET)) .andExpect(header(X-Request-Source, cooking-platform)) .andRespond(withSuccess(json, MediaType.APPLICATION_JSON)); // when ChefDto result client.getChefById(1001L); // then assertThat(result.getId()).isEqualTo(1001L); assertThat(result.getName()).isEqualTo(張師傅); assertThat(result.getSpecialty()).isEqualTo(川菜); mockServer.verify(); } Test void testListChefsByCity_whenNoData_shouldReturnEmptyList() { // given mockServer.expect(requestToUriStartingWith(/api/chefs?city上海)) .andExpect(method(HttpMethod.GET)) .andRespond(withSuccess([], MediaType.APPLICATION_JSON)); // when ListChefDto result client.listChefsByCity(上海); // then assertThat(result).isEmpty(); mockServer.verify(); } }這個(gè)測試類有個(gè)很重要的細(xì)節(jié)MockRestServiceServer.bindTo(builder).build()會在底層包裝 builder之后任何通過這個(gè) builder 創(chuàng)建的 RestClient 請求都會被它攔截。verify()放在最后斷言所有聲明的期望請求都被匹配到一個(gè)都不能多一個(gè)也不能少。3.5 異常場景怎么測RestClient 默認(rèn)繼承了 RestTemplate 的異常處理方式4xx 拋出HttpClientErrorException5xx 拋出HttpServerErrorException連接失敗拋出ResourceAccessException。這些異常場景在測試中很容易模擬Test void testGetChefById_whenServerReturns500_shouldThrowHttpServerErrorException() { mockServer.expect(requestTo(/api/chefs/2000)) .andExpect(method(HttpMethod.GET)) .andRespond(withServerError()); assertThatThrownBy(() - client.getChefById(2000L)) .isInstanceOf(HttpServerErrorException.class) .hasMessageContaining(500); } Test void testGetChefById_whenThirdPartyTimeout_shouldThrowResourceAccessException() { // 通過 withException 模擬連接異常 mockServer.expect(requestTo(/api/chefs/3000)) .andExpect(method(HttpMethod.GET)) .andRespond(withException(new ConnectTimeoutException(connect timed out))); assertThatThrownBy(() - client.getChefById(3000L)) .isInstanceOf(ResourceAccessException.class) .hasMessageContaining(connect timed out); }這里我想強(qiáng)調(diào)一個(gè)容易混淆的概念讀超時(shí)Read Timeout和連接超時(shí)Connect Timeout是兩個(gè)不同的異常MockRestServiceServer 單測里能模擬的是“連接層”的異常因?yàn)檎埱蟾緵]發(fā)出去。如果你想驗(yàn)證讀超時(shí)的處理邏輯得用 WireMock 或 Testcontainers 起真實(shí)服務(wù)然后讓服務(wù)端故意睡眠超過讀超時(shí)時(shí)間這個(gè)在線上排查特別有用。3.6 配合 SpringBootTest 的寫法如果項(xiàng)目里配置比較多想直接把測試環(huán)境拉起來可以用下面的方式SpringBootTest AutoConfigureMockRestServiceServer class ChefServiceClientIntegrationTest { Autowired private ChefServiceClient client; Autowired private MockRestServiceServer mockServer; Test void testGetChefById_withSpringContext() { mockServer.expect(requestTo(/api/chefs/1001)) .andRespond(withSuccess({\id\:1001,\name\:\李師傅\}, MediaType.APPLICATION_JSON)); ChefDto result client.getChefById(1001L); assertThat(result.getName()).isEqualTo(李師傅); mockServer.verify(); } }用AutoConfigureMockRestServiceServer時(shí)Spring Boot 會自動替換容器里的 RestClient.Builder 為 mock 版你的測試類不需要有任何綁定邏輯。但這個(gè)方案要求被注入的 RestClient 確實(shí)是項(xiàng)目中配置的同一個(gè) builder 構(gòu)建的如果代碼里new RestClient那神仙也攔不住。4. WireMock 方案實(shí)戰(zhàn)連協(xié)議棧一起測4.1 什么時(shí)候必須用 WireMock年初我們團(tuán)隊(duì)對接了一個(gè)第三方“菜品識別服務(wù)”對方文檔沒寫好響應(yīng)里有時(shí)候返回 JSON有時(shí)候返回純文本還有時(shí)候返回的 JSON 字段名大小寫不一致。MockRestServiceServer 這種“模擬”方式在這種場景下就使不上勁了因?yàn)椴还苷鎸?shí)服務(wù)返回什么MockRestServiceServer 給你的 response 都是你定義的字符串它測不到 RestClient 和消息轉(zhuǎn)換器之間的協(xié)商過程。這時(shí)候把請求打到真實(shí)服務(wù)上、然后讓真實(shí)服務(wù)“聽你指揮”才是檢驗(yàn)正確性的唯一標(biāo)準(zhǔn)。WireMock 干的就是這個(gè)事。4.2 引入 WireMock 并編寫測試Maven 添加依賴dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency dependency groupIdcom.github.tomakehurst/groupId artifactIdwiremock-standalone/artifactId version3.3.1/version scopetest/scope /dependency測試代碼package com.example.cooking.client; import com.example.cooking.dto.ChefDto; import com.github.tomakehurst.wiremock.WireMockServer; import com.github.tomakehurst.wiremock.client.WireMock; import org.junit.jupiter.api.AfterEach; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.springframework.http.MediaType; import org.springframework.web.client.RestClient; import static com.github.tomakehurst.wiremock.client.WireMock.*; import static org.assertj.core.api.Assertions.assertThat; class ChefServiceClientWireMockTest { private WireMockServer wireMockServer; private ChefServiceClient client; BeforeEach void setUp() { wireMockServer new WireMockServer(8089); wireMockServer.start(); WireMock.configureFor(localhost, 8089); RestClient restClient RestClient.builder() .baseUrl(http://localhost:8089) .build(); client new ChefServiceClient(restClient); } AfterEach void tearDown() { wireMockServer.stop(); } Test void testGetChefById_withWireMock() { stubFor(get(urlEqualTo(/api/chefs/1001)) .willReturn(aResponse() .withStatus(200) .withHeader(Content-Type, application/json) .withBody({\id\:1001,\name\:\王師傅\,\specialty\:\粵菜\,\rating\:4.9}))); ChefDto result client.getChefById(1001L); assertThat(result.getName()).isEqualTo(王師傅); verify(getRequestedFor(urlEqualTo(/api/chefs/1001))); } }WireMock 跑起來之后RestClient 發(fā)請求就像打真實(shí)服務(wù)一樣DNS、端口、連接、HTTP 協(xié)議全過程都會走一遍這能暴露一些 MockRestServiceServer 永遠(yuǎn)發(fā)現(xiàn)不了的問題。比如我們團(tuán)隊(duì)之前就遇到過ChefDto里有個(gè)LocalDateTime字段普通 JSON 序列化沒問題但第三方服務(wù)返回的是yyyy-MM-dd HH:mm:ss這種非 ISO 格式在 MockRestServiceServer 里因?yàn)?response 直接走消息轉(zhuǎn)換器解析根本沒報(bào)警WireMock 下同樣的 JSON 結(jié)果解析報(bào)錯(cuò)才暴露出問題最后加了JsonFormat注解才解決。4.3 在單元測試?yán)锬M延遲和超時(shí)剛才提到的讀超時(shí)場景WireMock 很容易模擬Test void testReadTimeout() { stubFor(get(urlEqualTo(/api/chefs/slow)) .willReturn(aResponse() .withFixedDelay(6000) // 人為延遲 6 秒 .withBody({}))); RestClient timeoutClient RestClient.builder() .baseUrl(http://localhost:8089) .requestFactory(new JdkClientHttpRequestFactory( HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(3)) .build())) .build(); // 需要單獨(dú)設(shè)置讀超時(shí) JdkClientHttpRequestFactory factory (JdkClientHttpRequestFactory) timeoutClient.getRequestFactory(); factory.setReadTimeout(Duration.ofSeconds(2)); assertThatThrownBy(() - timeoutClient.get() .uri(/api/chefs/slow) .retrieve() .toBodilessEntity()) .isInstanceOf(ResourceAccessException.class) .hasMessageContaining(Read timed out); }有一點(diǎn)要提醒JdkClientHttpRequestFactory的讀超時(shí)必須在構(gòu)建RestClient之后單獨(dú)設(shè)置如果一開始就在HttpClient構(gòu)建時(shí)設(shè)置connectTimeout那只影響連接階段不影響讀取階段。這個(gè)坑我遇到過不止一次線上排查超時(shí)問題時(shí)要分清楚是連接超時(shí)還是讀超時(shí)。5. 常見問題與排查技巧實(shí)錄5.1 報(bào)了Unexpected request是什么原因怎么定位這是 MockRestServiceServer 最經(jīng)典的報(bào)錯(cuò)意思是有請求發(fā)出來了但你測試?yán)餂]有對這次請求做過期望聲明或者期望聲明的 URL/method 對不上。最常見的原因是 RestClient 實(shí)際請求的 URL 和你預(yù)期的不一致。排查技巧把異常堆棧完整拉出來里面會帶著實(shí)際請求的 method 和 URI對照你測試?yán)飁xpect的 matcher 逐項(xiàng)核對。另外特別提醒 URL 里的 query 參數(shù)requestTo(/api/chefs?city上海)這種寫法對中文參數(shù)和你預(yù)期不一致時(shí)很容易誤判建議用queryParam逐項(xiàng)匹配而不是拼字符串。5.2 RestClient 類找不到或者版本不兼容RestClient是 Spring 6.1 引入的類如果你用的 Spring Boot 3.1 或更早即使引了spring-web類也是不存在的。這時(shí)候 IDE 會報(bào)ClassNotFoundException或編譯錯(cuò)誤別糾結(jié)直接升 Spring Boot 到 3.2。還有一個(gè)很少人注意的點(diǎn)如果項(xiàng)目里手動指定了 Spring Framework 版本開發(fā)環(huán)境 Spring Boot 用的 6.1.x但內(nèi)部某個(gè)模塊鎖定了 6.0.x那也會出現(xiàn)類找不到Maven 依賴樹里查一下spring-web的版本即可。5.3 MockRestServiceServer mock 沒生效請求打到了真實(shí)服務(wù)發(fā)生這種情況九成是 RestClient 實(shí)例不是你綁定后那個(gè) builder 創(chuàng)建的。仔細(xì)檢查一下MockRestServiceServer.bindTo(builder).build()之后你的被測類是否用的是這個(gè) builder.build()出來的 RestClient如果被測類自己內(nèi)部RestClient.create()或者 new 了一個(gè)那 mock 自然攔不到。另外檢查是否多個(gè)RestClientBean 有同名的質(zhì)量問題Qualifier指定錯(cuò)了也會導(dǎo)致注入的不是同一個(gè)實(shí)例。5.4 JSON 反序列化報(bào)錯(cuò)但接口文檔明明沒錯(cuò)使用 RestClient 時(shí)./body()的解析依賴消息轉(zhuǎn)換器自動協(xié)商 content-type。如果第三方返回的Content-Type是application/json;charsetUTF-8沒問題但如果第三方服務(wù)不規(guī)范返回了text/plain或者根本沒有 Content-TypeRestClient 會認(rèn)為響應(yīng)不是 JSON走默認(rèn)的消息轉(zhuǎn)換器結(jié)果自然是反序列化失敗或者拿到一個(gè) String。解決辦法在 Client 的請求代碼里顯式指定.accept(MediaType.APPLICATION_JSON)并且與第三方約定響應(yīng)頭必須帶application/json。這個(gè)看著是小事但排查起來最容易讓人懷疑人生我見過有人在這個(gè)問題上卡了兩天。5.5 測試用例之間互相影響如果你在同一個(gè)測試類里寫了多個(gè)測試方法且都用BeforeEach綁定 MockRestServiceServer那么每個(gè)測試方法運(yùn)行前都會新建一個(gè) server 實(shí)例用例之間互不干擾。但如果用了SpringBootTest且測試類標(biāo)注Transactional事務(wù)會貫穿整個(gè)測試此時(shí)第三方服務(wù)調(diào)用不會被事務(wù)回滾影響別指望 mock 會在事務(wù)結(jié)束后自動恢復(fù)需要在BeforeEach里手動重置 server。用 WireMock 時(shí)多個(gè)測試類并行跑可能發(fā)生端口沖突建議每個(gè)測試類指定一個(gè)獨(dú)立端口不要全部用8089這種固定值CI 上爆端口沖突是常事。5.6 “SQL執(zhí)行10秒自動關(guān)閉”這類配置會不會影響 RestClient 測試很多人會把 RestClient 和數(shù)據(jù)庫連接池的超時(shí)概念搞混這里順手捋一下。Spring Boot 中關(guān)于“SQL 執(zhí)行 10 秒自動關(guān)閉”這類說法一般是指連接池的連接回收時(shí)長時(shí)間不歸還或事務(wù)超時(shí)它影響的范圍是數(shù)據(jù)庫連接和 HTTP 客戶端的超時(shí)完全是兩條線。RestClient 的超時(shí)配置在ClientHttpRequestFactory層與 JDBC 無關(guān)。所以你在測試 RestClient 時(shí)不需要也沒必要依賴 Spring 的spring.datasource.*超時(shí)配置連接超時(shí)和讀超時(shí)都在 RestClient 自己的 RequestFactory 里設(shè)置。測試時(shí)為了不等待過久通常把 connectTimeout 設(shè) 1~3 秒、readTimeout 設(shè) 2~5 秒即可線上再根據(jù)接口實(shí)際響應(yīng)時(shí)間放寬。5.7 測試時(shí)遇到JdkClientHttpRequestFactory和 HttpURLConnection 混用Spring Boot 3.2 默認(rèn)的ClientHttpRequestFactory是JdkClientHttpRequestFactory但在某些 Spring Boot 小版本上如果 classpath 里有 Apache HttpClient 或 Jetty 的客戶端自動配置可能選擇其他工廠。這會導(dǎo)致你在本地跑測試時(shí)沒問題一到 CI 就發(fā)現(xiàn) RestClient 行為不一致比如代理設(shè)置、連接池參數(shù)全變了。建議在配置類里顯式指定requestFactory不要依賴容器自動選擇這樣測試和生產(chǎn)環(huán)境行為才一致。如果你像我一樣習(xí)慣在RestClientConfig里手動構(gòu)建就把JdkClientHttpRequestFactory或你選擇的工廠實(shí)現(xiàn)固定寫死。6. 實(shí)操心得我踩過幾次坑之后的幾點(diǎn)體會寫這篇文章之前我把團(tuán)隊(duì)里所有用到 RestClient 的模塊翻了一遍發(fā)現(xiàn)很多測試代碼還在用 RestTemplate 時(shí)代的MockRestServiceServer.createServer()老寫法這讓我挺感慨的?？蚣芨?lián)Q代速度很快但很多人的測試知識還停留在上一代 API 上。我覺得 RestClient 的單元測試核心要把握住三點(diǎn)方案選型看需求——純單元測試用 MockRestServiceServer需要驗(yàn)證 HTTP 細(xì)節(jié)用 WireMock響應(yīng)類型要匹配——單個(gè)對象用ChefDto.class集合用ParameterizedTypeReference不要混用異常要全覆蓋——正常返回、4xx、5xx、連接異常、讀超時(shí)這五類場景都該有測試第三方接口才敢放心調(diào)。最后再分享一個(gè)小技巧MockRestServiceServer的expect支持一次聲明多個(gè)請求的期望如果被測代碼里循環(huán)調(diào)用了多次接口可以用expect(requestTo(...)).andExpect(...).andRespond(...)連續(xù)寫多個(gè)最后統(tǒng)一verify()。但如果你對一個(gè) URL 期望了兩次且兩次返回的內(nèi)容不一樣建議用andRespond的不同響應(yīng)或MockRestResponseCreators的withSuccess參數(shù)變體分別處理不要讓測試變成“最后一次賦值生效”那樣排錯(cuò)會非常痛苦。對于剛接觸 RestClient 的讀者我建議先把 3.4 節(jié)的基礎(chǔ)測試跑通再把 3.5 的異常場景補(bǔ)上最后再去研究 WireMock。測試是寫給未來的自己看的一個(gè)能快速定位問題的測試類比什么架構(gòu)理念都實(shí)在。