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 定义接口
java
import org.springframework.web.service.annotation.GetExchange;
import org.springframework.web.service.annotation.HttpExchange;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestParam;
@HttpExchange(url = "/api")
public interface TodoClient {
@GetExchange("/todos/{id}")
Todo getTodo(@PathVariable("id") long id);
@GetExchange("/todos")
List<Todo> list(@RequestParam("owner") String owner);
}Spring 文档明确：@HttpExchange 可放在类型上做统一配置，方法上用 @GetExchange / @PatchExchange ... 补齐具体动作；方法参数支持 @PathVariable、@RequestHeader、@RequestParam 等。(Home)
3.2 生成代理（以 RestClient 为底座，同步）
java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestClient;
import org.springframework.web.client.support.RestClientAdapter;
import org.springframework.web.service.invoker.HttpServiceProxyFactory;
@Configuration
public class ClientConfig {
@Bean
public TodoClient todoClient() {
RestClient restClient = RestClient.builder()
.baseUrl("https://example.com")
.defaultHeader("Accept", "application/json")
.build();
HttpServiceProxyFactory factory =
HttpServiceProxyFactory.builderFor(RestClientAdapter.create(restClient)).build();
return factory.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>>等
有个实用补充：RestClientAdapter 还额外支持 InputStream 或 ResponseEntity<InputStream>，适合下载类场景。(Home)
5. 全局错误处理：别在业务里到处 try/catch
默认 4xx/5xx 会抛异常，但你可以在底层客户端统一定制：
RestClient.Builder.defaultStatusHandler(...)WebClient.Builder.defaultStatusHandler(...)RestTemplate.setErrorHandler(...)
文档还给了示例代码框架（推荐你把异常映射做在这里，业务层就干净了）。(Home)
另外，如果你希望"404 不算异常，直接返回空对象/NOT_FOUND"，还可以通过 adapter decorator 做统一策略（文档提供了现成装饰器思路）。(Home)
6. 规模化：接口多了之后，用 Group + Registry 管起来（Spring 7）
当你接入多个外部系统（比如 GitHub、支付、短信、ERP），如果还按"一个接口写一个 @Bean createClient"，配置会爆炸。Spring 7 引入了 HTTP Service Registry ：按 group 组织接口，框架自动生成代理并注册为 Bean。(Home)
6.1 用 @ImportHttpServices 声明分组（自动注册代理 Bean）
@ImportHttpServices 是 Spring 7 新增（javadoc 标注 Since: 7.0），支持 types 手动列出接口或按包扫描。(Home)
6.2 每个 group 统一配置底层客户端
Spring 文档给出 HttpServiceGroupConfigurer 的使用方式：你可以按 group 名字定制 clientBuilder，也可以对所有 group 做统一处理。(Home)
更关键的是：Spring Boot 还能基于 group 注入"按组的客户端配置属性"；Spring Security 可以加 OAuth；Spring Cloud 可以加负载均衡。(Home)
如果同一接口在多个 group 里各有一份代理（比如两个不同环境/不同租户的 host），你还可以直接从 HttpServiceProxyRegistry 按 group 拿到指定代理。(Home)
7. 测试怎么做
如果你底层用 RestClient，Spring 官方明确提到：可以通过 MockRestServiceServer 来测试它的使用方式。(Home)
工程上常见做法是：
- 单元测试：mock 接口代理（因为它就是个接口）
- 集成测试：MockRestServiceServer / WireMock（把外部服务模拟出来）
- 契约测试：把接口当"调用契约"，配合服务端的实现做回归验证（尤其适合内部微服务）