去年给一个老项目接第三方物流接口时我翻遍了代码仓库发现同一个外部系统的对接代码居然混着四种风格有的在 Service 里用String.format拼 URL有的从RestTemplate里拿ResponseEntityMap再手动 get 字段还有几个走WebClient的异步调用剩下的是交给FeignClient的接口。当时我就想Spring 官方能不能像 Feign 那样让我直接定义一个 Java 接口加几个注解剩下的请求构造、序列化、错误处理全部交给框架这个愿望在 Spring 6.1 之后真的实现了——HTTP Interface加上RestClient把调用外部 API这件事做成了纯声明式。这篇东西我会完整讲清楚这套新组合是什么、怎么用以及我在真实项目里踩过的坑。1. 换了三任HTTP 客户端之后Spring 终于把声明式接口收编了1.1 RestTemplate 到 WebClient 再到 RestClient这次演进到底解决了什么大部分老 Spring 开发者对RestTemplate都不陌生。它的 API 看起来简单但实际业务代码里很容易变成一堆ResponseEntityMap、手动get(data)、JSONObject拆字段的操作。一个接口对接要写三四十行同一个请求逻辑换个路径又要复制三四十行。更要命的是RestTemplate 在 5.0 之后被官方打入维护模式虽然还能用但团队再在新项目里大面积使用它基本是在给后人留债。WebClient是 Spring 5 推出的响应式客户端能力确实强异步、流式、背压都有但问题也跟着来了大量业务项目用的是传统 Servlet 栈为了调一个第三方接口就得引入 Reactor、学习Mono/Flux、处理各种响应式回调学习成本和心智负担都不小。我见过好多团队把WebClient.block()直接写在 Service 里美其名曰用响应式实际上只是换了个更绕的写法。RestClient是 Spring 6.1 推出的同步 HTTP 客户端官方定位就是RestTemplate 的现代替代品且不强制你进入响应式世界。它的 API 是链式的写起来像WebClient但执行方式是同步阻塞的对普通业务系统非常友好String result restClient.get() .uri(/users/{id}, 1001L) .accept(MediaType.APPLICATION_JSON) .retrieve() .body(String.class);从一个纯粹调用方视角看RestClient 解决了 RestTemplate 的写起来啰嗦问题也解决了 WebClient 的杀鸡用牛刀问题。但它本质上还是一种过程式写法你依然要关心 URL、URI 变量、请求头、响应转换。真正让调用外部 API 变得优雅的是紧接着出现的HTTP Interface。1.2 HTTP Interface 不是什么框架而是一套注解规范很多人第一次听说 HTTP Interface会以为又是个新框架。实际上它是 Spring 6 在spring-web模块里定义的一套注解式接口规范。你只需要定义一个纯 Java 接口在上面标注请求映射注解Spring 会自动生成一个代理实现每次调用接口方法时代理负责把方法参数拼成 HTTP 请求、发送出去、再把响应体转换成方法声明的返回类型。说白了这就是Feign 玩法被官方收编了。但和 Feign 有本质区别HTTP Interface 不是 Spring Cloud 的附属功能它就在最基础的spring-web里你用 Spring Boot 写一个普通的 Web 应用不需要引入任何 Spring Cloud 组件甚至不需要引入额外 starter就能用。而且它不绑定底层 HTTP 客户端Spring 6.0 初期默认绑定WebClientSpring 6.1 起支持了RestClientAdapter可以和 RestClient 完美配合。1.3 这套组合最适合谁结合我在项目里的实际感受HTTP Interface RestClient 最适合这几类人用 Spring Boot 3.x 写微服务或单体应用需要对接第三方 REST API但不想引入整套 Spring Cloud OpenFeign 的团队。正在从 RestTemplate 迁移想要少写代码并且好测试的团队。项目里已经用了 OpenFeign但发现为了调一个外部 HTTP 接口还要引入服务发现、负载均衡那一套觉得过于笨重的人。只要接口定义清晰Mock 方便写单元测试时能直接用 Mockito 把接口一 mock就能把业务逻辑单测跑起来。反过来说如果你的项目已经深度依赖 Spring Cloud 生态大量 Feign 接口和 Nacos/Eureka 服务发现绑定在一起那就没必要强迫自己换这套后面我会单独对比两者怎么选。2. 环境准备Spring Boot 3.2 的最小依赖与第一个可运行示例2.1 版本要求别在 Spring Boot 3.0 上踩坑HTTP Interface 在 Spring Framework 6.0对应 Spring Boot 3.0就有但那时候只能配WebClient。RestClient是 Spring Framework 6.1 才正式推出的想把HTTP Interface RestClient作为默认组合最稳妥的是使用 Spring Boot 3.2 及以上版本。如果你用 3.0 或 3.1HttpServiceProxyFactory里不会提供现成的RestClientAdapter硬用会碰到 API 不存在的问题所以我的建议很直接新项目直接用 Spring Boot 3.2老项目升级到 3.2 再考虑这套方案。2.2 依赖只需要一个 starter这里有个让很多人意外的点如果你只是做Spring MVC 项目 调用外部 HTTP 接口实际上引入spring-boot-starter-web就够了。RestClient、HTTP Interface、注解解析、JSON 转换全部来自spring-webstarter-web 已经把这条链路带上了。不需要额外引入spring-cloud-starter-openfeign也不需要webflux。如果你的项目压根没有 Web 层只想做一个纯后台任务调用外部 API那么引入spring-boot-starter之后再把spring-web和jackson-databind加上即可Spring Boot 的依赖管理会帮你把版本对齐。我建议多数人直接用 starter-web最省事。2.3 第一个能跑的 HTTP Interface三步走先定义一个接口对应你要调用的外部 API。比如我要对接一个用户中心服务查询用户信息public interface UserApiClient { GetExchange(/users/{userId}) UserInfo getUser(PathVariable(userId) Long userId); }然后创建一个 RestClient并通过HttpServiceProxyFactory生成代理RestClient restClient RestClient.builder() .baseUrl(https://user-center.example.com) .defaultHeader(Accept, application/json) .build(); HttpServiceProxyFactory factory HttpServiceProxyFactory .builderFor(RestClientAdapter.create(restClient)) .build(); UserApiClient userApiClient factory.createClient(UserApiClient.class);最后把userApiClient注册成 Spring 管理的 Bean注入到 Service 里使用Configuration public class HttpClientConfig { Bean UserApiClient userApiClient(RestClient.Builder builder) { RestClient restClient builder .baseUrl(https://user-center.example.com) .build(); HttpServiceProxyFactory factory HttpServiceProxyFactory .builderFor(RestClientAdapter.create(restClient)) .build(); return factory.createClient(UserApiClient.class); } }如果你在 Controller 或 Service 里调用userApiClient.getUser(1001L)代理会发送一个 GET 请求到https://user-center.example.com/users/1001响应 JSON 会被自动转换成UserInfo对象。整个过程中你不需要写任何发请求的代码这就达到了标题里说的把调用外部 API 写成接口。3. 把外部 API 写成接口HTTP Interface 注解与代理生成的完整拆解3.1 类级注解 HttpExchange统一请求路径和默认配置HTTP Interface 的注解核心是HttpExchange。它可以直接标在接口类上也可以标在方法上。类级别的HttpExchange一般用来指定公共前缀和默认请求头比如HttpExchange(url /api/v2, accept application/json, contentType application/json) public interface OrderApiClient { GetExchange(/orders/{orderNo}) OrderDetail getOrder(PathVariable(orderNo) String orderNo); }这样方法里的路径/orders/{orderNo}会被拼接到类级别的/api/v2后面最终请求路径是/api/v2/orders/{orderNo}。这种设计非常适合同一个第三方系统多个接口的情况统一在类上声明 base path后续新增接口时只需要关注方法级别的相对路径不容易写错。HttpExchange里有几个属性值得注意url是路径模板method是 HTTP 方法contentType和accept是媒体类型headers可以额外指定自定义请求头。但实际项目中我很少在接口上写死 method因为后续讲的快捷注解已经把方法语义覆盖了写死 method 反而容易出问题。3.2 方法级快捷注解GetExchange 到 PatchExchangeSpring 为 HTTP Interface 提供了五个快捷注解本质上都是HttpExchange预设了 method 的变体GetExchangePostExchangePutExchangeDeleteExchangePatchExchange用法和 Spring MVC 里的GetMapping、PostMapping高度相似。比如PostExchange(/orders) OrderDetail createOrder(RequestBody CreateOrderRequest request); PostExchange(/orders/search) ListOrderDetail searchOrders(RequestBody OrderSearchRequest query); PutExchange(/orders/{orderNo}/cancel) OrderDetail cancelOrder(PathVariable(orderNo) String orderNo, RequestParam(reason) String reason);这里有个很关键的体验点HTTP Interface 的注解设计有意识地和 Spring MVC 对齐因此团队从RestController切到 HTTP Interface 时几乎没有额外学习成本。如果你本来就会用RequestBody、PathVariable、RequestParam那你在写这个接口时几乎是无缝迁移的。3.3 参数绑定与返回值设计HTTP Interface 的方法参数支持以下几种基本覆盖了 REST API 的常见需求PathVariable(id)把参数绑定到 URL 模板中的{id}占位符。RequestParam(name)追加查询参数多个值可以传ListString或数组。RequestHeader(X-Token)设置请求头。CookieValue(sessionId)设置 Cookie。RequestBody把参数对象序列化为请求体。也可以传Map框架会将其展开成多个查询参数或请求头。返回值同样灵活除了直接声明业务对象你还可以返回ResponseEntityT拿到完整的状态码、响应头、响应体三件套。返回void或Void表示不关心响应体内容。返回byte[]、String拿原始响应内容。返回ListT、MapString, Object等带泛型的类型。如果底层用的是 WebClient还能返回MonoT做异步调用。我强烈建议接口方法返回值尽量声明具体的业务类型比如OrderDetail而不是Object这样代理做 JSON 转换时直接往目标类型上转IDE 补全和单元测试也都会舒服很多。3.4 代理工厂HTTP Interface 是怎么凭空变成可调用对象的接口本身不能执行 HTTP关键在于HttpServiceProxyFactory。这个工厂会扫描你传入的接口上的注解信息生成一个 JDK 动态代理。每次调用接口方法时代理对象会解析方法的注解、参数、返回类型构造对应的ClientHttpRequest再交给底层的RestClient或WebClient去执行。HttpServiceProxyFactory的建造方式在和 RestClient 结合时是固定的两步HttpServiceProxyFactory factory HttpServiceProxyFactory .builderFor(RestClientAdapter.create(restClient)) .build();其中RestClientAdapter是 Spring 6.1 提供的适配器它把 RestClient 的同步执行能力包装成 HTTP Interface 可以驱动的统一模型。如果底层换成 WebClient对应的就是WebClientAdapter.forClient(webClient)。这种适配器设计意味着 HTTP Interface 并不关心你底层用谁发请求它只定义契约真正的 I/O 由适配器代理给具体客户端。实际使用中我会建议你把创建代理的代码收敛到一个Configuration类里每个第三方系统对应一个接口、一个 Bean命名清晰一点。如果接口多还可以写个公共方法批量创建减少大量重复的工厂构建代码。4. RestClient 不只是配角引擎配置、超时与底层客户端选择4.1 用 RestClient 做引擎比直接写 WebClient 顺眼太多有些人会把 HTTP Interface 想成就是 RestClient 的语法糖其实不完全对。更准确的说法是HTTP Interface 负责把接口方法翻译成 HTTP 请求模型RestClient 负责真正发出请求并接收响应。但在实际开发中RestClient 本身也是一个非常值得单独掌握的同步 HTTP 客户端即便你暂时不想用 HTTP Interface也可以先用 RestClient 替换掉旧的 RestTemplate 代码。RestClient 的常规用法非常直观ResponseEntityOrderDetail response RestClient.create(https://api.example.com) .post() .uri(/orders) .header(X-Api-Key, xxxx) .contentType(MediaType.APPLICATION_JSON) .body(orderCreateRequest) .retrieve() .toEntity(OrderDetail.class);和 RestTemplate 最大的不同是RestClient 的方法名就是动词.get()、.post()、.put()、.delete()后面直接跟.uri()、.header()、.body()每一步都返回一个面向下一步的 BuilderIDE 提示基本可以带你完整写完几乎不会出现 RestTemplate 那种参数顺序记错、回调接口一堆的问题。4.2 超时、连接池与底层请求工厂不配置等于裸奔这里必须强调一个非常容易被忽略的点RestClient 本身不管理连接和超时它委托给底层的ClientHttpRequestFactory。Spring Boot 3.x 下 RestClient 默认使用的底层工厂是JdkClientHttpRequestFactory也就是 JDK 自带的HttpClient。很多人以为在RestClient.Builder.timeout()里配几秒就完事了这个 API 并不存在超时配置得落到请求工厂上JdkClientHttpRequestFactory jdkFactory new JdkClientHttpRequestFactory(); jdkFactory.setConnectTimeout(Duration.ofSeconds(5)); jdkFactory.setReadTimeout(Duration.ofSeconds(15)); RestClient restClient RestClient.builder() .baseUrl(https://api.example.com) .requestFactory(jdkFactory) .build();如果不配置JDK HttpClient 默认读超时是无限的线上只要第三方服务挂起你的线程就会一直卡住连接池也会被慢慢耗尽最终拖垮整个应用。这是一个生产环境事故率很高的点一定要在初始化时就配置好。如果你想用 Apache HttpClient 或 OkHttp 做底层可以通过引入对应依赖并构建ClientHttpRequestFactory来替换。对大多数普通接口调用场景JDK HttpClient 已经够用没必要多引依赖。4.3 RestClient 的拦拦截器体系日志、认证、重试都在这加RestClient 支持在构建时注册ClientHttpRequestInterceptor这比 RestTemplate 时代清爽很多。比如我习惯做一件事加一个日志拦截器统一打印请求路径、状态码、耗时避免排查问题时两眼一抹黑。RestClient restClient RestClient.builder() .baseUrl(https://api.example.com) .requestInterceptor((request, body, execution) - { long start System.currentTimeMillis(); ClientHttpResponse response execution.execute(request, body); long cost System.currentTimeMillis() - start; System.out.println(request.getMethod() request.getURI() - response.getStatusCode() [ cost ms]); return response; }) .build();认证头、Token 刷新、幂等重试等公共逻辑都可以写在这种拦截器里一处配置处处生效。HTTP Interface 生成的所有请求都会经过这个拦截器所以在 RestClient 上做统一治理等于给所有声明式接口都加上了统一治理能力。这个点是我觉得RestClient HTTP Interface组合最香的地方。5. 我实测踩过的三个坑泛型、错误响应、超时日志5.1 泛型返回值被吃掉直接拿到一个 List 却转不出来有一次我定义了一个接口方法返回类型是ListOrderDetail代理调用时直接抛了类型转换异常后台日志提示Object无法转成OrderDetail。排查后发现问题出在我把方法返回值偷懒写成了接口的原始类型List没有写泛型参数// 错误写法泛型丢了 GetExchange(/orders) List getOrders(); // 正确写法 GetExchange(/orders) ListOrderDetail getOrders();这里面的原理是HTTP Interface 需要根据方法的泛型返回类型来构造ParameterizedTypeReference如果泛型不存在框架只能按Object处理结果序列化出来的对象自然无法转成OrderDetail。这个坑我在代码 review 里见过好几次表面上是报错信息看不懂根子就是泛型擦除。所以定义接口方法时返回类型一定要写完整泛型不要裸写List、Map。5.2 4xx/5xx 响应为什么会抛异常统一错误响应处理的落地方式HTTP Interface 的代理遇到非 2xx 状态码时默认会抛出RestClientResponseException。第一次用的时候我很不适应——我期望的是不管什么状态码先把响应体给我我根据状态码决定怎么处理。但框架的默认语义是非成功状态码即异常。如果你想保留完整的状态码和错误响应体最直接的办法是把方法返回值声明成ResponseEntityGetExchange(/orders/{orderNo}) ResponseEntityOrderDetail getOrder(PathVariable(orderNo) String orderNo);这样 4xx/5xx 的响应也能通过ResponseEntity拿到但如果你仍然直接声明业务对象异常还是照抛。我的实践经验是对于确定性比较高的业务接口直接声明业务对象配合全局异常捕获处理对于拿不准的第三方接口用ResponseEntity兜底在 Service 里先判状态码再取业务数据。这两种模式按接口区分不要混用。5.3 超时配了但不生效坑在配错了对象我踩过的一个隐蔽问题是在RestClient的.uri(...)方法上传入了一个带超时参数的 URI想当然地以为请求超时就被覆盖了。实际上 RestClient 的 URI 只负责拼接地址超时控制完全由requestFactory决定。我那次排查了很久最后打印线程栈才发现线程一直阻塞在网络读上。正确做法就是你得通过requestFactory显式设置SimpleClientHttpRequestFactory simple new SimpleClientHttpRequestFactory(); simple.setConnectTimeout(5000); simple.setReadTimeout(10000); RestClient.builder() .requestFactory(simple) .build();另外要留意一旦自定义了requestFactory某些基于类型判断的自动配置可能会失效例如部分 Boot 自动配置会尝试帮你调优连接池如果你自己覆盖了工厂那这部分优化就中断了。所以我的建议是不要随意自定义请求工厂除非你真清楚底层客户端的连接管理方式。6. 和 OpenFeign 的取舍什么时候换什么时候别硬换6.1 两者核心差异对照如果团队里已经在用 Spring Cloud OpenFeign面对 HTTP Interface 的第一个问题肯定是是不是要迁移。我把两个方案放在一起对比过结论很清楚它们定位不同不是简单的替代关系。对比维度HTTP Interface RestClientOpenFeign所属生态Spring 官方基础模块spring-webSpring Cloud OpenFeign依赖成本只需spring-boot-starter-web需要spring-cloud-starter-openfeign注解体系HttpExchange系列 Spring MVC 参数注解FeignClient Spring MVC 注解服务发现不支持需自己集成或直接写 URL天然集成 Nacos/Eureka负载均衡需手动配LoadBalancerClient开箱即用底层客户端RestClient / WebClientFeign 内置实现可配 OkHttp 等拦截器扩展ClientHttpRequestInterceptorRequestInterceptor容错降级无内置可配合 Resilience4j有 Spring Cloud CircuitBreaker 集成从表格能看出来HTTP Interface 的强项是轻量和独立Feign 的强项是微服务生态整合尤其在服务发现和负载均衡上是真正开箱即用。6.2 我的选择建议和迁移思路如果你是普通 Spring Boot 单体或者两三个服务之间的轻量调用外部 API 地址基本是固定的那我强烈建议用 HTTP Interface RestClient。它不引入 Spring Cloud 那一大坨依赖底层可控测试友好特别是新项目里完全没必要为了调用一个第三方支付接口去拉一套 OpenFeign。但如果你已经在 Spring Cloud 体系内团队技能栈也围绕 Feign 建立了各种统一拦截器、降级策略那就别硬换。这种场景强切 HTTP Interface服务发现和负载均衡都要自己重新接收益不大。假如确实需要从 Feign 迁过来迁移路径其实比想象中平滑原来标FeignClient的接口保留方法签名把接口上的注解换成HttpExchangeFeignClient的configuration属性里的 Bean 改写成 RestClient 的拦截器或自定义RestClient.Builder。大部分业务代码调用方不需要动因为上游还是那个接口对象。我们团队有一个内部组件就是用这种方式把一个独立模块从 OpenFeign 迁到了 HTTP Interface迁移成本主要花在测试回归上代码改动其实不大。我个人在项目里现在的默认做法是新模块一律使用 HTTP Interface RestClient老模块除非有大额重构计划否则维持现状。这套组合虽然年轻但它是 Spring 官方持续演进的方向至少在未来几年内不会像 RestTemplate 那样进入维护模式。如果你正在纠结客户端选型直接拿一个小接口先试点感受一下写接口、加注解、注入调用的完整流程比看任何对比文章都来得直观。