Spring HTTP客户端：OpenFeign、HTTP Interface、RestClient与WebClient

微服务之间做同步调用时，常见选择不只有OpenFeign。存量系统里常见RestTemplate和OpenFeign；Java 17 + Spring Boot 3.x新项目里还会遇到HTTP Interface、RestClient和WebClient。它们写法不同，但本质都绕不开同一件事：

把一次Java方法调用或客户端API调用，转换成HTTP请求，再经过服务发现、负载均衡、连接池、超时、重试、熔断、编解码和错误处理。

阅读入口：先选编程模型，再看共同执行链

按“阻塞/响应式选择 → 请求构造 → 服务名解析 → 连接池与超时 → 响应解码 → 排障”阅读。不要把 WebClient 当成自动提速开关，也不要跳过总 Deadline 和连接池等待。

本页解决“到底该用哪个、怎么工作、不这样会怎样、生产如何配置和排查”。OpenFeign更深源码见OpenFeign内部原理，负载均衡见LoadBalancer内部原理，端到端链路见Spring Cloud服务调用链路。

核心原理：代理只是入口，真正执行的是客户端适配链

OpenFeign/HTTP Interface 先把接口方法解析成请求模板，RestClient/RestTemplate 通过命令式 API 构造请求，WebClient 则把请求组装成响应式 Publisher。随后所有实现都会进入服务名解析、LoadBalancer 选实例、连接池建连、编解码和错误映射这条链路。

mermaid

flowchart TD
    A["Java方法或HTTP Interface"] --> B["代理/Builder解析参数"]
    B --> C["RequestTemplate或Request"]
    C --> D["服务名解析与DiscoveryClient"]
    D --> E["LoadBalancer选择实例"]
    E --> F["连接池获取连接"]
    F --> G["HTTP Client发送请求"]
    G --> H["状态码判断与Decoder"]
    H --> I["DTO/Mono响应或统一异常"]

客户端类型改变的是编程模型和线程模型，不会消除网络的不确定性；连接超时、读取超时、连接池等待和总 Deadline 仍需分别设置。

一、学习目标

学完本页应能回答：

RestTemplate、RestClient、WebClient、HTTP Interface和OpenFeign分别是什么。
为什么“客户端API”不等于“真正发请求的HTTP实现”。
阻塞调用和响应式调用在线程模型上的差异。
@HttpExchange接口怎样变成代理对象。
为什么Boot 2存量项目不能直接复制Boot 3示例。
服务名怎样通过LoadBalancer变成真实IP:Port。
连接超时、读取超时、连接池等待、总Deadline有什么区别。
写请求超时为什么不能盲目重试。
商业项目中订单、资产、采集、权限系统如何选择客户端。
线上调用慢、无实例、401/403、序列化失败怎样排查。

二、版本边界：JDK 8和Java 17+要分开看

技术	JDK 8 + Boot 2.7常见情况	Java 17 + Boot 3.x常见情况	说明
RestTemplate	大量存量系统仍使用	仍可用，但新代码通常不优先扩写	阻塞客户端模板，成熟但API较老
OpenFeign	微服务声明式HTTP主力	仍广泛使用	Spring Cloud生态集成成熟
WebClient	可用，但常需要引入WebFlux理解响应式	仍是响应式主力	非阻塞、流式、高并发更合适
RestClient	Boot 2没有主线支持	Spring 6.1后常见	阻塞风格，API比RestTemplate现代
HTTP Interface	Boot 2不是主线	Spring 6后常见	`@HttpExchange`声明式接口代理

不要把Java 17示例里的record、var、Lambda高级写法和Boot 3配置直接复制到JDK 8项目。JDK 8项目最稳妥的是OpenFeign、RestTemplate或WebClient；现代项目可同时了解OpenFeign、HTTP Interface、RestClient和WebClient。

三、先建立统一心智模型

mermaid

flowchart TD
    A["业务代码发起调用"] --> B["客户端抽象<br/>Feign、RestClient、WebClient、HTTP Interface"]
    B --> C["构造HTTP请求<br/>方法、路径、Header、Body"]
    C --> D["服务发现和LoadBalancer"]
    D --> E["得到真实IP和端口"]
    E --> F["底层HTTP Client"]
    F --> G["连接池、TCP、TLS、发送请求"]
    G --> H["下游服务处理"]
    H --> I["响应解码和错误映射"]

几个角色要拆开：

层	负责什么	典型对象
声明或调用API	让业务代码表达“我要调哪个接口”	OpenFeign接口、`RestClient`、`WebClient`、`@HttpExchange`接口
请求构造	拼URL、Header、Query、Body、Content-Type	Encoder、MessageConverter、BodyInserter
服务发现	按服务名获得实例列表	Nacos、Eureka、Consul、Kubernetes
负载均衡	从候选实例中选一个	Spring Cloud LoadBalancer
网络传输	DNS、连接池、TCP、TLS、HTTP收发	Apache HC5、OkHttp、JDK HttpClient、Reactor Netty
响应处理	状态码、反序列化、异常映射	Decoder、ErrorDecoder、ResponseSpec

面试里不要说“Feign从Nacos拿地址后发请求”就结束。更准确是：Feign或HTTP Interface负责代理和请求模板；Nacos提供本地实例快照；LoadBalancer选实例；底层HTTP Client真正发网络请求。

四、几个客户端怎么选

客户端	编程风格	优点	风险	适合场景
OpenFeign	声明式接口	Spring Cloud集成成熟，代码简洁	容易把远程调用误当本地调用	服务间标准HTTP调用
HTTP Interface	声明式接口	Spring原生声明式HTTP，和`RestClient`/`WebClient`适配	生态治理能力要自己组合	Boot 3新项目、轻量声明式调用
RestClient	阻塞流式API	比RestTemplate更现代，适合MVC阻塞项目	不自动获得微服务治理，需明确配置	内部HTTP、第三方API、同步查询
WebClient	响应式非阻塞	适合高并发、SSE、流式、WebFlux	阻塞代码混入会拖垮EventLoop	网关、流式接口、高并发聚合
RestTemplate	阻塞模板	存量多、简单直接	API老，扩展风格不如新客户端	维护旧系统，不建议新项目大量新增

选择原则：

已经是Spring Cloud OpenFeign体系，继续用OpenFeign最稳，重点补超时、连接池、错误语义和观测。
Boot 3新项目如果只需要轻量HTTP声明式接口，可以评估HTTP Interface。
MVC阻塞项目调用第三方HTTP接口，RestClient比手写Apache Client更统一。
Gateway、WebFlux项目、SSE和流式接口优先WebClient。
不要为了“新”把所有Feign重写成HTTP Interface。迁移要看治理能力、超时、重试、熔断、指标和团队熟悉度。

五、HTTP Interface怎样工作

HTTP Interface使用@HttpExchange、@GetExchange、@PostExchange等注解描述远程HTTP接口，然后通过HttpServiceProxyFactory创建代理。它的思想和Feign相似：启动时解析接口，运行时代理把方法调用变成HTTP请求。

mermaid

flowchart TD
    A["定义HttpExchange接口"] --> B["HttpServiceProxyFactory创建代理"]
    B --> C["方法调用被代理拦截"]
    C --> D["注解和参数生成HTTP请求"]
    D --> E["RestClient或WebClient Adapter执行"]
    E --> F["响应转换为Java对象"]

Java 17 + Boot 3示例：

java

import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.service.annotation.GetExchange;
import org.springframework.web.service.annotation.HttpExchange;

@HttpExchange("/users")
public interface UserHttpApi {

    @GetExchange("/{id}")
    UserDTO findById(@PathVariable Long id);
}

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 UserHttpApiConfig {

    @Bean
    public UserHttpApi userHttpApi(RestClient.Builder builder) {
        RestClient restClient = builder
                .baseUrl("http://user-service")
                .build();

        HttpServiceProxyFactory factory = HttpServiceProxyFactory
                .builderFor(RestClientAdapter.create(restClient))
                .build();

        return factory.createClient(UserHttpApi.class);
    }
}

这段代码重点不是“能不能调通”，而是理解代理链：接口本身没有实现类，HttpServiceProxyFactory创建代理；代理调用RestClient或WebClient；真正发请求的仍是底层HTTP客户端。

如果要接入服务发现和负载均衡，不能只写http://user-service就假设一定生效。需要按项目版本配置支持LoadBalancer的客户端构建器，或使用已经集成LoadBalancer的调用方式。否则user-service可能被当成普通DNS主机名解析，直接失败。

六、RestClient适合什么

RestClient是阻塞式HTTP客户端API，适合Spring MVC阻塞线程模型。它比RestTemplate链式写法更清晰。

java

UserDTO user = restClient.get()
        .uri("/users/{id}", 1001L)
        .retrieve()
        .body(UserDTO.class);

它适合：

场景	原因
调第三方HTTP接口	不一定需要Feign接口和服务发现
后台管理系统同步查询	阻塞模型简单，易理解
Boot 3新项目轻量客户端	API比RestTemplate现代

但它不会自动替你处理所有微服务治理问题。你仍然要配置：

连接超时、读取超时、连接池。
统一Header，例如Trace、Token、租户。
错误状态码映射。
指标和Tracing。
幂等键和写请求超时后的事实查询。

七、WebClient为什么不是“更快的RestTemplate”

WebClient基于响应式模型，默认常见底层是Reactor Netty。它的优势不是让单个请求魔法般变快，而是用少量线程管理大量I/O等待。

mermaid

flowchart TD
    A["请求发起"] --> B["注册异步回调"]
    B --> C["EventLoop负责网络读写"]
    C --> D["响应到达触发后续处理"]
    D --> E["业务链继续执行"]

危险点：在EventLoop上执行阻塞代码。

java

webClient.get()
        .uri("/users/{id}", id)
        .retrieve()
        .bodyToMono(UserDTO.class)
        .map(user -> blockingRepository.save(user)); // 错误：阻塞DB操作混入响应式链

如果确实要调用阻塞库，要切换到有界调度器并控制并发：

java

webClient.get()
        .uri("/users/{id}", id)
        .retrieve()
        .bodyToMono(UserDTO.class)
        .publishOn(Schedulers.boundedElastic())
        .map(user -> blockingRepository.save(user));

这只是把阻塞从EventLoop隔离出去，不代表下游数据库容量变大。高并发聚合接口仍要限制并发、设置超时、熔断和总Deadline。

八、JDK 8 Demo：RestTemplate调用必须带超时和错误语义

JDK 8存量项目里常见RestTemplate。下面示例演示两个原则：远程调用必须有超时；写请求超时后不能直接认定失败。

java

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.web.client.ResourceAccessException;
import org.springframework.web.client.RestTemplate;

public class InventoryClient {

    private final RestTemplate restTemplate;

    public InventoryClient() {
        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
        factory.setConnectTimeout(800);
        factory.setReadTimeout(1500);
        this.restTemplate = new RestTemplate(factory);
    }

    public ReserveResult reserve(String baseUrl, String orderId, String skuId, int quantity) {
        String idempotencyKey = "reserve:" + orderId;
        ReserveRequest body = new ReserveRequest(orderId, skuId, quantity);

        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("Idempotency-Key", idempotencyKey);

        try {
            ResponseEntity<ReserveResult> response = restTemplate.postForEntity(
                    baseUrl + "/inventory/reserve",
                    new HttpEntity<ReserveRequest>(body, headers),
                    ReserveResult.class);
            return response.getBody();
        } catch (ResourceAccessException timeoutOrNetworkError) {
            return queryReserveResult(baseUrl, idempotencyKey);
        }
    }

    private ReserveResult queryReserveResult(String baseUrl, String idempotencyKey) {
        return restTemplate.getForObject(
                baseUrl + "/inventory/reserve-result?key={key}",
                ReserveResult.class,
                idempotencyKey);
    }

    static class ReserveRequest {
        public String orderId;
        public String skuId;
        public int quantity;

        ReserveRequest(String orderId, String skuId, int quantity) {
            this.orderId = orderId;
            this.skuId = skuId;
            this.quantity = quantity;
        }
    }

    static class ReserveResult {
        public String status;
        public String message;
    }
}

这个Demo没有引入连接池，只为了让JDK 8小白理解超时和幂等键。生产项目应使用连接池HTTP客户端，并监控每路由连接数、租借等待、连接年龄、错误率和P95/P99。

九、超时、连接池和Deadline怎么设计

一次HTTP调用不只有一个超时：

阶段	含义	常见现象
连接池等待	等本地空闲连接	请求可能还没发出去
DNS解析	域名变IP	DNS慢或缓存异常
Connect Timeout	建立TCP连接	目标不可达、防火墙、实例异常
TLS握手	HTTPS协商	证书、协议、加密套件问题
Write Timeout	写请求体	大Body、网络慢
Read/Response Timeout	等响应或读取响应	下游慢、DB慢、锁等待
总Deadline	整个业务调用预算	防止多层重试超过入口SLO

mermaid

flowchart TD
    A["入口总Deadline 3s"] --> B["本服务处理 300ms"]
    B --> C["调用用户服务 700ms"]
    C --> D["调用库存服务 1000ms"]
    D --> E["保留响应和降级预算 1000ms"]

不要每一层都配置完整5秒。A调B给5秒，B调C也给5秒，C调D还给5秒，用户早就超时了，下游却还在继续执行，最终形成线程堆积和幽灵流量。

十、商业项目怎么用

场景	推荐思路
订单服务查用户资料	OpenFeign或HTTP Interface，短超时，可有限重试
下单扣库存	OpenFeign，必须幂等键、状态查询、补偿，不盲目重试
医疗采集调用医院接口	RestClient或Feign，按医院配置超时、限流、熔断和审计
Gateway聚合多个查询	WebClient并发聚合，限制并发和总Deadline
审计日志上报	优先MQ异步，HTTP失败不能阻塞主交易太久
权限服务校验	同步调用要短超时，可缓存权限摘要，但高风险操作实时校验

十一、生产排查Runbook

11.1 调用慢

先用Trace确认慢在调用方、Gateway、网络、下游还是数据库。
看客户端阶段耗时：连接池等待、Connect、TLS、首字节、读取、解码。
看是否多层重试导致逻辑一次、物理多次。
看下游实例分布，确认是否命中慢实例或旧实例。
看线程池、连接池、CPU、GC、DB连接池和慢SQL。

11.2 无实例或调旧实例

查服务名、namespace、group、cluster、metadata。
查注册中心事实和调用方本地快照。
查LoadBalancer缓存和过滤链。
查HTTP连接池是否复用旧连接。
查Readiness、preStop和优雅下线时间线。

11.3 401/403

401先查Token是否携带、过期、签名、iss、aud、kid。
Gateway过、下游401，重点查Authorization是否透传和下游issuer/audience配置。
403查scope、角色、权限码、方法注解和数据权限。
权限刚变更，查JWT权限快照、token_version和权限缓存。

11.4 序列化失败

查Content-Type、请求体、响应体是否符合契约。
查DTO字段是否兼容，日期格式是否变化。
查错误响应是否被当成成功DTO解码。
不要跨服务直接传JPA Entity。

十二、面试标准回答

Spring里HTTP客户端怎么选？

text

存量JDK 8和Boot 2系统里常见OpenFeign和RestTemplate；Java 17、Boot 3新项目还可以使用
HTTP Interface、RestClient和WebClient。OpenFeign适合Spring Cloud服务间声明式调用；
HTTP Interface是Spring原生声明式HTTP接口；RestClient是阻塞式现代客户端；WebClient是响应式
非阻塞客户端，适合Gateway、WebFlux、流式和高并发聚合。无论选哪个，真正发请求的都是底层HTTP
Client，都要处理服务发现、负载均衡、连接池、超时、重试、熔断、编解码、错误语义和观测。

HTTP Interface和OpenFeign有什么区别？

text

二者都能用接口描述HTTP调用并创建代理。OpenFeign属于Spring Cloud OpenFeign生态，和Nacos、
LoadBalancer、配置、Fallback等微服务治理集成更成熟；HTTP Interface是Spring Framework原生能力，
通过HttpServiceProxyFactory基于RestClient或WebClient创建代理，更轻量，但服务发现、熔断、
错误映射和观测要按项目组合清楚。不能只看注解相似就认为生产治理能力完全一样。

JDK 8/11/17/21 LTS演进

线程池

Spring HTTP客户端：OpenFeign、HTTP Interface、RestClient与WebClient ​

阅读入口：先选编程模型，再看共同执行链 ​

核心原理：代理只是入口，真正执行的是客户端适配链 ​

一、学习目标 ​

二、版本边界：JDK 8和Java 17+要分开看 ​

三、先建立统一心智模型 ​

四、几个客户端怎么选 ​

五、HTTP Interface怎样工作 ​

六、RestClient适合什么 ​

七、WebClient为什么不是“更快的RestTemplate” ​

八、JDK 8 Demo：RestTemplate调用必须带超时和错误语义 ​

九、超时、连接池和Deadline怎么设计 ​

十、商业项目怎么用 ​

十一、生产排查Runbook ​

11.1 调用慢 ​

11.2 无实例或调旧实例 ​

11.3 401/403 ​

11.4 序列化失败 ​

十二、面试标准回答 ​

关联学习 ​

Spring HTTP客户端：OpenFeign、HTTP Interface、RestClient与WebClient

阅读入口：先选编程模型，再看共同执行链

核心原理：代理只是入口，真正执行的是客户端适配链

一、学习目标

二、版本边界：JDK 8和Java 17+要分开看

三、先建立统一心智模型

四、几个客户端怎么选

五、HTTP Interface怎样工作

六、RestClient适合什么

七、WebClient为什么不是“更快的RestTemplate”

八、JDK 8 Demo：RestTemplate调用必须带超时和错误语义

九、超时、连接池和Deadline怎么设计

十、商业项目怎么用

十一、生产排查Runbook

11.1 调用慢

11.2 无实例或调旧实例

11.3 401/403

11.4 序列化失败

十二、面试标准回答

关联学习