在 Spring Boot 生态系统中，与外部世界交互通常是应用程序最关键的部分之一。无论我们是调用第三方支付网关、微服务之间的内部通信，还是仅仅从公共 API 获取数据，高效且可靠的 HTTP 客户端都是必不可少的。
过去几年，我们习惯了依赖 INLINECODE88230ff6。它就像一把老式的瑞士军刀，功能齐全但略显笨重。然而，随着 Spring Framework 6.1 和 Spring Boot 3.2 的发布，INLINECODE84526408 已正式进入维护模式。Spring 团队建议我们转向更现代的解决方案。于是，RestClient 应运而生。
在这篇文章中，我们将深入探讨这个全新的 HTTP 客户端。我们将从基本概念入手，通过丰富的实战代码示例，展示它如何利用流畅的 API 简化我们的开发工作，以及它相比旧方案有哪些不可替代的优势。
目录
什么是 RestClient？
简单来说，INLINECODEcb8c16f2 是 Spring 为我们提供的下一代同步 HTTP 客户端。它的设计初衷是填补 INLINECODEcf71d872 的空缺，同时提供比 RestTemplate 更符合现代 Java 编程习惯的 API。
你可能会问：“为什么不用 INLINECODEe3385c30？” 这是一个很好的问题。INLINECODEa9de003f 虽然强大且支持响应式编程，但它的学习曲线相对陡峭，且对于简单的同步调用来说，引入响应式栈显得有些“杀鸡用牛刀”。INLINECODE4f2e5a61 则完美地平衡了这两点：它拥有像 INLINECODE09a9d7cb 一样流畅、易读的 API 设计，但在底层默认使用阻塞方式发送请求，这使得它在大多数基于 Servlet 的传统 Spring Boot 应用中更加自然和易用。
RestClient 的核心优势
在我们开始写代码之前，让我们先了解一下为什么你应该考虑在下一个项目中使用它：
- 流畅的 API 设计：基于构建器模式，代码读起来像自然语言，极大地提高了可读性。
- 极简的错误处理：提供了一种声明式的方式来处理特定的 HTTP 状态码，告别繁琐的
if-else判断。 - 灵活性：虽然默认是同步的，但它也可以轻松利用底层库进行异步操作。
- 现代化的基础设施：原生支持 HTTP/2，并且可以配置使用 JDK 11+ 的
HttpClient或 Apache HttpComponents 等高性能库。
创建你的第一个 RestClient
一切的开始都是实例化。我们可以使用构建器模式来创建一个客户端实例。
// 创建一个默认配置的 RestClient
RestClient defaultClient = RestClient.builder().build();
对于大多数快速原型开发来说，这就足够了。但在实际的企业级开发中，我们通常会配置一些基础信息，比如基础 URL。
RestClient restClient = RestClient.builder()
.baseUrl("https://api.example.com") // 设置基础 URL，避免重复编写
.defaultHeader("X-Request-ID", UUID.randomUUID().toString()) // 设置默认请求头
.build();
在上面的代码中，我们做了两件事：首先设置了一个 baseUrl，这样在后续的请求中我们只需要填写相对路径即可；其次，我们添加了一个默认的请求头，这对于分布式系统中的链路追踪非常有用。
发起 GET 请求
让我们从最简单的场景开始：从服务器获取数据。
基础用法
假设我们需要获取一个用户资源的 JSON 字符串。
String result = restClient.get()
.uri("/users/{id}", 101) // 使用占位符传递路径变量
.retrieve() // 发起请求并获取响应
.body(String.class); // 将响应体转换为 String
System.out.println(result);
代码解析：
-
.get(): 指定 HTTP 方法为 GET。 - INLINECODE121c4389: 这里展示了路径变量的使用，INLINECODE0c1acb1c 会被替换为
101。这不仅安全，还能防止 URL 注入风险。 -
.retrieve(): 这是一个关键方法，它告诉客户端执行请求并返回响应体。 - INLINECODE5b08940a: 我们直接将结果读取为 INLINECODEe72423db。实际上，你可以将其替换为任何 POJO 类，只要 Jackson 能够反序列化它。
直接映射为 Java 对象
在实际业务中，我们很少直接操作字符串。让我们看看如何直接获取对象。
// 假设这是一个简单的数据记录类 (Record)
record User(Long id, String username, String email) {}
User user = restClient.get()
.uri("/users/101")
.retrieve()
.body(User.class); // 自动将 JSON 映射为 User 对象
if (user != null) {
System.out.println("获取用户: " + user.username());
}
这种流畅的链式调用让我们免去了手动处理 INLINECODEe05f1c4f 和 INLINECODE463530f9 的痛苦，Spring 会自动处理底层的繁琐操作。
处理查询参数和请求头
真实世界的 API 往往不仅仅是简单的 GET 请求，我们经常需要传递参数或特定的认证信息。
String response = restClient.get()
.uri("/users")
// 添加查询参数 ?active=true&role=admin
.queryParam("active", "true")
.queryParam("role", "admin")
// 添加特定的请求头
.header("Authorization", "Bearer eyJhbGciOi...")
.accept(MediaType.APPLICATION_JSON)
.retrieve()
.body(String.class);
实用见解：在处理 Authorization 头时，通常会结合拦截器使用（我们稍后会讲到），这样可以避免在每个请求方法中都手动传递 Token。
深入：错误处理与状态码
这是 INLINECODE98e1bc97 最令人兴奋的特性之一。在使用 INLINECODEe7fd07a8 时，我们经常不得不捕获 INLINECODE7fb1d36f 或 INLINECODE7dc353a9。有了 RestClient，我们可以采用声明式的方式来定义错误处理逻辑。
基于状态码的处理
假设 API 在资源未找到时返回 404，在服务器出错时返回 500。我们可以这样优雅地处理：
import org.springframework.web.client.RestClient;
import reactor.core.publisher.Mono;
String response = restClient.get()
.uri("/external/resource")
.retrieve()
.onStatus(
// 定义状态码谓词：处理所有 4xx 错误
HttpStatus::is4xxClientError,
// 定义错误处理函数
(request, response) -> {
throw new RuntimeException("客户端请求错误，状态码: " + response.getStatusCode());
}
)
.onStatus(
// 定义状态码谓词：处理所有 5xx 错误
HttpStatus::is5xxServerError,
(request, response) -> {
// 这里可以添加更复杂的逻辑，比如记录日志
throw new RuntimeException("服务器内部错误，状态码: " + response.getStatusCode());
}
)
.body(String.class);
注意：在 INLINECODE71a343df 中，如果你不想抛出异常，也可以返回一个 INLINECODE2c223f60 来吞掉错误或执行副作用，但在同步流中抛出异常通常是更符合预期的行为。
使用 Exchange 进行更底层的控制
如果我们需要访问完整的响应对象（包括所有的 Header、Cookie 等），而不仅仅是 Body，我们可以使用 INLINECODE9b5374a3 方法替代 INLINECODE8c9c7ee3。
RestClient.ResponseSpec result = restClient.get()
.uri("/secure-data")
.retrieve();
// 或者更高级的 exchange
restClient.get()
.uri("/info")
.exchange((request, response) -> {
if (response.getStatusCode().is2xxSuccessful()) {
return response.bodyToEntity(String.class);
} else {
// 自定义非 200 响应的处理
return "Error: " + response.getStatusCode();
}
});
这种方法给了我们最大的灵活性，让我们可以根据响应的元数据做出决策。
发送 POST 请求与序列化
不仅获取数据，创建和更新数据同样重要。RestClient 默认集成了 Jackson，可以自动将 Java 对象序列化为 JSON。
发送 JSON 数据
// 使用 Java Record 创建 DTO
record NewUserRequest(String name, String email) {}
NewUserRequest newUser = new NewUserRequest("张三", "[email protected]");
User createdUser = restClient.post()
.uri("/users")
.contentType(MediaType.APPLICATION_JSON) // 明确指定内容类型
.body(newUser) // 自动序列化为 JSON
.retrieve()
.body(User.class); // 将响应再次反序列化回来
表单提交
并不是所有的 API 都是 JSON。有些接口（特别是传统的 OAuth2 授权接口）仍然使用 application/x-www-form-urlencoded 格式。
String tokenResponse = restClient.post()
.uri("/oauth/token")
.contentType(MediaType.APPLICATION_FORM_URLENCODED)
// 使用 BodyInserters 构建表单数据
.body(BodyInserters.fromFormData("grant_type", "client_credentials")
.with("client_id", "my-client")
.with("client_secret", "secret"))
.retrieve()
.body(String.class);
高级配置：超时与底层客户端
在微服务架构中，合理的超时设置是防止系统雪崩的关键。INLINECODEa802423c 允许我们通过定制底层的 INLINECODEedb38a4d 来配置这些参数。
使用 JDK HttpClient 配置超时
从 JDK 11 开始，Java 拥有了一个高性能的 INLINECODE59cc967d。我们可以将其与 INLINECODE110a79ef 结合使用。
import java.net.http.HttpClient;
import java.time.Duration;
import org.springframework.http.client.JdkClientHttpRequestFactory;
// 1. 配置 JDK HttpClient
HttpClient jdkHttpClient = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(5)) // 连接超时 5秒
.build();
// 2. 将其注入到 RestClient 的构建器中
RestClient clientWithTimeout = RestClient.builder()
.requestFactory(new JdkClientHttpRequestFactory(jdkHttpClient))
.baseUrl("https://api.example.com")
.build();
实用见解：对于需要读取超时控制的场景，直接在 INLINECODE2bc301d9 配置时通过 INLINECODE8610f976 并不能覆盖读取超时。在某些特定的底层实现中（如 Apache HttpComponents），你可以更精细地设置 INLINECODE5b3e9982 和 INLINECODEf2d95d55。如果 JDK 版本过低或需要更多高级网络参数（如连接池管理），建议切换到使用 HttpComponentsClientHttpRequestFactory。
异步支持与集成
虽然 INLINECODEf48f8b4c 本身是同步阻塞的，但你可以轻松地将其包装在 INLINECODE3bdef2b4 中以实现异步调用，从而不阻塞主线程。
import java.util.concurrent.CompletableFuture;
public CompletableFuture getUserAsync(String userId) {
// 使用 supplyAsync 在后台线程池中执行
return CompletableFuture.supplyAsync(() ->
restClient.get()
.uri("/users/{id}", userId)
.retrieve()
.body(User.class),
// 建议指定自定义线程池，避免使用 ForkJoinPool.commonPool()
executorService
);
}
拦截器：统一处理横切关注点
如果你需要在每个请求中都添加同一个 Header（比如 INLINECODEb2d4ee13），或者记录所有请求的日志，使用拦截器是最佳实践。我们可以通过自定义 INLINECODE6f05e248 来实现。
import org.springframework.http.HttpRequest;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpRequestInterceptor;
import org.springframework.http.client.ClientHttpResponse;
// 自定义拦截器
class LoggingInterceptor implements ClientHttpRequestInterceptor {
@Override
public ClientHttpResponse intercept(
HttpRequest request,
byte[] body,
ClientHttpRequestExecution execution) throws IOException {
System.out.println("正在发送请求至: " + request.getURI());
// 在这里可以在请求发送前修改 Header 或 Body
ClientHttpResponse response = execution.execute(request, body);
System.out.println("收到响应状态码: " + response.getStatusCode());
return response;
}
}
// 注册拦截器
RestClient clientWithInterceptor = RestClient.builder()
.requestInterceptors(interceptors -> {
interceptors.add(new LoggingInterceptor());
})
.build();
通过这种方式，你可以将认证逻辑（如获取和刷新 Token）封装在一个拦截器中，从而保持业务代码的整洁。
常见陷阱与最佳实践
- 资源管理：INLINECODEce4b8fe2 实例通常设计为可重用的单例。不要为每一个请求都创建一个新的 INLINECODE388ef7c2，这会浪费连接池资源。
- 异常处理：默认情况下，如果是 4xx 或 5xx 状态码，INLINECODE6ad1628c 方法可能会抛出异常（取决于底层配置）。务必使用 INLINECODEda2efc24 来处理这些异常，或者确保你的全局异常处理器能够捕获它们。
- 泛型类型擦除：当你需要返回 INLINECODE4955cc9b 这样的泛型集合时，直接传 INLINECODE875a8528 可能会因为 Java 的类型擦除而导致反序列化失败（Jackson 会将其视为 List
总结
随着 Spring Boot 3.2 的普及，INLINECODE7da071fd 无疑将成为 Java 开发者处理 HTTP 请求的首选工具。它不仅修复了 INLINECODE994d7615 的设计缺陷，还提供了比 WebClient 更低的学习曲线。
在这篇文章中，我们不仅学习了如何发送基本的 GET 和 POST 请求，还深入探讨了错误处理、超时配置、表单提交以及拦截器的使用。这些技能足以帮助你在实际项目中构建健壮的服务间通信层。
下一步建议：
在你的下一个 Spring Boot 项目中，尝试创建一个配置类，专门用于构建一个预配置好的 RestClient Bean。尝试把它集成到你现有的代码库中，感受一下它带来的流畅体验吧！