【微服务|SpringBoot 3.0】 新特性——内置声明式HTTP客户端

前言

从Spring 6和Spring Boot 3开始，Spring framework支持将远程http服务代理为带有HTTP交换注解方法的Java接口。类似的库，如OpenFeign和Retrofit，仍然可以使用，但HttpServiceProxyFactory添加了对Spring框架的原生支持。

声明式HTTP接口

声明式 http 客户端主旨是使得编写 java http 客户端更容易。为了贯彻这个理念，采用了通过处理注解来自动生成请求的方式（官方称呼为声明式、模板化）。通过声明式 http 客户端实现我们就可以在 java 中像调用一个本地方法一样完成一次 http 请求，大大减少了编码成本，同时提高了代码可读性。

举个例子，如果想调用 /tenants 的接口，只需要定义如下的接口类即可

public interface TenantClient {

  @GetExchange("/tenants")
  Flux<User> getAll();
}

Spring 会在运行时提供接口的调用的具体实现，如上请求我们可以如 Java 方法一样调用

@Autowired
TenantClient tenantClient;

tenantClient.getAll().subscribe(

);

如果我们想使用HTTP GET /users API，那么我们可以简单地编写:

public interface UserClient {
  @GetExchange("/users")
  Flux<User> getAll();
}

Spring会在运行时提供接口和exchange实现，我们只需要调用getAll()方法。

@Autowired
UserClient userClient;
userClient.getAll().subscribe(
    data -> log.info("User: {}", data)
);

测试使用

1. Maven

声明式HTTP接口功能是spring-web依赖的一部分，当我们引入spring-boot-starter-web或spring-boot-starter-webflux时，它就会被传递引入。如果我们想添加响应式支持，那么就包括后面的依赖。

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

<!-- For reactive support -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

2.创建HTTP服务接口

在Spring中，HTTP服务接口是一个带有@HttpExchange方法的Java接口。带注释的方法被视为HTTP端点，细节通过注解属性和输入法参数类型静态定义。
交流的方法
我们可以使用以下注解将方法标记为HTTP服务端点:

@HttpExchange:是指定HTTP端点的通用注释。当在接口级别使用时，它适用于所有方法。
@GetExchange:为HTTP GET请求指定@HttpExchange。
@PostExchange:对于HTTP POST请求，指定@HttpExchange。
@PutExchange:为HTTP PUT请求指定@HttpExchange。
@DeleteExchange:对于HTTP DELETE请求，指定@HttpExchange。
@PatchExchange:对于HTTP Patch请求，指定@HttpExchange。

方法参数
exchange方法在方法签名中支持下列方法参数:

URI:设置请求的URL。
@PathVariable:将请求URL中的值替换为占位符。
@RequestBody:提供请求的主体。
@RequestParam:添加请求参数。当“content-type”设置为“application/x-www-form-urlencoded”时，请求参数会在请求体中编码。否则，它们将作为URL查询参数添加。
@ requesttheader:添加请求头的名称和值。
@RequestPart:可用于添加请求部分(表单字段，资源或HttpEntity等)。
@CookieValue:向请求中添加cookie。

示例代码：

@PutExchange
void update(@PathVariable Long id, @RequestBody User user);

返回值
HTTP exchange方法可以返回如下值:

阻塞或反应性(Mono/Flux)。
只有特定的响应信息，如状态码和/或响应头。
Void，表示该方法仅被视为execute方法;

对于阻塞交换方法，我们通常应该返回ResponseEntity，而对于响应式方法，我们可以返回Mono/Flux类型。

//阻塞性
@GetExchange("/{id}")
User getById(...);

//Reactive
@GetExchange("/{id}")
Mono<User> getById(...);

3.构建HttpServiceProxyFactory

HttpServiceProxyFactory是一个从HTTP服务接口创建客户端代理的工厂。使用它的HttpServiceProxyFactory.builder(client).build()方法来获取代理bean的实例。

import ***.fasterxml.jackson.databind.ObjectMapper;
import ***.leftso.app.web.UserClient;
import lombok.SneakyThrows;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.reactive.function.client.support.WebClientAdapter;
import org.springframework.web.service.invoker.HttpServiceProxyFactory;

@Configuration
public class WebConfig {
  @Bean
  WebClient webClient(ObjectMapper objectMapper) {
    return WebClient.builder()
        .baseUrl("https://jsonplaceholder.typicode.***/")
        .build();
  }
  @SneakyThrows
  @Bean
  UserClient postClient(WebClient webClient) {
    HttpServiceProxyFactory httpServiceProxyFactory =
        HttpServiceProxyFactory.builder(WebClientAdapter.forClient(webClient))
            .build();
    return httpServiceProxyFactory.createClient(UserClient.class);
  }
}

注意，我们已经在WebClient bean中设置了远程API的基础URL，因此我们只需要在交换方法中使用相对路径。

4. HTTP业务接口示例

下面是与https://jsonplaceholder.typicode.***/users/端点交互并执行各种操作的HTTP接口示例。

import ***.leftso.app.model.User;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.service.annotation.DeleteExchange;
import org.springframework.web.service.annotation.GetExchange;
import org.springframework.web.service.annotation.HttpExchange;
import org.springframework.web.service.annotation.PostExchange;
import org.springframework.web.service.annotation.PutExchange;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

@HttpExchange(url = "/users", a***ept = "application/json", contentType = "application/json")
public interface UserClient {
  @GetExchange("/")
  Flux<User> getAll();

  @GetExchange("/{id}")
  Mono<User> getById(@PathVariable("id") Long id);

  @PostExchange("/")
  Mono<ResponseEntity<Void>> save(@RequestBody User user);

  @PutExchange("/{id}")
  Mono<ResponseEntity<Void>> update(@PathVariable Long id, @RequestBody User user);

  @DeleteExchange("/{id}")
  Mono<ResponseEntity<Void>> delete(@PathVariable Long id);
}

注意，我们创建了一个User类型的记录来保存用户信息。

public record User(Long id, String name, String username, String email) {}

现在我们可以将UserClient bean注入到应用程序类中，并调用方法以获取API响应。

@Autowired
UserClient userClient;
//获取所有用户
userClient.getAll().subscribe(
    data -> log.info("User: {}", data)
);
//通过id获取用户
userClient.getById(1L).subscribe(
    data -> log.info("User: {}", data)
);
//创建一个新用户
userClient.save(new User(null, "Lokesh", "lokesh", "admin@email.***"))
    .subscribe(
        data -> log.info("User: {}", data)
    );
//通过id删除用户
userClient.delete(1L).subscribe(
    data -> log.info("User: {}", data)
);

总结

在这个Spring（Spring Boot 3.0）教程中，我们通过示例学习了如何创建和使用声明式HTTP客户端接口。

Spring Boot3.0王炸版本带来了很多新特性，值得我们深入学习

推荐给大家哔站上动力节点王妈妈的springboot3教程，采用知识点配合项目案例的方式，可以让大家很轻松的掌握SpringBoot

配套资料也非常全面，领取方式可看视频简介区~

点击这里开始 快速学习