当前位置：首页 > news >正文

Spring 新声明式 HTTP 客户端：HTTP Interface + RestClient，把“调用外部 API”写成接口

news 2026/5/12 16:56:31

1. 核心概念：HTTP Service Clients（HTTP Interface）

它的本质是两件事：(Home)

用接口定义“我要调用的 HTTP API”（方法上标注@GetExchange等）
用HttpServiceProxyFactory基于底层 HTTP 客户端（RestClient/WebClient/RestTemplate）生成代理对象

额外有个很实用的点：如果这个 API 是你们自己的服务，服务端的@Controller甚至可以实现同一份接口，做到“契约复用”。(Home)

2. 版本关系：6、6.1、7 分别带来了什么

Spring 6：引入接口式的@HttpExchange声明调用能力(Home)
Spring 6.1：引入RestClient（新的同步 HTTP 客户端），API 风格像WebClient，底层复用RestTemplate的 converters、拦截器等基础设施(Home)
Spring 7：为了解决“接口多了以后 Bean 配置很重复”的问题，加入Registry + 分组（group）的配置模型，并提供@ImportHttpServices自动注册代理 Bean(Home)

3. 最小闭环：写一个接口 + 生成代理（Spring 6+ 都能用）

3.1 定义接口

importorg.springframework.web.service.annotation.GetExchange;importorg.springframework.web.service.annotation.HttpExchange;importorg.springframework.web.bind.annotation.PathVariable;importorg.springframework.web.bind.annotation.RequestParam;@HttpExchange(url="/api")publicinterfaceTodoClient{@GetExchange("/todos/{id}")TodogetTodo(@PathVariable("id")longid);@GetExchange("/todos")List<Todo>list(@RequestParam("owner")Stringowner);}

Spring 文档明确：@HttpExchange可放在类型上做统一配置，方法上用@GetExchange / @PatchExchange ...补齐具体动作；方法参数支持@PathVariable、@RequestHeader、@RequestParam等。(Home)

3.2 生成代理（以 RestClient 为底座，同步）

importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importorg.springframework.web.client.RestClient;importorg.springframework.web.client.support.RestClientAdapter;importorg.springframework.web.service.invoker.HttpServiceProxyFactory;@ConfigurationpublicclassClientConfig{@BeanpublicTodoClienttodoClient(){RestClientrestClient=RestClient.builder().baseUrl("https://example.com").defaultHeader("Accept","application/json").build();HttpServiceProxyFactoryfactory=HttpServiceProxyFactory.builderFor(RestClientAdapter.create(restClient)).build();returnfactory.createClient(TodoClient.class);}}

这就是官方给出的标准套路：RestClientAdapter/WebClientAdapter/RestTemplateAdapter+HttpServiceProxyFactory。(Home)

4. 返回值怎么选：同步 or 响应式，一眼看懂

Spring 文档对“返回值支持哪些类型”给了一个非常清晰的表：(Home)

当底层是RestClient / RestTemplate（同步）时，你可以返回：
- T（直接反序列化成对象）
- ResponseEntity<T>（要状态码、头、body）
- HttpHeaders、void等
当底层是WebClient时，除了上面的同步返回，还支持响应式：Mono<T>、Flux<T>、Mono<ResponseEntity<T>>等