1. 项目概述：为什么我们需要一个新的 RestClient？

如果你和我一样，在过去几年里深度使用 Spring Boot 进行微服务或分布式系统开发，那么对于发起 HTTP 请求这件事，你一定有过不少纠结。从最早的RestTemplate，到后来社区力推的WebClient，再到各种第三方封装，选择不少，但痛点也一直存在。RestTemplate简单直接，但功能上总觉得差那么点意思，尤其是在响应式和非阻塞编程成为趋势的今天，它显得有些“老派”。WebClient功能强大，响应式编程范儿很酷，但对于一个简单的同步 HTTP 调用来说，它的学习曲线和代码量又显得有点“杀鸡用牛刀”。

就在这种背景下，Spring Boot 3.2 带来了一个让我眼前一亮的特性：RestClient。它不是对旧框架的修修补补，而是一个全新的、现代化的同步 HTTP 客户端，旨在成为RestTemplate的继任者，同时吸收了WebClient在 API 设计上的诸多优点。我第一次在官方文档里看到它时，感觉就像 Spring 团队终于听到了我们这些一线开发者的心声——我们需要一个既简单易用，又功能强大、符合现代 Java 编码习惯的 HTTP 客户端。

简单来说，RestClient 的定位非常清晰：为同步 HTTP 调用提供一套流畅、声明式的 API。它底层默认基于我们熟悉的HttpClient（JDK 11+），性能有保障。它的 API 设计借鉴了WebClient的Builder模式和链式调用，写起来非常流畅，同时又去掉了响应式那些复杂的Mono、Flux概念，回归同步世界的直观。对于绝大多数日常的 REST API 调用、第三方服务集成场景，RestClient 提供了一个近乎完美的选择。它解决了“我想简单快速地发个请求，但又不想用那个略显过时的RestTemplate”的核心矛盾。

2. 核心特性与设计哲学深度解析

2.1 流畅的链式 API：从“怎么做”到“做什么”

RestClient 最直观的改变就是其 API 设计。我们来回想一下RestTemplate的典型用法：你需要先创建一个实例（或者注入一个配置好的 Bean），然后调用getForObject、postForEntity这类方法，传入 URL、请求体、响应类型等一堆参数。代码逻辑是“命令式”的，告诉框架“一步一步怎么做”。

而 RestClient 采用了“流畅接口”和“建造者模式”。你通过RestClient.create()或RestClient.builder()开始，然后像搭积木一样，通过链式调用一步步声明你的请求：设置基础 URL、添加默认头信息、配置拦截器、定义错误处理，最后才执行请求并处理响应。整个代码读起来更像是在描述“我要做什么”，而不是“我该如何做”。

举个例子，一个带认证和错误处理的 GET 请求，在 RestClient 中可能长这样：

MyResponse response = restClient.get() .uri("/api/v1/users/{id}", userId) .header("Authorization", "Bearer " + token) .retrieve() .onStatus(status -> status.value() == 404, (request, response) -> { throw new UserNotFoundException("User not found with id: " + userId); }) .body(MyResponse.class);

这段代码从上到下，清晰地表达了意图：获取（get）某个资源（uri），携带认证头（header），检索响应（retrieve），针对 404 状态码进行特殊处理（onStatus），最后将响应体转换为特定类型（body）。这种声明式的风格，极大地提升了代码的可读性和可维护性。

2.2 强大的响应处理与错误处理机制

错误处理一直是 HTTP 客户端编程中的繁琐环节。RestTemplate默认在遇到 4xx/5xx 状态码时会抛出HttpClientErrorException或HttpServerErrorException，你需要用try-catch来包裹，或者配置一个自定义的ResponseErrorHandler，后者配置起来并不直观。

RestClient 在这方面做了大幅改进，引入了更精细、更灵活的错误处理策略。核心方法是retrieve()后可以链式调用的onStatus方法。这个方法接受一个Predicate<HttpStatusCode>来判断哪些状态码需要被视作错误，以及一个RestClient.ResponseSpec.ErrorHandler来处理这个错误。你可以为不同的状态码定义不同的处理逻辑。

String result = restClient.get() .uri("/api/items/{id}", itemId) .retrieve() .onStatus(status -> status.is4xxClientError(), (req, resp) -> { // 处理所有4xx错误，例如记录日志或抛出自定义业务异常 log.warn("Client error occurred for request: {}", req.getURI()); throw new BusinessException("Client request error"); }) .onStatus(status -> status.value() == 503, (req, resp) -> { // 专门处理503服务不可用 throw new ServiceUnavailableException("Backend service is down"); }) .body(String.class);

这种设计的好处是，错误处理逻辑和正常的业务逻辑在代码结构上是分离且清晰的。你可以针对不同的 API、不同的错误类型进行定制，而不是一股脑地捕获一个通用的异常再去里面做instanceof判断。对于响应体的处理，body(Class<T>)方法会自动利用配置的HttpMessageConverter进行转换，和 Spring MVC 中的体验保持一致，非常顺手。

2.3 灵活的配置与扩展能力

RestClient 的配置入口是RestClient.Builder。通过这个建造者，你可以集中配置一些全局行为，然后基于此创建出具有特定配置的RestClient实例。这种设计非常适合在微服务环境中，为不同的下游服务配置不同的客户端实例。

1. 基础配置示例：

@Bean public RestClient orderServiceClient() { return RestClient.builder() .baseUrl("http://order-service:8080") .defaultHeader("X-Client-ID", "my-app") .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) .requestInterceptor(new LoggingInterceptor()) .build(); } @Bean public RestClient paymentServiceClient() { return RestClient.builder() .baseUrl("https://api.payment.com") .defaultHeader("Authorization", "Basic " + encodeCredentials(user, pass)) .requestInitializer(request -> request.getHeaders().setAccept(List.of(MediaType.APPLICATION_JSON))) .build(); }

这里我为订单服务和支付服务分别创建了独立的RestClientBean。每个客户端都有自己的基础 URL、默认请求头和拦截器。这种细粒度的配置比在全局使用一个RestTemplate并动态修改请求参数要清晰和安全得多。

2. 核心配置项解析：

• baseUrl: 设置所有请求的默认基础路径，后续的uri()调用都是相对路径。
• defaultHeader/defaultHeaders: 设置每个请求都会携带的默认头信息，如认证令牌、内容类型等。
• requestInterceptor: 添加请求拦截器。这是非常强大的扩展点，你可以在这里统一添加签名、链路追踪（TraceId）、日志记录、重试逻辑等。拦截器接收ClientHttpRequest，允许你修改请求头、体甚至 URI。
• requestFactory: 自定义用于创建底层连接的ClientHttpRequestFactory。大多数情况下，默认的基于 JDKHttpClient的工厂已经足够，但在需要特殊代理或 SSL 配置时，可以在这里进行定制。
• messageConverters: 配置用于序列化请求体和反序列化响应体的转换器列表。Spring Boot 会自动配置好一套常用的（如 JSON 用的MappingJackson2HttpMessageConverter），你也可以自定义或调整顺序。

实操心得：拦截器的正确使用姿势拦截器是复用通用逻辑的利器。一个常见的模式是创建一个“认证拦截器”，从线程上下文或安全上下文中获取当前用户的令牌，并自动添加到请求头中。但要注意拦截器的执行顺序以及避免在拦截器中进行复杂的阻塞操作，以免影响客户端性能。另外，对于需要重试的场景，更推荐使用 Spring Retry 等专用框架在拦截器外层或通过ExchangeFilterFunction（如果使用WebClient风格的过滤器）来实现，而不是在拦截器内写循环重试逻辑。

3. 从零到一：RestClient 的完整实操指南

3.1 环境准备与基础依赖

要使用 RestClient，首先确保你的项目是基于 Spring Boot 3.2 或更高版本。如果你是从旧版本升级，需要检查相关依赖的兼容性。对于新项目，直接使用 Spring Initializr 生成即可。

核心依赖就是spring-boot-starter-web，它已经包含了 Spring MVC 和相关的 HTTP 客户端支持。如果你是一个纯 WebFlux 项目（只有spring-boot-starter-webflux），那么默认的同步RestClient可能不可用，你需要额外添加spring-boot-starter-web依赖，或者考虑直接使用WebClient。

Maven 依赖：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>

Gradle 依赖：

implementation 'org.springframework.boot:spring-boot-starter-web'

无需其他特殊依赖。Spring Boot 的自动配置会为我们准备好RestClient.BuilderBean，我们可以直接注入它来创建自定义的RestClient实例。

3.2 四种创建与配置方式详解

根据不同的使用场景，RestClient 提供了多种创建方式，灵活度很高。

方式一：最简创建（适用于临时、简单的请求）

RestClient restClient = RestClient.create();

这种方式创建的客户端没有任何默认配置（如基础 URL、默认头）。适合在方法内部发起一次性的、配置简单的请求。但不推荐作为 Bean 注入，因为缺乏统一配置。

方式二：通过 Builder 创建（推荐，用于定义可复用的客户端）这是最常用、最推荐的方式，尤其是在需要定义多个面向不同服务的客户端时。

import org.springframework.web.client.RestClient; @Configuration public class RestClientConfig { @Bean public RestClient weatherApiClient(RestClient.Builder builder) { return builder .baseUrl("https://api.weather.com/v3") .defaultHeader("api-key", "your-api-key-here") .build(); } @Bean public RestClient internalUserServiceClient(RestClient.Builder builder) { return builder .baseUrl("http://user-service:8081") .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) .requestInterceptor(new RequestIdInterceptor()) .build(); } }

在配置类中，我们可以注入 Spring 自动配置好的RestClient.Builder。这个 Builder 本身可能已经携带了一些全局配置（例如通过application.properties配置的代理）。我们在其基础上，为不同的目标服务添加特定的配置（baseUrl,defaultHeader等），然后build()出独立的RestClientBean。这样，在业务代码中，我们可以通过@Autowired注入weatherApiClient或internalUserServiceClient来使用，代码意图非常清晰。

方式三：自定义全局 Builder（统一修改默认行为）如果你想修改所有通过RestClient.builder()创建的客户端的默认行为，可以自定义一个RestClient.BuilderBean。

@Bean public RestClient.Builder restClientBuilder() { return RestClient.builder() .requestInterceptor(new MetricsInterceptor()) // 全局监控拦截器 .requestFactory(new HttpComponentsClientHttpRequestFactory()); // 切换为 Apache HttpClient }

定义了这个 Bean 后，项目中任何通过RestClient.builder()或注入RestClient.Builder的地方，都会使用你这个经过自定义的 Builder 实例。注意，这会覆盖 Spring Boot 的默认 Builder。

方式四：从 RestTemplate 迁移（平滑升级）如果你有现有的RestTemplateBean，并且已经对其进行了复杂的配置（如自定义转换器、错误处理器），RestClient 提供了一个便捷的迁移路径：

@Bean public RestClient customRestClient(RestTemplate oldRestTemplate) { return RestClient.builder(oldRestTemplate).build(); }

RestClient.builder(RestTemplate)会从RestTemplate中拷贝其配置的ClientHttpRequestFactory、MessageConverter列表等。这是一个快速将旧项目升级到新 API 的桥梁，但长期来看，建议还是按照 RestClient 的方式重新配置，以利用其新特性。

3.3 发起各类 HTTP 请求的代码实录

让我们通过一系列具体的代码示例，看看如何使用 RestClient 完成常见的 HTTP 操作。假设我们有一个UserServiceClientBean，其baseUrl配置为http://localhost:8080/api。

1. GET 请求：获取资源

@Service public class UserService { private final RestClient userRestClient; // 注入配置好的客户端 public UserService(@Qualifier("userServiceClient") RestClient userRestClient) { this.userRestClient = userRestClient; } // 示例1：获取对象，自动反序列化 public User getUserById(Long id) { return userRestClient.get() .uri("/users/{id}", id) // 路径参数 .retrieve() .body(User.class); // 自动转换为User对象 } // 示例2：获取列表 public List<User> getAllUsers() { User[] users = userRestClient.get() .uri("/users") .retrieve() .body(User[].class); // 注意返回数组，或使用 ParameterizedTypeReference return Arrays.asList(users); } // 示例3：带查询参数的GET请求 public List<User> getUsersByCondition(String name, String status) { return List.of(userRestClient.get() .uri(uriBuilder -> uriBuilder .path("/users/search") .queryParam("name", name) .queryParam("active", status) .build()) .retrieve() .body(User[].class)); } }

注意：处理泛型集合当反序列化List<User>这类泛型集合时，直接使用.body(List.class)会丢失泛型信息，导致 Jackson 反序列化失败或类型不安全。正确的做法是使用ParameterizedTypeReference：

List<User> users = restClient.get() .uri("/users") .retrieve() .body(new ParameterizedTypeReference<List<User>>() {});

2. POST 请求：创建资源

public User createUser(UserCreateRequest request) { return userRestClient.post() .uri("/users") .contentType(MediaType.APPLICATION_JSON) .body(request) // 请求体会被自动序列化为JSON .retrieve() .body(User.class); } // 如果不需要响应体，只关心状态码 public void createUserSimple(UserCreateRequest request) { userRestClient.post() .uri("/users") .body(request) .retrieve() .toBodilessEntity(); // 忽略响应体，只返回ResponseEntity<Void> }

3. PUT/PATCH 请求：更新资源

// PUT - 替换整个资源 public User updateUser(Long id, UserUpdateRequest request) { return userRestClient.put() .uri("/users/{id}", id) .body(request) .retrieve() .body(User.class); } // PATCH - 部分更新资源 public void patchUserEmail(Long id, String newEmail) { Map<String, String> patchData = Map.of("email", newEmail); userRestClient.patch() .uri("/users/{id}", id) .body(patchData) .retrieve() .toBodilessEntity(); }

4. DELETE 请求：删除资源

public void deleteUser(Long id) { userRestClient.delete() .uri("/users/{id}", id) .retrieve() .toBodilessEntity(); }

5. 交换模式：获取完整响应实体retrieve()方法是一种高级抽象，方便我们直接获取响应体。但有些时候，我们需要访问响应的状态码、头信息等元数据。这时可以使用exchange方法，它返回一个ClientResponse对象，提供了对 HTTP 响应的完全控制权。

public User getUserWithDetails(Long id) { ClientResponse response = userRestClient.get() .uri("/users/{id}", id) .accept(MediaType.APPLICATION_JSON) .exchange(); // 注意：这里不是retrieve() HttpStatusCode statusCode = response.getStatusCode(); HttpHeaders headers = response.getHeaders(); if (statusCode.is2xxSuccessful()) { return response.body(User.class); } else if (statusCode == HttpStatus.NOT_FOUND) { log.warn("User {} not found. Headers: {}", id, headers); return null; } else { // 处理其他错误，可以读取错误响应体 String errorBody = response.body(String.class); throw new ServiceException("Failed to get user, status: " + statusCode + ", body: " + errorBody); } }

exchange提供了最大的灵活性，但代价是需要手动处理更多细节（如关闭响应资源，虽然ClientResponse通常会自动处理）。对于大多数常见场景，retrieve()配合onStatus的错误处理已经足够优雅和简洁。

4. 高级特性与生产级应用实践

4.1 拦截器实战：实现统一认证与日志

拦截器是 RestClient 实现横切关注点的核心组件。让我们实现两个实用的拦截器。

1. 认证拦截器：自动注入 JWT Token假设我们的系统使用 JWT 进行服务间认证，Token 存储在SecurityContext或ThreadLocal中。

@Component public class JwtTokenInterceptor implements ClientHttpRequestInterceptor { @Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { // 从安全上下文或自定义Holder中获取当前令牌 String token = SecurityContextHolder.getContext().getAuthentication() != null ? SecurityContextHolder.getContext().getAuthentication().getCredentials().toString() : TokenHolder.getCurrentToken(); if (token != null && !token.isBlank()) { request.getHeaders().setBearerAuth(token); // 便捷方法，等同于 set("Authorization", "Bearer " + token) } // 添加请求ID用于链路追踪 request.getHeaders().set("X-Request-ID", UUID.randomUUID().toString()); // 继续执行请求链 return execution.execute(request, body); } }

然后在配置RestClient时添加这个拦截器：.requestInterceptor(new JwtTokenInterceptor())。这样，所有通过该客户端发起的请求都会自动携带认证令牌，无需在每个调用处重复设置。

2. 日志与监控拦截器

@Component @Slf4j public class LoggingMetricsInterceptor implements ClientHttpRequestInterceptor { @Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { String requestId = request.getHeaders().getFirst("X-Request-ID"); String method = request.getMethod().name(); String uri = request.getURI().toString(); long startTime = System.currentTimeMillis(); log.debug("Outgoing request [{}]: {} {}", requestId, method, uri); try { ClientHttpResponse response = execution.execute(request, body); long duration = System.currentTimeMillis() - startTime; log.debug("Received response [{}]: Status {} in {} ms", requestId, response.getStatusCode(), duration); // 可以在这里记录指标，例如发送到Micrometer Metrics.counter("http.client.requests", "method", method, "uri", uri, "status", String.valueOf(response.getStatusCode().value())) .increment(); return response; } catch (IOException e) { long duration = System.currentTimeMillis() - startTime; log.error("Request failed [{}]: {} {} after {} ms", requestId, method, uri, duration, e); Metrics.counter("http.client.errors", "method", method, "uri", uri, "exception", e.getClass().getSimpleName()) .increment(); throw e; } } }

这个拦截器记录了请求的耗时、状态，并集成监控指标。注意，拦截器的执行顺序很重要，通常认证拦截器应该在日志拦截器之前执行，以确保日志能记录到完整的请求头信息。

4.2 消息转换器：处理非 JSON 数据

虽然 JSON 是主流，但有时我们仍需处理 XML、表单数据或自定义格式。RestClient 通过HttpMessageConverter来处理这些转换。

1. 发送表单数据

public void login(String username, String password) { // 方式一：使用 MultiValueMap MultiValueMap<String, String> formData = new LinkedMultiValueMap<>(); formData.add("username", username); formData.add("password", password); String result = restClient.post() .uri("/login") .contentType(MediaType.APPLICATION_FORM_URLENCODED) .body(formData) .retrieve() .body(String.class); // 方式二：使用字符串拼接（简单场景） // String formBody = "username=" + URLEncoder.encode(username) + "&password=" + URLEncoder.encode(password); // .contentType(MediaType.APPLICATION_FORM_URLENCODED) // .body(formBody) }

Spring 默认配置了FormHttpMessageConverter来处理application/x-www-form-urlencoded数据。

2. 发送 Multipart 文件

public void uploadProfilePicture(Long userId, MultipartFile file) throws IOException { // 构建 multipart 数据 MultiValueMap<String, Object> parts = new LinkedMultiValueMap<>(); parts.add("file", new ByteArrayResource(file.getBytes()) { @Override public String getFilename() { return file.getOriginalFilename(); } }); parts.add("userId", userId); restClient.post() .uri("/users/{id}/avatar", userId) .contentType(MediaType.MULTIPART_FORM_DATA) .body(parts) .retrieve() .toBodilessEntity(); }

这里利用了ByteArrayResource并重写getFilename()方法来构建文件部分。Spring 的MultipartHttpMessageConverter会处理这种格式。

3. 自定义消息转换器假设你需要和一个老系统通信，它使用 XML。

@Configuration public class RestClientConfig { @Bean public RestClient xmlServiceClient(RestClient.Builder builder) { // 创建支持XML的转换器 MarshallingHttpMessageConverter xmlConverter = new MarshallingHttpMessageConverter(); Jaxb2Marshaller marshaller = new Jaxb2Marshaller(); marshaller.setPackagesToScan("com.example.xml.model"); // 你的XML模型类包 xmlConverter.setMarshaller(marshaller); xmlConverter.setUnmarshaller(marshaller); return builder .baseUrl("http://legacy-system/api") .messageConverters(converters -> { converters.add(0, xmlConverter); // 添加到列表开头，优先于JSON转换器 // 也可以完全替换 converters.clear(); converters.add(xmlConverter); }) .defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_XML_VALUE) .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_XML_VALUE) .build(); } }

这样，使用xmlServiceClient发起的请求，其Accept和Content-Type头都会是 XML，并且序列化/反序列化会使用 JAXB。

4.3 连接池与超时配置：性能调优要点

默认情况下，RestClient 使用 JDK 自带的HttpClient，其连接池行为由系统属性控制。在生产环境中，我们通常需要更精细的控制。

通过application.yml配置全局 HTTP 客户端属性：

spring: application: name: my-service # 这些配置会影响通过 RestClient.builder() 创建的客户端底层使用的 HttpClient http: client: connect-timeout: 2s # 建立TCP连接的超时时间 read-timeout: 5s # 从服务器读取数据的超时时间 write-timeout: 5s # 向服务器发送数据的超时时间（JDK HttpClient支持） connection-timeout: 500ms # 从连接池获取连接的超时时间 max-connections: 200 # 连接池最大总连接数 max-connections-per-route: 50 # 到每个目标主机的最大连接数 keep-alive: 30s # 空闲连接的存活时间 compression: on # 是否启用压缩（gzip/deflate） # 代理配置（根据实际需要） # proxy: # host: proxy.example.com # port: 8080 # username: user # password: pass # non-proxy-hosts: localhost|127.*|[::1]

这些配置属性会被 Spring Boot 的HttpClientAutoConfiguration捕获，并应用到自动配置的HttpClientBean 上，进而影响所有基于此HttpClient的RestClient实例。

为特定客户端配置独立的超时如果需要对某个特定的下游服务设置不同的超时，你需要自定义ClientHttpRequestFactory。

@Bean public RestClient slowExternalServiceClient() { // 使用HttpComponentsClientHttpRequestFactory（需要引入Apache HttpClient依赖） HttpClient httpClient = HttpClientBuilder.create() .setMaxConnTotal(100) .setMaxConnPerRoute(20) .setConnectionTimeToLive(30, TimeUnit.SECONDS) .setDefaultRequestConfig(RequestConfig.custom() .setConnectTimeout(5000) // 5秒连接超时 .setSocketTimeout(30000) // 30秒读写超时 .build()) .build(); HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(httpClient); return RestClient.builder() .baseUrl("http://very-slow-external-api.com") .requestFactory(factory) .build(); }

重要提示：超时策略

• connect-timeout：设置过短可能导致网络波动时连接失败。对于内网服务，1-2秒足够；对于公网API，可以考虑3-5秒。
• read-timeout：这是最重要的超时之一。必须根据下游服务的 SLA（服务等级协议）来设置。例如，一个快速查询接口可设为1-2秒，一个批处理接口可能需要30秒或更长。永远不要不设置读超时，否则一个慢响应或挂起的连接会永久占用你的线程池资源，导致应用雪崩。
• 连接池大小（max-connections,max-connections-per-route）需要根据应用的并发量和下游服务的承受能力来调整。一个通用的起始公式是：max-connections-per-route = 并发线程数 * 2。监控客户端的连接池使用情况是关键。

5. 常见问题、性能调优与迁移指南

5.1 高频问题排查手册

在实际使用 RestClient 时，你可能会遇到以下典型问题。这里提供一个快速排查指南。

5.2 从 RestTemplate 平滑迁移的策略

如果你有一个正在使用RestTemplate的大型项目，全面迁移到RestClient可能需要一个渐进的过程。

策略一：并行运行，逐步替换这是风险最低的策略。不要一次性替换所有RestTemplate代码。

1. 引入依赖：确保升级到 Spring Boot 3.2+。
2. 创建新客户端：为新的服务调用或模块，直接使用RestClient进行开发。
3. 旧代码迁移：当需要修改或重构某个使用了RestTemplate的旧类时，顺便将其迁移到RestClient。可以借助RestClient.builder(oldRestTemplate)来快速创建一个行为一致的客户端，减少配置迁移成本。
4. 最终清理：当所有相关代码都迁移完毕后，删除旧的RestTemplateBean 定义和相关配置。

策略二：创建适配器层如果项目结构清晰，可以创建一个“HTTP 客户端门面”或适配器接口。

public interface ApiClient { <T> T getForObject(String url, Class<T> responseType, Object... uriVariables); // ... 其他方法 } // 旧实现，委托给RestTemplate @Service @Primary // 初始阶段使用此实现 @ConditionalOnProperty(name = "http.client.impl", havingValue = "rest-template", matchIfMissing = true) public class RestTemplateApiClient implements ApiClient { private final RestTemplate restTemplate; // 实现方法... } // 新实现，使用RestClient @Service @ConditionalOnProperty(name = "http.client.impl", havingValue = "rest-client") public class RestClientApiClient implements ApiClient { private final RestClient restClient; // 实现方法... }

这样，业务代码依赖于ApiClient接口。通过一个配置开关（如http.client.impl），可以在不修改业务代码的情况下，在RestTemplate和RestClient之间切换，实现平滑迁移和回滚。

迁移注意事项：

• 错误处理：RestTemplate默认抛异常，RestClient的retrieve()也需要配置onStatus或使用exchange来达到类似效果。这是迁移时需要重点修改的部分。
• URI 构建：RestClient的uri()方法更灵活，支持String模板和UriBuilder。迁移时注意路径参数和查询参数的写法变化。
• 响应类型：处理List<T>等泛型集合时，RestClient需要使用ParameterizedTypeReference，而RestTemplate有专用的ParameterizedTypeReference参数重载方法，概念一致但 API 略有不同。

5.3 性能监控与最佳实践

将 RestClient 用于生产环境，监控是必不可少的。

1. 启用 Micrometer 指标如果你使用了 Spring Boot Actuator 和 Micrometer（例如与 Prometheus 集成），RestClient 的指标会自动通过RestClient.Builder的observationRegistry集成。确保你的配置中包含了相关依赖：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-registry-prometheus</artifactId> </dependency>

然后在application.yml中启用指标：

management: endpoints: web: exposure: include: metrics,prometheus metrics: tags: application: ${spring.application.name}

你可以在/actuator/metrics/http.client.requests端点看到 HTTP 客户端的详细指标，包括请求数量、耗时、状态码分布等。

2. 连接池监控如果使用 Apache HttpClient 作为底层实现，可以暴露其连接池指标到 Micrometer。

@Bean public MeterBinder httpClientMetrics(HttpClient httpClient) { return new HttpClientMetrics(httpClient, "my-http-client"); }

3. 日志记录为org.springframework.web.client设置DEBUG级别日志，可以在开发阶段看到详细的请求和响应信息，包括头信息和体（注意敏感信息）。在生产环境，建议设置为WARN或ERROR，并结合拦截器记录摘要日志和错误。

最佳实践总结：

• 为每个下游服务创建独立的客户端 Bean：配置不同的超时、重试和拦截策略。
• 合理设置超时：连接超时、读超时、写超时必须根据网络环境和下游服务 SLA 明确设置。
• 使用连接池：并监控其使用情况，避免连接泄漏或耗尽。
• 实现统一的拦截器：用于认证、链路追踪、日志和监控。
• 精细化错误处理：利用onStatus将不同的 HTTP 错误状态映射到不同的业务异常。
• 监控告警：对客户端错误率、延迟、超时率设置监控告警。
• 考虑重试机制：对于网络抖动或下游服务瞬时故障，可以在拦截器层或使用 Spring Retry 实现有策略的重试（注意幂等性）。

从我个人的迁移和使用体验来看，RestClient 带来的代码清晰度和可维护性的提升是巨大的。它用一种更现代、更符合直觉的方式，解决了我们日常开发中高频的 HTTP 通信需求。虽然初期需要一点学习成本来熟悉其 API 和配置方式，但一旦上手，你就会发现它几乎能优雅地处理所有场景。对于新项目，毫无疑问应该直接采用 RestClient；对于老项目，制定一个渐进式的迁移计划，逐步享受它带来的便利，是完全值得的。