強大又優雅！Spring Boot 中 RestTemplate 的最佳實踐詳解
在現代開發中，API 的設計和調用變得尤為重要，尤其是基于 REST 架構的服務調用。RestTemplate 是 Spring 提供的用于同步調用 RESTful 服務的強大工具，它支持各種 HTTP 方法，如 GET、POST、PUT、DELETE 等。作為開發者，理解并掌握如何高效使用 RestTemplate 是優化服務交互性能的重要一步。本文旨在深入探討 RestTemplate 的 POST 請求方法以及 exchange() 和 execute() 等常用方法，幫助你在實際開發中靈活使用這些工具應對復雜的業務場景。
通過示例代碼，我們將詳細演示如何使用 RestTemplate 進行 POST 請求，包括如何設置請求頭和請求體、如何構建和傳遞復雜數據，以及如何處理返回的響應。同時，我們還將探索如何使用 exchange() 指定 HTTP 方法，實現靈活的請求處理。無論是初學者還是有經驗的開發者，這篇文章都將為你提供有價值的參考。
RestTemplate 是 Spring 提供的用于訪問 REST 服務的客戶端。
它提供了多種便捷的方法來訪問遠程 HTTP 服務，大大提高了客戶端代碼開發的效率。
之前，我使用 Apache 的 HttpClient 開發 HTTP 請求。代碼非常復雜，我不得不管理資源清理等問題，代碼繁瑣且包含大量冗余部分。
以下是我封裝的一個 post 請求工具的截圖：
圖片
本教程將指導你如何在 Spring 生態系統中使用 RestTemplate 進行 GET 和 POST 請求，并通過 exchange 方法來指定請求類型。同時，還會分析 RestTemplate 的核心方法。
閱讀完本教程后，你將能夠以優雅的方式進行 HTTP 請求。
RestTemplate 簡介
*RestTemplate* 是 *Spring* 中用于同步客戶端通信的核心類。它簡化了與 HTTP 服務的通信，并遵循 RestFul 原則。代碼只需提供一個 URL 并提取結果。
默認情況下，RestTemplate 依賴于 JDK 的 HTTP 連接工具。但是，你可以通過 setRequestFactory 屬性切換到其他 HTTP 工具源，例如 Apache HttpComponents、Netty 和 OkHttp。
RestTemplate 大大簡化了表單數據的提交，并包含對 JSON 數據的自動轉換。
然而，要真正掌握它的使用，必須理解 HttpEntity 的結構（包括 headers 和 body）以及它與 uriVariables 之間的區別。
這一點在 POST 請求中尤為明顯，稍后我們將詳細討論。
此類的主要入口點基于六種 HTTP 方法：
圖片
此外，exchange 和 execute 可以與上述方法互換使用。
在內部，RestTemplate 默認使用 HttpMessageConverter 實例，將 HTTP 消息轉換為 POJO或將 POJO 轉換為 HTTP 消息。默認情況下，它會為主要的 MIME 類型注冊轉換器，但你也可以通過 setMessageConverters 注冊其他轉換器。
（在實際使用中，這一點并不十分明顯；許多方法都有一個 responseType 參數，你可以傳遞一個與響應體映射的對象，底層的 HttpMessageConverter 會進行映射。）
HttpMessageConverterExtractor<T> responseExtractor =
new HttpMessageConverterExtractor<>(responseType, getMessageConverters(), logger);HttpMessageConverter.java 源代碼：
public interface HttpMessageConverter<T> {
// 判斷該轉換器是否可以讀取給定的類。
boolean canRead(Class<?> clazz, @Nullable MediaType mediaType);
// 判斷該轉換器是否可以寫入給定的類。
boolean canWrite(Class<?> clazz, @Nullable MediaType mediaType);
// 返回一個 List<MediaType>
List<MediaType> getSupportedMediaTypes();
// 讀取輸入消息
T read(Class<? extends T> clazz, HttpInputMessage inputMessage)
throws IOException, HttpMessageNotReadableException;
// 將對象寫入輸出消息
void write(T t, @Nullable MediaType contentType, HttpOutputMessage outputMessage)
throws IOException, HttpMessageNotWritableException;
}在內部，RestTemplate 默認使用 SimpleClientHttpRequestFactory 和 DefaultResponseErrorHandler 來分別處理 HTTP 請求的創建和錯誤處理。
然而，你可以通過 setRequestFactory 和 setErrorHandler 來覆蓋這些默認行為。
GET 請求
getForObject() 方法
public <T> T getForObject(String url, Class<T> responseType, Object... uriVariables){}
public <T> T getForObject(String url, Class<T> responseType, Map<String, ?> uriVariables)
public <T> T getForObject(URI url, Class<T> responseType)getForObject() 方法可以將 HTTP 響應直接轉換為 POJO，而不像 getForEntity() 需要額外處理響應。
getForObject 會直接返回 POJO，省略了大量響應信息。
POJO 示例:
public class Notice {
private int status;
private Object msg;
private List<DataBean> data;
}
public class DataBean {
private int noticeId;
private String noticeTitle;
private Object noticeImg;
private long noticeCreateTime;
private long noticeUpdateTime;
private String noticeContent;
}無參數的 GET 請求
/**
* 無參數的 GET 請求
*/
@Test
public void restTemplateGetTest(){
RestTemplate restTemplate = new RestTemplate();
Notice notice = restTemplate.getForObject("http://icoderoad.com/notice/list/1/5", Notice.class);
System.out.println(notice);
}控制臺輸出:
INFO 19076 --- [ main] c.w.s.c.w.c.HelloControllerTest
: Started HelloControllerTest in 5.532 seconds (JVM running for 7.233)
Notice{status=200, msg=null, data=[DataBean{noticeId=21, noticeTitle='aaa', noticeImg=null,
noticeCreateTime=1525292723000, noticeUpdateTime=1525292723000, noticeContent='<p>aaa</p>'},
DataBean{noticeId=20, noticeTitle='ahaha', noticeImg=null, noticeCreateTime=1525291492000,
noticeUpdateTime=1525291492000, noticeContent='<p>ah.......'帶參數的 GET 請求 1
Notice notice = restTemplate.getForObject("http://icoderoad.com/notice/list/{1}/{2}", Notice.class, 1, 5);可以看到，使用了占位符 {1} 和 {2}。
帶參數的 GET 請求 2
Map<String, String> map = new HashMap<>();
map.put("start", "1");
map.put("page", "5");
Notice notice = restTemplate.getForObject("http://icoderoad.com/notice/list/", Notice.class, map);在這種情況下，使用 Map 加載參數，默認情況下會以 PathVariable 格式解析 URL。
getForEntity() 方法
public <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Object... uriVariables){}
public <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Map<String, ?> uriVariables){}
public <T> ResponseEntity<T> getForEntity(URI url, Class<T> responseType){}與 getForObject() 不同，此方法返回 ResponseEntity 對象。
如果需要將其轉換為 POJO，則必須使用 JSON 工具類，可根據個人偏好選擇。
對于不熟悉解析 JSON 的人，可以查閱工具如 FastJson 或 Jackson。接下來我們來探討 ResponseEntity 的相關方法。
ResponseEntity、HttpStatus 和 BodyBuilder 的結構
//ResponseEntity.java
public HttpStatus getStatusCode(){}
public int getStatusCodeValue(){}
public boolean equals(@Nullable Object other) {}
public String toString() {}
public static BodyBuilder status(HttpStatus status) {}
public static BodyBuilder ok() {}
public static <T> ResponseEntity<T> ok(T body) {}
public static BodyBuilder created(URI location) {}
...
//HttpStatus.java
public enum HttpStatus {
public boolean is1xxInformational() {}
public boolean is2xxSuccessful() {}
public boolean is3xxRedirection() {}
public boolean is4xxClientError() {}
public boolean is5xxServerError() {}
public boolean isError() {}
}
//BodyBuilder.java
public interface BodyBuilder extends HeadersBuilder<BodyBuilder> {
// 通過 Content-Length 頭設置響應實體的內容長度
BodyBuilder contentLength(long contentLength);
// 設置響應實體的 MediaType
BodyBuilder contentType(MediaType contentType);
// 設置響應實體的內容并返回
<T> ResponseEntity<T> body(@Nullable T body);
}如上所示，ResponseEntity 包含了來自 HttpStatus 和 BodyBuilder 的信息，這使得處理原始響應變得更加簡單。
示例：
@Test
public void rtGetEntity(){
RestTemplate restTemplate = new RestTemplate();
ResponseEntity<Notice> entity = restTemplate.getForEntity("http://icoderoad.com/notice/list/1/5", Notice.class);
HttpStatus statusCode = entity.getStatusCode();
System.out.println("statusCode.is2xxSuccessful()" + statusCode.is2xxSuccessful());
Notice body = entity.getBody();
System.out.println("entity.getBody()" + body);
ResponseEntity.BodyBuilder status = ResponseEntity.status(statusCode);
status.contentLength(100);
status.body("在此處添加一個聲明");
ResponseEntity<Class<Notice>> body1 = status.body(Notice.class);
Class<Notice> body2 = body1.getBody();
System.out.println("body1.toString()" + body1.toString());
}輸出:
statusCode.is2xxSuccessful() true
entity.getBody() Notice{status=200, msg=null, data=[DataBean{noticeId=21, noticeTitle='aaa', ...
body1.toString() <200 OK, class com.waylau.spring.cloud.weather.pojo.Notice, {Content-Length=[100]}>當然，像 getHeaders() 這樣的方法也是可用的，但在此不作示例。
POST 請求
類似于 GET 請求，POST 請求也有 postForObject 和 postForEntity 方法。
public <T> T postForObject(String url, @Nullable Object request, Class<T> responseType, Object... uriVariables)
throws RestClientException {}
public <T> T postForObject(String url, @Nullable Object request, Class<T> responseType, Map<String, ?> uriVariables)
throws RestClientException {}
public <T> T postForObject(URI url, @Nullable Object request, Class<T> responseType) throws RestClientException {}示例
這里我使用一個郵箱驗證接口進行測試。
@Test
public void rtPostObject(){
RestTemplate restTemplate = new RestTemplate();
String url = "http://47.xxx.xxx.96/register/checkEmail";
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
map.add("email", "844072586@qq.com");
HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(map, headers);
ResponseEntity<String> response = restTemplate.postForEntity(url, request, String.class);
System.out.println(response.getBody());
}執行結果：
{"status":500,"msg":"該郵箱已經注冊","data":null}為什么使用 MultiValueMap？
MultiValueMap 是 Map 的子類，它允許每個鍵存儲多個值。這里簡單介紹該接口：
public interface MultiValueMap<K, V> extends Map<K, List<V>> {...}使用 MultiValueMap 的原因是 HttpEntity 接受的請求類型為 MultiValueMap：
public HttpEntity(@Nullable T body, @Nullable MultiValueMap<String, String> headers){}在這個構造函數中，我們傳入的 map 是請求體，headers 是請求頭。
我們使用 HttpEntity 是因為，盡管 restTemplate.postForEntity 方法似乎接受 @Nullable Object request 類型，但如果深入追溯，會發現這個 request 是通過 HttpEntity 解析的。核心代碼如下：
if (requestBody instanceof HttpEntity) {
this.requestEntity = (HttpEntity<?>) requestBody;
} else if (requestBody != null) {
this.requestEntity = new HttpEntity<>(requestBody);
} else {
this.requestEntity = HttpEntity.EMPTY;
}我曾嘗試使用 map 傳遞參數，雖然編譯時沒有報錯，但請求無效，最終出現 400 錯誤。
這種請求方式已經滿足 POST 請求的需求，同時，cookie 作為請求頭的一部分，也可以根據需要進行設置。
其他方法與此類似。
使用 exchange 指定 HTTP 方法
exchange() 方法與 getForObject()、getForEntity()、postForObject() 和 postForEntity() 不同之處在于它允許你指定 HTTP 方法。
你會注意到，所有的 exchange 方法似乎都有 @Nullable HttpEntity<?> requestEntity 參數，這意味著我們需要使用 HttpEntity 來傳遞請求體。正如前面提到的，使用 HttpEntity性能更好。
示例
@Test
public void rtExchangeTest() throws JSONException {
RestTemplate restTemplate = new RestTemplate();
String url = "http://icoderoad.com/notice/list";
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
JSONObject jsonObj = new JSONObject();
jsonObj.put("start", 1);
jsonObj.put("page", 5);
HttpEntity<String> entity = new HttpEntity<>(jsonObj.toString(), headers);
ResponseEntity<JSONObject> exchange = restTemplate.exchange(url, HttpMethod.GET, entity, JSONObject.class);
System.out.println(exchange.getBody());
}這次我使用了 JSONObject 來傳遞和返回數據。其他 HttpMethod 方法的使用類似。
使用 execute 指定 HTTP 方法
execute() 方法類似于 exchange()，它允許你指定不同的 HttpMethod 類型。但不同之處在于它返回的響應體是一個對象 <T>，而不是 ResponseEntity<T>。
需要強調的是，execute() 方法是上述所有方法的底層實現。以下是一個示例：
@Override
@Nullable
public <T> T postForObject(String url, @Nullable Object request, Class<T> responseType, Map<String, ?> uriVariables)
throws RestClientException {
RequestCallback requestCallback = httpEntityCallback(request, responseType);
HttpMessageConverterExtractor<T> responseExtractor =
new HttpMessageConverterExtractor<>(responseType, getMessageConverters(), logger);
return execute(url, HttpMethod.POST, requestCallback, responseExtractor, uriVariables);
}結語
通過對 RestTemplate 不同方法的深入講解，特別是 POST 請求的使用以及 exchange()、execute() 的靈活運用，本文展示了在開發過程中如何使用這些方法簡化與外部服務的交互，并提升代碼的可讀性和維護性。在面對復雜的業務需求時，掌握這些技術將幫助開發者在請求數據、處理響應以及提升 API 性能方面取得更好的平衡。
對于高效的 HTTP 請求處理，RestTemplate 提供了豐富的功能，靈活支持多種請求方式和參數配置，極大地簡化了開發流程。隨著項目復雜度的增加，理解和掌握這些工具的使用技巧，能夠大大提升開發效率，同時減少潛在的錯誤。通過深入研究 RestTemplate，我們可以構建出更加健壯、高效的服務交互機制，滿足不斷變化的業務需求。希望本文能為你提供深入的理解，助力你的開發之旅。
