Spring HTTP Interface 入门案例介绍

Spring HTTP Interface 是 Spring 6 和 Spring Boot 3.0 引入的声明式 HTTP 客户端特性，允许通过接口和注解定义 HTTP 请求，无需手动编写 HTTP 调用代码。以下是核心要点：

一、核心特性

1. 声明式接口定义
   通过 Java 接口 + 注解（如@GetExchange）定义 HTTP 请求，类似 Feign

   例如：

   public interface UserApiService {
       @GetExchange("/users")
       List<User> getUsers();
   }
   

2. 运行时代理实现
   Spring 自动生成接口的代理类，底层基于 WebClient（响应式）或未来的 RestTemplate 实现。

3. 简化依赖管理
   仅需添加spring-boot-starter-webflux依赖即可启用，无需引入第三方库（如 OpenFeign）

二、使用步骤

1. 添加依赖

首先，你需要在你的项目中添加 Spring Boot 和 Spring webflux 的依赖。可以在pom.xml文件中添加以下依赖：

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

2. 创建 HTTP 接口

接下来，你可以创建一个接口来定义你的 HTTP 请求。Spring HTTP Interface 使用注解来标记请求的方法和路径。以下是一个简单的示例：

import org.springframework.web.service.annotation.GetExchange;  
import org.springframework.web.service.annotation.HttpExchange;  
import reactor.core.publisher.Mono;  
 
// 使用 @HttpExchange 注解来指定基础 URL 和请求头信息 
@HttpExchange(url = "https://jsonplaceholder.typicode.com",  accept = "application/json") 
public interface JsonPlaceholderService { 
 
    // 使用 @GetExchange 注解来指定具体的请求路径 
    // 该方法用于获取一个用户的信息，返回一个 Mono 对象，Mono 是 Reactor 库中的一种响应式类型，表示最多包含一个元素的异步序列 
    @GetExchange("/users/1") 
    Mono<String> getUser(); 
} 

在上述代码中：

@HttpExchange注解用于指定基础 URL 和请求头信息，这里的基础 URL 是https://jsonplaceholder.typicode.com，

请求头中accept字段为application/json，表示期望接收 JSON 格式的数据。

@GetExchange注解用于指定具体的请求路径，这里的路径是/users/1，表示获取 ID 为 1 的用户信息。

Mono<String>表示该方法返回一个异步的字符串结果，使用Mono是为了支持响应式编程。

3. 配置 HTTP 客户端

创建一个配置类： JsonPlaceholderService，用于配置 HTTP 客户端和初始化

import org.springframework.context.annotation.Bean;  
import org.springframework.context.annotation.Configuration;  
import org.springframework.web.reactive.function.client.WebClient;  
import org.springframework.web.service.invoker.HttpServiceProxyFactory;  
 
@Configuration 
public class HttpServiceConfig { 
 
    // 定义一个 WebClient Bean，用于发送 HTTP 请求 
    @Bean 
    public WebClient webClient() { 
        return WebClient.builder().build();  
    } 
 
    // 定义一个 JsonPlaceholderService Bean，使用 HttpServiceProxyFactory 来创建接口的代理实例 
    @Bean 
    public JsonPlaceholderService jsonPlaceholderService(WebClient webClient) { 
        // 创建 HttpServiceProxyFactory 实例，并使用 WebClientAdapter 将 WebClient 适配到工厂中 
        HttpServiceProxyFactory factory = HttpServiceProxyFactory.builder()  
               .clientAdapter(org.springframework.web.reactive.function.client.support.WebClientAdapter.forClient(webClient))  
               .build(); 
        // 使用工厂创建 JsonPlaceholderService 接口的代理实例 
        return factory.createClient(JsonPlaceholderService.class);  
    } 
} 

4. 测试调用

创建一个测试类，用于测试

import org.junit.jupiter.api.Test;  
import org.springframework.beans.factory.annotation.Autowired;  
import org.springframework.boot.test.context.SpringBootTest;  
import reactor.test.StepVerifier;  
 
@SpringBootTest 
public class JsonPlaceholderServiceTest { 
 
    // 注入 JsonPlaceholderService 实例 
    @Autowired 
    private JsonPlaceholderService jsonPlaceholderService; 
 
    @Test 
    public void testGetUser() { 
        // 调用 JsonPlaceholderService 接口的 getUser 方法，获取一个 Mono 对象 
        var result = jsonPlaceholderService.getUser();  
        // 使用 StepVerifier 来验证 Mono 对象的结果 
        StepVerifier.create(result)  
               .expectNextMatches(response -> response.contains("\"id\":  1")) 
               .verifyComplete(); 
    } 
} 

三、优势与适用场景

1. 简化代码
   将 HTTP 请求抽象为 Java 方法，减少模板代码，提升开发效率15。
2. 集成 Spring 生态
   支持参数绑定、错误处理、拦截器等，与 Spring 特性无缝兼容36。
3. 响应式支持
   默认基于 WebClient，适合响应式和非阻塞场景16。

四、注意事项

1. 版本要求
   Spring Boot ≥ 3.0 且 JDK ≥ 1737。
2. 依赖限制
   目前仅支持 WebClient 实现，RestTemplate 支持待后续版本36。
3. 与 Feign 对比
   功能类似，但 HTTP Interface 是 Spring 原生方案，适合新项目；已有 Feign 项目可逐步迁移57。

五、扩展应用

• 复杂请求处理：支持路径变量、请求头、表单参数等注解配置6。
• 错误处理：自定义异常映射和降级逻辑6。
• 测试：结合 MockWebServer 或 Spring Boot Test 进行单元测试2。