4.0.6
该项目通过自动配置和绑定到 Spring 环境及其他 Spring 编程模型惯用语,为 Spring Boot 应用提供 OpenFeign 集成。
1. 声明式 REST 客户端:Feign
Feign 是一个声明式的 Web 服务客户端。它使编写 Web 服务客户端变得更加容易。要使用 Feign,创建一个接口并进行注解。它支持可插拔的注解,包括 Feign 注解和 JAX-RS 注解。Feign 还支持可插拔的编码器和解码器。Spring Cloud 添加了对 Spring MVC 注解的支持,以及使用 Spring Web 中默认使用的相同 HttpMessageConverters。Spring Cloud 集成了 Eureka、Spring Cloud CircuitBreaker 以及 Spring Cloud LoadBalancer,在使用 Feign 时提供一个负载均衡的 HTTP 客户端。
1.1. 如何包含 Feign
要在您的项目中包含 Feign,请使用群组为 org.springframework.cloud,artifact id 为 spring-cloud-starter-openfeign 的 starter。有关使用当前 Spring Cloud 发布列车设置构建系统的详细信息,请参阅Spring Cloud 项目页面。
Spring Boot 应用程序示例
@SpringBootApplication
@EnableFeignClients
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
@FeignClient("stores")
public interface StoreClient {
@RequestMapping(method = RequestMethod.GET, value = "/stores")
List<Store> getStores();
@RequestMapping(method = RequestMethod.GET, value = "/stores")
Page<Store> getStores(Pageable pageable);
@RequestMapping(method = RequestMethod.POST, value = "/stores/{storeId}", consumes = "application/json")
Store update(@PathVariable("storeId") Long storeId, Store store);
@RequestMapping(method = RequestMethod.DELETE, value = "/stores/{storeId:\\d+}")
void delete(@PathVariable Long storeId);
}
在 @FeignClient 注解中,字符串值(上面是 "stores")是一个任意客户端名称,用于创建 Spring Cloud LoadBalancer 客户端。您还可以使用 url 属性(绝对值或仅主机名)指定 URL。应用程序上下文中的 bean 名称是接口的完全限定名。要指定您自己的别名值,您可以使用 @FeignClient 注解的 qualifiers 值。
上面的负载均衡器客户端将希望发现 "stores" 服务的物理地址。如果您的应用程序是 Eureka 客户端,它将在 Eureka 服务注册表中解析该服务。如果您不想使用 Eureka,您可以使用 SimpleDiscoveryClient 在您的外部配置中配置服务器列表。
Spring Cloud OpenFeign 支持 Spring Cloud LoadBalancer 阻塞模式的所有可用功能。您可以在项目文档中了解更多信息。
要在 @Configuration 注解的类上使用 @EnableFeignClients 注解,请务必指定客户端所在的位置,例如:@EnableFeignClients(basePackages = "com.example.clients") 或显式列出它们:@EnableFeignClients(clients = InventoryServiceFeignClient.class) |
1.1.1. 属性解析模式
在创建 Feign 客户端 bean 时,我们解析通过 @FeignClient 注解传递的值。从 4.x 开始,这些值正在被急切地解析。对于大多数用例来说,这是一个很好的解决方案,它还支持 AOT。
如果您需要延迟解析属性,请将 spring.cloud.openfeign.lazy-attributes-resolution 属性值设置为 true。
| 对于 Spring Cloud Contract 测试集成,应该使用延迟属性解析。 |
1.2. 覆盖 Feign 默认值
Spring Cloud 的 Feign 支持中的一个核心概念是命名客户端。每个 Feign 客户端都是组件集合的一部分,这些组件协同工作以按需联系远程服务器,并且该集合有一个名称,您作为应用程序开发人员使用 @FeignClient 注解给它。Spring Cloud 为每个命名客户端使用 FeignClientsConfiguration 按需创建一个新的 ApplicationContext 集合。这(除其他外)包含一个 feign.Decoder、一个 feign.Encoder 和一个 feign.Contract。可以通过使用 @FeignClient 注解的 contextId 属性来覆盖该集合的名称。
Spring Cloud 允许您通过使用 @FeignClient 声明额外配置(在 FeignClientsConfiguration 之上)来完全控制 Feign 客户端。例如
@FeignClient(name = "stores", configuration = FooConfiguration.class)
public interface StoreClient {
//..
}
在这种情况下,客户端由 FeignClientsConfiguration 中已有的组件以及 FooConfiguration 中的任何组件组成(后者将覆盖前者)。
FooConfiguration 不需要用 @Configuration 注解。但是,如果它被注解了,那么请注意将其从任何 @ComponentScan 中排除,否则该 @ComponentScan 将包含此配置,因为它将成为 feign.Decoder、feign.Encoder、feign.Contract 等的默认源(如果指定)。这可以通过将其放在与任何 @ComponentScan 或 @SpringBootApplication 不重叠的单独包中来避免,或者可以在 @ComponentScan 中显式排除它。 |
除了更改 ApplicationContext 集合的名称之外,使用 @FeignClient 注解的 contextId 属性还将覆盖客户端名称的别名,并将其用作为该客户端创建的配置 bean 名称的一部分。 |
以前,使用 url 属性不需要 name 属性。现在必须使用 name。 |
name 和 url 属性支持占位符。
@FeignClient(name = "${feign.name}", url = "${feign.url}")
public interface StoreClient {
//..
}
Spring Cloud OpenFeign 默认提供以下 Feign bean(BeanType beanName: ClassName)
-
DecoderfeignDecoder:ResponseEntityDecoder(包装了一个SpringDecoder) -
EncoderfeignEncoder:SpringEncoder -
LoggerfeignLogger:Slf4jLogger -
MicrometerObservationCapabilitymicrometerObservationCapability: 如果类路径上有feign-micrometer并且ObservationRegistry可用 -
MicrometerCapabilitymicrometerCapability: 如果类路径上有feign-micrometer,MeterRegistry可用且ObservationRegistry不可用 -
CachingCapabilitycachingCapability: 如果使用@EnableCaching注解。可以通过spring.cloud.openfeign.cache.enabled禁用。 -
ContractfeignContract:SpringMvcContract -
Feign.BuilderfeignBuilder:FeignCircuitBreaker.Builder -
ClientfeignClient: 如果类路径上有 Spring Cloud LoadBalancer,则使用FeignBlockingLoadBalancerClient。如果两者都没有,则使用默认的 Feign 客户端。
spring-cloud-starter-openfeign 支持 spring-cloud-starter-loadbalancer。但是,由于它是一个可选依赖项,如果您想使用它,需要确保已将其添加到您的项目中。 |
要使用 OkHttpClient 支持的 Feign 客户端,请确保 OKHttpClient 在您的类路径上,并将 spring.cloud.openfeign.okhttp.enabled 设置为 true。
对于 Apache HttpClient 5 支持的 Feign 客户端,只需确保 HttpClient 5 在类路径上即可,但您仍然可以通过将 spring.cloud.openfeign.httpclient.hc5.enabled 设置为 false 来禁用 Feign 客户端使用它。您可以通过在使用 Apache HC5 时提供 org.apache.hc.client5.http.impl.classic.CloseableHttpClient 类型的 bean 来定制使用的 HTTP 客户端。
您可以通过在 spring.cloud.openfeign.httpclient.xxx 属性中设置值来进一步定制 HTTP 客户端。以 httpclient 开头的属性将适用于所有客户端,以 httpclient.hc5 开头的适用于 Apache HttpClient 5,以 httpclient.okhttp 开头的适用于 OkHttpClient。您可以在附录中找到可自定义的属性的完整列表。
| 从 Spring Cloud OpenFeign 4 开始,不再支持 Feign Apache HttpClient 4。我们建议改用 Apache HttpClient 5。 |
Spring Cloud OpenFeign 不 默认提供以下 Feign bean,但仍从应用程序上下文中查找这些类型的 bean 以创建 Feign 客户端
-
Logger.Level -
Retryer -
ErrorDecoder -
Request.Options -
Collection<RequestInterceptor> -
SetterFactory -
QueryMapEncoder -
Capability(MicrometerObservationCapability和CachingCapability默认提供)
默认情况下会创建一个类型为 Retryer 的 Retryer.NEVER_RETRY bean,这将禁用重试。请注意,这种重试行为与 Feign 默认行为不同,在 Feign 默认行为中,它会自动重试 IOException,将其视为瞬时网络相关异常,以及从 ErrorDecoder 抛出的任何 RetryableException。
创建其中一种类型的 bean 并将其放在 @FeignClient 配置中(例如上面的 FooConfiguration)允许您覆盖所描述的每个 bean。示例
@Configuration
public class FooConfiguration {
@Bean
public Contract feignContract() {
return new feign.Contract.Default();
}
@Bean
public BasicAuthRequestInterceptor basicAuthRequestInterceptor() {
return new BasicAuthRequestInterceptor("user", "password");
}
}
这会将 SpringMvcContract 替换为 feign.Contract.Default,并向 RequestInterceptor 集合添加一个 RequestInterceptor。
@FeignClient 也可以使用配置属性进行配置。
application.yml
spring:
cloud:
openfeign:
client:
config:
feignName:
url: http://remote-service.com
connectTimeout: 5000
readTimeout: 5000
loggerLevel: full
errorDecoder: com.example.SimpleErrorDecoder
retryer: com.example.SimpleRetryer
defaultQueryParameters:
query: queryValue
defaultRequestHeaders:
header: headerValue
requestInterceptors:
- com.example.FooRequestInterceptor
- com.example.BarRequestInterceptor
responseInterceptor: com.example.BazResponseInterceptor
dismiss404: false
encoder: com.example.SimpleEncoder
decoder: com.example.SimpleDecoder
contract: com.example.SimpleContract
capabilities:
- com.example.FooCapability
- com.example.BarCapability
queryMapEncoder: com.example.SimpleQueryMapEncoder
micrometer.enabled: false
此示例中的 feignName 指的是 @FeignClient 的 value,它也与 @FeignClient 的 name 和 @FeignClient 的 contextId 别名。在负载均衡场景中,它也对应于将用于检索实例的服务器应用程序的 serviceId。解码器、重试器和其他指定的类必须在 Spring 上下文中有一个 bean 或有一个默认构造函数。
默认配置可以通过 @EnableFeignClients 属性 defaultConfiguration 以与上述类似的方式指定。区别在于此配置将应用于 所有 Feign 客户端。
如果您更喜欢使用配置属性来配置所有 @FeignClient,您可以使用 default Feign 名称创建配置属性。
您可以使用 spring.cloud.openfeign.client.config.feignName.defaultQueryParameters 和 spring.cloud.openfeign.client.config.feignName.defaultRequestHeaders 来指定将随名为 feignName 的客户端的每个请求一起发送的查询参数和头。
application.yml
spring:
cloud:
openfeign:
client:
config:
default:
connectTimeout: 5000
readTimeout: 5000
loggerLevel: basic
如果同时创建 @Configuration bean 和配置属性,配置属性将胜出。它将覆盖 @Configuration 值。但如果您想将优先级更改为 @Configuration,可以将 spring.cloud.openfeign.client.default-to-properties 更改为 false。
如果我们想创建多个具有相同名称或 URL 的 Feign 客户端,以便它们指向同一服务器但每个都具有不同的自定义配置,那么我们必须使用 @FeignClient 的 contextId 属性,以避免这些配置 bean 的名称冲突。
@FeignClient(contextId = "fooClient", name = "stores", configuration = FooConfiguration.class)
public interface FooClient {
//..
}
@FeignClient(contextId = "barClient", name = "stores", configuration = BarConfiguration.class)
public interface BarClient {
//..
}
还可以配置 FeignClient 不从父上下文继承 bean。您可以通过覆盖 FeignClientConfigurer bean 中的 inheritParentConfiguration() 返回 false 来实现
@Configuration
public class CustomConfiguration {
@Bean
public FeignClientConfigurer feignClientConfigurer() {
return new FeignClientConfigurer() {
@Override
public boolean inheritParentConfiguration() {
return false;
}
};
}
}
默认情况下,Feign 客户端不编码斜杠 / 字符。您可以通过将 spring.cloud.openfeign.client.decodeSlash 的值设置为 false 来更改此行为。 |
1.2.1. SpringEncoder 配置
在我们提供的 SpringEncoder 中,我们将二进制内容类型设置为 null 字符集,将所有其他内容类型设置为 UTF-8。
您可以通过将 spring.cloud.openfeign.encoder.charset-from-content-type 的值设置为 true 来修改此行为,从而从 Content-Type 头字符集中派生字符集。
1.3. 超时处理
我们可以为默认客户端和命名客户端配置超时。OpenFeign 使用两个超时参数
-
connectTimeout防止因服务器处理时间过长而阻塞调用者。 -
readTimeout从连接建立时开始应用,当返回响应时间过长时触发。
如果服务器未运行或不可用,数据包会导致 连接被拒绝。通信要么以错误消息结束,要么以回退结束。如果 connectTimeout 设置得很低,这可能发生在 之前。执行查找和接收此类数据包所需的时间构成了此延迟的很大一部分。它会根据涉及 DNS 查找的远程主机而改变。 |
1.4. 手动创建 Feign 客户端
在某些情况下,可能需要以无法使用上述方法的方式自定义您的 Feign 客户端。在这种情况下,您可以使用 Feign Builder API 创建客户端。下面是一个示例,它创建了两个具有相同接口的 Feign 客户端,但为每个客户端配置了单独的请求拦截器。
@Import(FeignClientsConfiguration.class)
class FooController {
private FooClient fooClient;
private FooClient adminClient;
@Autowired
public FooController(Client client, Encoder encoder, Decoder decoder, Contract contract, MicrometerObservationCapability micrometerObservationCapability) {
this.fooClient = Feign.builder().client(client)
.encoder(encoder)
.decoder(decoder)
.contract(contract)
.addCapability(micrometerObservationCapability)
.requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
.target(FooClient.class, "https://PROD-SVC");
this.adminClient = Feign.builder().client(client)
.encoder(encoder)
.decoder(decoder)
.contract(contract)
.addCapability(micrometerObservationCapability)
.requestInterceptor(new BasicAuthRequestInterceptor("admin", "admin"))
.target(FooClient.class, "https://PROD-SVC");
}
}
在上面的示例中,FeignClientsConfiguration.class 是 Spring Cloud OpenFeign 提供的默认配置。 |
PROD-SVC 是客户端将向其发出请求的服务的名称。 |
Feign Contract 对象定义了接口上哪些注解和值是有效的。自动装配的 Contract bean 支持 SpringMVC 注解,而不是默认的 Feign 原生注解。 |
您还可以使用 Builder 来配置 FeignClient 不从父上下文继承 bean。您可以通过在 Builder 上调用 inheritParentContext(false) 来实现。
1.5. Feign Spring Cloud CircuitBreaker 支持
如果类路径上有 Spring Cloud CircuitBreaker 并且 spring.cloud.openfeign.circuitbreaker.enabled=true,Feign 将使用断路器包装所有方法。
要禁用每个客户端的 Spring Cloud CircuitBreaker 支持,请创建一个具有 "prototype" 范围的普通 Feign.Builder,例如
@Configuration
public class FooConfiguration {
@Bean
@Scope("prototype")
public Feign.Builder feignBuilder() {
return Feign.builder();
}
}
断路器名称遵循此模式 <feignClientClassName>#<calledMethod>(<parameterTypes>)。当调用具有 FooClient 接口的 @FeignClient 并且被调用的接口方法没有参数是 bar 时,断路器名称将是 FooClient#bar()。
从 2020.0.2 开始,断路器名称模式已从 <feignClientName>_<calledMethod> 更改。使用 2020.0.4 中引入的 CircuitBreakerNameResolver,断路器名称可以保留旧模式。 |
通过提供 CircuitBreakerNameResolver 的 bean,您可以更改断路器名称模式。
@Configuration
public class FooConfiguration {
@Bean
public CircuitBreakerNameResolver circuitBreakerNameResolver() {
return (String feignClientName, Target<?> target, Method method) -> feignClientName + "_" + method.getName();
}
}
要启用 Spring Cloud CircuitBreaker 组,请将 spring.cloud.openfeign.circuitbreaker.group.enabled 属性设置为 true(默认为 false)。
1.6. 使用配置属性配置 CircuitBreaker
您可以通过配置属性配置 CircuitBreaker。
例如,如果您有这个 Feign 客户端
@FeignClient(url = "https://:8080")
public interface DemoClient {
@GetMapping("demo")
String getDemo();
}
您可以通过以下方式使用配置属性配置它
spring:
cloud:
openfeign:
circuitbreaker:
enabled: true
alphanumeric-ids:
enabled: true
resilience4j:
circuitbreaker:
instances:
DemoClientgetDemo:
minimumNumberOfCalls: 69
timelimiter:
instances:
DemoClientgetDemo:
timeoutDuration: 10s
如果您想切换回 Spring Cloud 2022.0.0 之前使用的断路器名称,可以将 spring.cloud.openfeign.circuitbreaker.alphanumeric-ids.enabled 设置为 false。 |
1.7. Feign Spring Cloud CircuitBreaker 回退
Spring Cloud CircuitBreaker 支持回退概念:当断路器打开或出现错误时执行的默认代码路径。要为给定的 @FeignClient 启用回退,请将 fallback 属性设置为实现回退的类名。您还需要将您的实现声明为 Spring bean。
@FeignClient(name = "test", url = "https://:${server.port}/", fallback = Fallback.class)
protected interface TestClient {
@RequestMapping(method = RequestMethod.GET, value = "/hello")
Hello getHello();
@RequestMapping(method = RequestMethod.GET, value = "/hellonotfound")
String getException();
}
@Component
static class Fallback implements TestClient {
@Override
public Hello getHello() {
throw new NoFallbackAvailableException("Boom!", new RuntimeException());
}
@Override
public String getException() {
return "Fixed response";
}
}
如果需要访问导致回退触发的原因,可以使用 @FeignClient 中的 fallbackFactory 属性。
@FeignClient(name = "testClientWithFactory", url = "https://:${server.port}/",
fallbackFactory = TestFallbackFactory.class)
protected interface TestClientWithFactory {
@RequestMapping(method = RequestMethod.GET, value = "/hello")
Hello getHello();
@RequestMapping(method = RequestMethod.GET, value = "/hellonotfound")
String getException();
}
@Component
static class TestFallbackFactory implements FallbackFactory<FallbackWithFactory> {
@Override
public FallbackWithFactory create(Throwable cause) {
return new FallbackWithFactory();
}
}
static class FallbackWithFactory implements TestClientWithFactory {
@Override
public Hello getHello() {
throw new NoFallbackAvailableException("Boom!", new RuntimeException());
}
@Override
public String getException() {
return "Fixed response";
}
}
1.8. Feign 和 @Primary
当将 Feign 与 Spring Cloud CircuitBreaker 回退一起使用时,ApplicationContext 中存在多个相同类型的 bean。这将导致 @Autowired 无法工作,因为没有恰好一个 bean,或者没有一个被标记为 primary。为了解决这个问题,Spring Cloud OpenFeign 将所有 Feign 实例标记为 @Primary,这样 Spring Framework 就会知道要注入哪个 bean。在某些情况下,这可能不合需要。要关闭此行为,请将 @FeignClient 的 primary 属性设置为 false。
@FeignClient(name = "hello", primary = false)
public interface HelloClient {
// methods here
}
1.9. Feign 继承支持
Feign 通过单继承接口支持样板 API。这允许将常见操作分组到方便的基接口中。
public interface UserService {
@RequestMapping(method = RequestMethod.GET, value ="/users/{id}")
User getUser(@PathVariable("id") long id);
}
@RestController
public class UserResource implements UserService {
}
package project.user;
@FeignClient("users")
public interface UserClient extends UserService {
}
@FeignClient 接口不应在服务器和客户端之间共享,并且不再支持在类级别使用 @RequestMapping 注解 @FeignClient 接口。 |
1.10. Feign 请求/响应压缩
您可以考虑为 Feign 请求启用请求或响应 GZIP 压缩。您可以通过启用其中一个属性来实现这一点
spring.cloud.openfeign.compression.request.enabled=true
spring.cloud.openfeign.compression.response.enabled=true
Feign 请求压缩为您提供了类似于您可以为 Web 服务器设置的设置
spring.cloud.openfeign.compression.request.enabled=true
spring.cloud.openfeign.compression.request.mime-types=text/xml,application/xml,application/json
spring.cloud.openfeign.compression.request.min-request-size=2048
这些属性允许您对压缩媒体类型和最小请求阈值长度进行选择性设置。
由于 OkHttpClient 使用“透明”压缩,如果在类路径上存在 feign.okhttp.OkHttpClient 并且 spring.cloud.openfeign.okhttp.enabled 设置为 true,则会禁用此压缩,因为存在 content-encoding 或 accept-encoding 头部。 |
1.11. Feign 日志
为每个创建的 Feign 客户端创建一个日志记录器。默认情况下,日志记录器的名称是用于创建 Feign 客户端的接口的完整类名。Feign 日志记录仅响应 DEBUG 级别。
logging.level.project.user.UserClient: DEBUG
您可以为每个客户端配置的 Logger.Level 对象,它告诉 Feign 要记录多少信息。选项有
-
NONE,不记录任何信息(默认)。 -
BASIC,仅记录请求方法和 URL,以及响应状态码和执行时间。 -
HEADERS,记录基本信息以及请求和响应头。 -
FULL,记录请求和响应的头、正文和元数据。
例如,以下将 Logger.Level 设置为 FULL
@Configuration
public class FooConfiguration {
@Bean
Logger.Level feignLoggerLevel() {
return Logger.Level.FULL;
}
}
1.12. Feign Capability 支持
Feign 能力公开了核心 Feign 组件,以便可以修改这些组件。例如,这些能力可以获取 Client,对其进行 装饰,然后将装饰后的实例返回给 Feign。对 Micrometer 的支持就是一个很好的实际示例。参见 Micrometer 支持。
创建或多个 Capability bean 并将其放在 @FeignClient 配置中,您可以注册它们并修改相关客户端的行为。
@Configuration
public class FooConfiguration {
@Bean
Capability customCapability() {
return new CustomCapability();
}
}
1.13. Micrometer 支持
如果满足以下所有条件,将创建并注册一个 MicrometerObservationCapability bean,以便您的 Feign 客户端可以通过 Micrometer 进行观察
-
类路径上有
feign-micrometer -
ObservationRegistrybean 可用 -
feign micrometer 属性设置为
true(默认)-
spring.cloud.openfeign.micrometer.enabled=true(适用于所有客户端) -
spring.cloud.openfeign.client.config.feignName.micrometer.enabled=true(适用于单个客户端)
-
如果您的应用程序已经使用 Micrometer,启用此功能就像将 feign-micrometer 放在类路径上一样简单。 |
您还可以通过以下方式禁用该功能
-
将
feign-micrometer从类路径中排除 -
将其中一个 feign micrometer 属性设置为
false-
spring.cloud.openfeign.micrometer.enabled=false -
spring.cloud.openfeign.client.config.feignName.micrometer.enabled=false
-
spring.cloud.openfeign.micrometer.enabled=false 会禁用 所有 Feign 客户端的 Micrometer 支持,无论客户端级别标志 spring.cloud.openfeign.client.config.feignName.micrometer.enabled 的值如何。如果您想为每个客户端启用或禁用 Micrometer 支持,请不要设置 spring.cloud.openfeign.micrometer.enabled,而是使用 spring.cloud.openfeign.client.config.feignName.micrometer.enabled。 |
您还可以通过注册自己的 bean 来定制 MicrometerObservationCapability
@Configuration
public class FooConfiguration {
@Bean
public MicrometerObservationCapability micrometerObservationCapability(ObservationRegistry registry) {
return new MicrometerObservationCapability(registry);
}
}
仍然可以使用 MicrometerCapability 与 Feign(仅度量支持),您需要禁用 Micrometer 支持(spring.cloud.openfeign.micrometer.enabled=false)并创建一个 MicrometerCapability bean
@Configuration
public class FooConfiguration {
@Bean
public MicrometerCapability micrometerCapability(MeterRegistry meterRegistry) {
return new MicrometerCapability(meterRegistry);
}
}
1.14. Feign 缓存
如果使用 @EnableCaching 注解,将创建并注册一个 CachingCapability bean,以便您的 Feign 客户端识别其接口上的 @Cache* 注解
public interface DemoClient {
@GetMapping("/demo/{filterParam}")
@Cacheable(cacheNames = "demo-cache", key = "#keyParam")
String demoEndpoint(String keyParam, @PathVariable String filterParam);
}
您也可以通过属性 spring.cloud.openfeign.cache.enabled=false 禁用此功能。
1.15. Feign @QueryMap 支持
Spring Cloud OpenFeign 提供了一个等效的 @SpringQueryMap 注解,用于将 POJO 或 Map 参数注解为查询参数映射。
例如,Params 类定义了参数 param1 和 param2
// Params.java
public class Params {
private String param1;
private String param2;
// [Getters and setters omitted for brevity]
}
以下 feign 客户端使用 @SpringQueryMap 注解使用 Params 类
@FeignClient("demo")
public interface DemoTemplate {
@GetMapping(path = "/demo")
String demoEndpoint(@SpringQueryMap Params params);
}
如果您需要对生成的查询参数映射进行更多控制,您可以实现自定义的 QueryMapEncoder bean。
1.16. HATEOAS 支持
Spring 提供了一些 API 来创建遵循 HATEOAS 原则的 REST 表示,即 Spring Hateoas 和 Spring Data REST。
如果您的项目使用 org.springframework.boot:spring-boot-starter-hateoas starter 或 org.springframework.boot:spring-boot-starter-data-rest starter,则默认启用 Feign HATEOAS 支持。
启用 HATEOAS 支持后,Feign 客户端可以序列化和反序列化 HATEOAS 表示模型:EntityModel、CollectionModel 和 PagedModel。
@FeignClient("demo")
public interface DemoTemplate {
@GetMapping(path = "/stores")
CollectionModel<Store> getStores();
}
1.17. Spring @MatrixVariable 支持
Spring Cloud OpenFeign 提供对 Spring @MatrixVariable 注解的支持。
如果将 Map 作为方法参数传递,则通过将 Map 中的键值对与 = 连接来创建 @MatrixVariable 路径段。
如果传递的是不同的对象,则 @MatrixVariable 注解中提供的 name(如果已定义)或被注解的变量名将与提供的方法参数使用 = 连接。
- 重要
-
尽管在服务器端,Spring 不要求用户将路径段占位符命名为与矩阵变量名相同,但由于在客户端会过于模糊,Spring Cloud OpenFeign 要求您添加一个路径段占位符,其名称与
@MatrixVariable注解中提供的name(如果已定义)或被注解的变量名匹配。
例如:
@GetMapping("/objects/links/{matrixVars}")
Map<String, List<String>> getObjects(@MatrixVariable Map<String, List<String>> matrixVars);
请注意,变量名和路径段占位符都称为 matrixVars。
@FeignClient("demo")
public interface DemoTemplate {
@GetMapping(path = "/stores")
CollectionModel<Store> getStores();
}
1.18. Feign CollectionFormat 支持
我们通过提供 @CollectionFormat 注解来支持 feign.CollectionFormat。您可以通过将所需的 feign.CollectionFormat 作为注解值传递来注解 Feign 客户端方法(或整个类以影响所有方法)。
在以下示例中,使用 CSV 格式而不是默认的 EXPLODED 来处理方法。
@FeignClient(name = "demo")
protected interface DemoFeignClient {
@CollectionFormat(feign.CollectionFormat.CSV)
@GetMapping(path = "/test")
ResponseEntity performRequest(String test);
}
1.19. 响应式支持
由于 OpenFeign 项目 目前不支持响应式客户端,例如 Spring WebClient,Spring Cloud OpenFeign 也不支持。一旦核心项目中可用,我们将在此时添加支持。
在此之前,我们建议使用 feign-reactive 来支持 Spring WebClient。
1.19.1. 早期初始化错误
我们不鼓励在应用程序生命周期的早期阶段使用 Feign 客户端,例如在处理配置和初始化 bean 时。在 bean 初始化期间使用客户端是不受支持的。
同样,根据您使用 Feign 客户端的方式,您可能会在启动应用程序时看到初始化错误。为了解决这个问题,您可以在自动装配客户端时使用 ObjectProvider。
@Autowired
ObjectProvider<TestFeignClient> testFeignClient;
1.20. Spring Data 支持
如果类路径上有 Jackson Databind 和 Spring Data Commons,则会自动添加 org.springframework.data.domain.Page 和 org.springframework.data.domain.Sort 的转换器。
要禁用此行为,请设置
spring.cloud.openfeign.autoconfiguration.jackson.enabled=false
有关详细信息,请参阅 org.springframework.cloud.openfeign.FeignAutoConfiguration.FeignJacksonConfiguration。
1.21. Spring @RefreshScope 支持
如果 Feign 客户端刷新已启用,则每个 Feign 客户端都使用以下方式创建
-
feign.Request.Options作为刷新范围的 bean。这意味着connectTimeout和readTimeout等属性可以针对任何 Feign 客户端实例进行刷新。 -
URL 封装在
org.springframework.cloud.openfeign.RefreshableUrl下。这意味着 Feign 客户端的 URL(如果使用spring.cloud.openfeign.client.config.{feignName}.url属性定义)可以针对任何 Feign 客户端实例进行刷新。
您可以通过 POST /actuator/refresh 刷新这些属性。
默认情况下,Feign 客户端中的刷新行为是禁用的。使用以下属性启用刷新行为
spring.cloud.openfeign.client.refresh-enabled=true
请勿使用 @RefreshScope 注解 @FeignClient 接口。 |
1.22. OAuth2 支持
可以通过向项目添加 spring-boot-starter-oauth2-client 依赖项并设置以下标志来启用 OAuth2 支持
spring.cloud.openfeign.oauth2.enabled=true
当该标志设置为 true 并且存在 OAuth2 客户端上下文资源详细信息时,将创建一个 OAuth2AccessTokenInterceptor 类的 bean。在每个请求之前,拦截器解析所需的访问令牌并将其作为请求头包含。OAuth2AccessTokenInterceptor 使用 OAuth2AuthorizedClientManager 获取包含 OAuth2AccessToken 的 OAuth2AuthorizedClient。如果用户已使用 spring.cloud.openfeign.oauth2.clientRegistrationId 属性指定了 OAuth2 clientRegistrationId,则将使用它来检索令牌。如果未检索到令牌或未指定 clientRegistrationId,则将使用从 url 主机段检索到的 serviceId。
- 提示
-
将
serviceId用作 OAuth2 客户端注册 ID 对于负载均衡的 Feign 客户端很方便。对于非负载均衡的客户端,基于属性的clientRegistrationId是一种合适的方法。 - 提示
-
如果您不想使用
OAuth2AuthorizedClientManager的默认设置,您可以在配置中实例化此类型的 bean。
1.23. 转换负载均衡的 HTTP 请求
您可以使用选定的 ServiceInstance 来转换负载均衡的 HTTP 请求。
对于 Request,您需要实现并定义 LoadBalancerFeignRequestTransformer,如下所示
@Bean
public LoadBalancerFeignRequestTransformer transformer() {
return new LoadBalancerFeignRequestTransformer() {
@Override
public Request transformRequest(Request request, ServiceInstance instance) {
Map<String, Collection<String>> headers = new HashMap<>(request.headers());
headers.put("X-ServiceId", Collections.singletonList(instance.getServiceId()));
headers.put("X-InstanceId", Collections.singletonList(instance.getInstanceId()));
return Request.create(request.httpMethod(), request.url(), headers, request.body(), request.charset(),
request.requestTemplate());
}
};
}
如果定义了多个转换器,它们将按照 bean 定义的顺序应用。或者,您可以使用 LoadBalancerFeignRequestTransformer.DEFAULT_ORDER 来指定顺序。
1.24. X-Forwarded Headers 支持
可以通过设置以下标志来启用 X-Forwarded-Host 和 X-Forwarded-Proto 支持
spring.cloud.loadbalancer.x-forwarded.enabled=true
1.25. 向 Feign 客户端提供 URL 的支持方式
您可以通过以下任何一种方式向 Feign 客户端提供 URL
| 情况 | 示例 | 详细信息 |
|---|---|---|
URL 在 |
|
URL 从注解的 |
URL 在 |
|
URL 从注解的 |
URL 未在 |
|
URL 从配置属性解析,不进行负载均衡。如果 |
URL 既未在 |
|
URL 从注解的 |
1.26. AOT 和 Native Image 支持
Spring Cloud OpenFeign 支持 Spring AOT 转换和 native image,但仅限于禁用刷新模式、禁用 Feign 客户端刷新(默认设置)和禁用 延迟 @FeignClient 属性解析(默认设置)的情况。
如果您想在 AOT 或 native image 模式下运行 Spring Cloud OpenFeign 客户端,请务必将 spring.cloud.refresh.enabled 设置为 false。 |
如果您想在 AOT 或 native image 模式下运行 Spring Cloud OpenFeign 客户端,请确保 spring.cloud.openfeign.client.refresh-enabled 未设置为 true。 |
如果您想在 AOT 或 native image 模式下运行 Spring Cloud OpenFeign 客户端,请确保 spring.cloud.openfeign.lazy-attributes-resolution 未设置为 true。 |
但是,如果您通过属性设置 url 值,则可以通过使用 -Dspring.cloud.openfeign.client.config.[clientId].url=[url] 标志运行镜像来覆盖 @FeignClient 的 url 值。为了启用覆盖,在构建时也必须通过属性而不是 @FeignClient 属性设置 url 值。 |