feat:增加RestClient文档

2026-01-08 09:36:35 +08:00
parent 4f07faaa64
commit 2549b696e1
1 changed files with 130 additions and 0 deletions
--- a/docs/Web-Backend/SpringBoot/SpringBoot-RestClient.md
+++ b/docs/Web-Backend/SpringBoot/SpringBoot-RestClient.md
@@ -2,3 +2,133 @@
  title: SpringBoot RestClient简介
  date: 2026-01-06
 ---
+
+# 一、简介
+&emsp;&emsp;RestClient 是 Spring Framework 6.1（及对应的 Spring Boot 3.2+）推出的新一代同步 HTTP 客户端，设计目标是替代传统的 RestTemplate（Spring 已标记 RestTemplate 为维护模式，不再新增功能），同时结合了 WebClient 的流畅 API 设计，又保持了 RestTemplate 的同步、简单易用的特点。    
+
+# 二、使用
+## 2.1 创建实例
+```java
+@Configuration
+public class RestClientConfig {
+    final String baseUrl = "https://demo.com";
+
+    @Bean
+    public RestClient restClient() {
+
+        return RestClient.builder()
+                // 基础RURL
+                .baseUrl(baseUrl)  
+                // 默认请求头 请求体为JSON格式
+                .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
+                // 默认请求头 响应体为JSON格式
+                .defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE)
+                .build();
+    }
+}
+```
+
+## 2.2 HTTP请求
+```java
+@Service
+public class RestClientService {
+
+    @Resource
+    private RestClient restClient;
+
+    // 1. GET 请求：获取单个资源
+    public Post getPostById(Long id) {
+        return restClient.get() // 指定 GET 方法
+                .uri("/posts/{id}", id) // 请求路径（支持路径参数）
+                .retrieve() // 执行请求并获取响应
+                .body(Post.class); // 解析响应体为Post实体
+    }
+
+    // 2. GET 请求：获取列表并解析为 Map
+    public Map<String, Object>[] getAllPosts() {
+        return restClient.get()
+                .uri("/posts")
+                .retrieve()
+                .body(Map[].class); // 解析为 Map 数组（适合未知结构的 JSON）
+    }
+
+    // 3. POST 请求：提交数据并获取响应
+    public Boolean createPost(Post post) {
+        return restClient.post() // 指定 POST 方法
+                .uri("/posts")
+                .body(post) // 设置请求体
+                .retrieve()
+                .body(Boolean.class);
+    }
+
+    // 4. PUT 请求：更新资源
+    public Boolean updatePost(Long id, Post post) {
+        return restClient.put() // 指定 PUT 方法
+                .uri("/posts/{id}", id)
+                .body(post)
+                .retrieve()
+                .body(Boolean.class);
+    }
+
+    // 5. DELETE 请求：删除资源
+    public void deletePost(Long id) {
+        restClient.delete() // 指定 DELETE 方法
+                .uri("/posts/{id}", id)
+                .retrieve(); // DELETE 请求通常无响应体
+    }
+}
+```
+
+::: tip
+在.retrieve()之前的是请求阶段，在此之后是响应阶段。  
+因此在此之前的.body()是请求体，在此之后的.body()是响应体。   
+:::
+
+## 2.3 进阶用法
+### 2.3.1 设置超时时间
+```java
+@Bean
+public RestClient restClient() {
+    // 创建请求工厂，设置超时
+    ClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory() {{
+        setConnectTimeout(3000); // 连接超时 3 秒
+        setReadTimeout(5000);    // 读取超时 5 秒
+    }};
+
+    return RestClient.builder()
+            .baseUrl(baseUrl)
+            .requestFactory(factory) // 设置请求工厂
+            .build();
+}
+```
+
+### 2.3.2 添加请求拦截器
+```java
+@Bean
+public RestClient restClient() {
+    return RestClient.builder()
+            .baseUrl(baseUrl)
+            // 添加拦截器
+            .requestInterceptor(request -> {
+                request.getHeaders().add("Authorization", "Bearer your-token-here");
+            })
+            .build();
+}
+```
+
+### 2.3.3 自定义响应处理
+```java
+public String getPostWithErrorHandling(Long id) {
+    return restClient.get()
+            .uri("/posts/{id}", id)
+            .retrieve()
+            // 自定义状态码处理
+            .onStatus(status -> status.is4xxClientError(), (request, response) -> {
+                throw new RuntimeException("客户端错误：" + response.getStatusCode() + "，路径：" + request.getURI());
+            })
+            .onStatus(status -> status.is5xxServerError(), (request, response) -> {
+                throw new RuntimeException("服务端错误：" + response.getStatusCode());
+            })
+            .body(String.class);
+}
+```