4.0.4

该项目通过自动配置和绑定到 Spring 环境和其他 Spring 编程模型习惯用法,为 Spring Boot 应用程序提供 OpenFeign 集成。

1.声明式REST客户端:Feign

Feign是一个声明式 Web 服务客户端。它使编写 Web 服务客户端变得更加容易。要使用 Feign 创建一个接口并对其进行注释。它具有可插入的注释支持,包括 Feign 注释和 JAX-RS 注释。Feign 还支持可插入的编码器和解码器。Spring Cloud 添加了对 Spring MVC 注释以及使用HttpMessageConvertersSpring Web 中默认使用的注释的支持。Spring Cloud集成了Eureka、Spring Cloud CircuitBreaker以及Spring Cloud LoadBalancer,在使用Feign时提供负载均衡的http客户端。

1.1. 如何包含 Feign

org.springframework.cloud 要将 Feign 包含在您的项目中,请使用带有组和工件 id 的启动器spring-cloud-starter-openfeign。 有关使用当前 Spring Cloud 发布系列设置构建系统的详细信息,请参阅Spring Cloud 项目页面。

示例 Spring Boot 应用程序

@SpringBootApplication
@EnableFeignClients
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}
商店客户端.java
@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 的名称是接口的完全限定名称。要指定您自己的别名值,您可以使用注释qualifiers的值@FeignClient

上面的负载平衡器客户端将希望发现“stores”服务的物理地址。如果您的应用程序是 Eureka 客户端,那么它将解析 Eureka 服务注册表中的服务。如果您不想使用 Eureka,您可以使用 在外部配置中配置服务器列表SimpleDiscoveryClient

Spring Cloud OpenFeign 支持 Spring Cloud LoadBalancer 阻塞模式的所有可用功能。您可以在项目文档中阅读有关它们的更多信息。

要在 -annotated-classes 上使用@EnableFeignClients注释@Configuration,请确保指定客户端所在的位置,例如: @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 支持的核心概念是指定客户端。每个假客户端都是组件集合的一部分,这些组件协同工作以按需联系远程服务器,并且该集合有一个名称,您作为应用程序开发人员使用注释为其指定名称@FeignClient。Spring Cloud 根据 ApplicationContext需要为每个使用FeignClientsConfiguration. 其中包含(除其他外) an feign.Decoder、 afeign.Encoder和 a feign.Contract。可以使用注释contextId 的属性来覆盖该集合的名称@FeignClient

Spring Cloud 允许您通过使用 声明附加配置(在 之上FeignClientsConfiguration)来完全控制 feign 客户端@FeignClient。例子:

@FeignClient(name = "stores", configuration = FooConfiguration.class)
public interface StoreClient {
    //..
}

在这种情况下,客户端由已有的组件FeignClientsConfiguration和任何 in组成FooConfiguration(后者将覆盖前者)。

FooConfiguration不需要用 来注释@Configuration。但是,如果是,请注意将其从任何@ComponentScan包含此配置的配置中排除,因为在指定时它将成为feign.Decoderfeign.Encoderfeign.Contract等的默认源。可以通过将其与任何@ComponentScan或放在单独的、不重叠的包中来避免这种情况@SpringBootApplication,或者可以将其显式排除在 中@ComponentScan
使用注释contextId的属性@FeignClient除了更改ApplicationContext集合的名称之外,还将覆盖客户端名称的别名,并将用作为该客户端创建的配置 bean 的名称的一部分。
以前,使用该url属性时不需要该name属性。name现在需要 使用。

name和属性支持占位符url

@FeignClient(name = "${feign.name}", url = "${feign.url}")
public interface StoreClient {
    //..
}

Spring Cloud OpenFeign 默认为 feign 提供以下 bean ( BeanTypebeanName: ClassName):

  • DecoderfeignDecoder:(ResponseEntityDecoder包装了一个SpringDecoder

  • Encoder假装编码器:SpringEncoder

  • Logger假装记录器:Slf4jLogger

  • MicrometerObservationCapabilitymicrometerObservationCapability:如果feign-micrometer位于类路径上并且ObservationRegistry可用

  • MicrometerCapabilitymicrometerCapability:如果feign-micrometer在类路径上,MeterRegistry则可用,ObservationRegistry不可用

  • CachingCapabilitycachingCapability:如果@EnableCaching使用注释。可以通过禁用spring.cloud.openfeign.cache.enabled

  • Contract假合同:SpringMvcContract

  • Feign.Builder假装建造者:FeignCircuitBreaker.Builder

  • ClientfeignClient:如果 Spring Cloud LoadBalancer 位于类路径上,FeignBlockingLoadBalancerClient则使用。如果它们都不在类路径上,则使用默认的 feign 客户端。

spring-cloud-starter-openfeign支持spring-cloud-starter-loadbalancer. 但是,作为一个可选依赖项,如果您想使用它,您需要确保它已添加到您的项目中。

spring.cloud.openfeign.okhttp.enabledOkHttpClient 和 Apache HttpClient 5 Feign 客户端可以通过分别设置或spring.cloud.openfeign.httpclient.hc5.enabled并将true它们放在类路径中来使用。org.apache.hc.client5.http.impl.classic.CloseableHttpClient在使用 Apache HC5 时,您可以通过提供任一 bean 来自定义所使用的 HTTP 客户端。

您可以通过设置属性中的值来进一步自定义 http 客户端spring.cloud.openfeign.httpclient.xxx。前缀为 的客户端httpclient适用于所有客户端,前缀为httpclient.hc5Apache HttpClient 5 的客户端以及前缀为httpclient.okhttpOkHttpClient 的客户端。您可以在附录中找到可自定义的属性的完整列表。

从 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

  • CapabilityMicrometerObservationCapability并且CachingCapability默认提供)

默认情况下会创建Retryer.NEVER_RETRY具有该类型的 bean ,这将禁用重试。Retryer请注意,此重试行为与 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.Defaulta 添加RequestInterceptor到 的集合中RequestInterceptor

@FeignClient也可以使用配置属性进行配置。

应用程序.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将用于检索实例的服务器应用程序的 。

可以按照与上述类似的方式在@EnableFeignClients属性中指定默认配置。defaultConfiguration不同之处在于此配置将适用于所有feign 客户端。

如果您更喜欢使用配置属性来配置 all @FeignClient,您可以使用defaultfeign 名称创建配置属性。

您可以使用spring.cloud.openfeign.client.config.feignName.defaultQueryParametersspring.cloud.openfeign.client.config.feignName.defaultRequestHeaders来指定将随名为 的客户端的每个请求一起发送的查询参数和标头feignName

应用程序.yml

spring:
    cloud:
        openfeign:
            client:
                config:
                    default:
                        connectTimeout: 5000
                        readTimeout: 5000
                        loggerLevel: basic

如果我们同时创建@Configurationbean 和配置属性,则配置属性将获胜。它将覆盖@Configuration值。但如果你想把优先级改成@Configuration,你可以spring.cloud.openfeign.client.default-to-properties改成false

如果我们想创建多个具有相同名称或 url 的 feign 客户端,以便它们指向同一服务器,但每个客户端具有不同的自定义配置,那么我们必须使用 的 属性,以避免这些配置 bean 的名称contextId冲突@FeignClient

@FeignClient(contextId = "fooClient", name = "stores", configuration = FooConfiguration.class)
public interface FooClient {
    //..
}
@FeignClient(contextId = "barClient", name = "stores", configuration = BarConfiguration.class)
public interface BarClient {
    //..
}

还可以配置 FeignClient 不从父上下文继承 bean。您可以通过覆盖beaninheritParentConfiguration()中的 FeignClientConfigurer return 来做到这一点false

@Configuration
public class CustomConfiguration{

@Bean
public FeignClientConfigurer feignClientConfigurer() {
            return new FeignClientConfigurer() {

                @Override
                public boolean inheritParentConfiguration() {
                    return false;
                }
            };

        }
}
默认情况下,Feign 客户端不对斜杠/字符进行编码。spring.cloud.openfeign.client.decodeSlash您可以通过设置to的值来更改此行为false

1.2.1. SpringEncoder配置

SpringEncoder我们提供的文件中,我们null为二进制内容类型和UTF-8所有其他内容设置字符集。

您可以修改此行为以从标头字符集派生字符集,Content-Type而不是通过将值设置为spring.cloud.openfeign.encoder.charset-from-content-typeto true

1.3. 超时处理

我们可以在默认客户端和指定客户端上配置超时。OpenFeign 使用两个超时参数:

  • connectTimeout防止由于服务器处理时间过长而阻塞调用者。

  • readTimeout从连接建立时开始应用,当返回响应时间过长时触发。

如果服务器未运行或不可用,数据包将导致连接被拒绝。通信会以错误消息或回退结束。如果它设置得很低,这可能会在之前发生。connectTimeout执行查找和接收此类数据包所花费的时间导致了此延迟的很大一部分。它可能会根据涉及 DNS 查找的远程主机而发生变化。

1.4. 手动创建假客户端

在某些情况下,可能需要以使用上述方法无法实现的方式自定义您的 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是客户端将请求的服务的名称。
FeignContract对象定义了接口上哪些注释和值是有效的。自动装配Contractbean 提供对 SpringMVC 注释的支持,而不是默认的 Feign 原生注释。

您还可以使用Builder`to configure FeignClient not to inherit beans from the parent context. You can do this by overriding calling `inheritParentContext(false)上的Builder.

1.5. Feign Spring Cloud 断路器支持

如果 Spring Cloud CircuitBreaker 位于类路径中并且spring.cloud.openfeign.circuitbreaker.enabled=true,Feign 将会用断路器包装所有方法。

要在每个客户端上禁用 Spring Cloud CircuitBreaker 支持,请创建一个Feign.Builder具有“原型”范围的普通版本,例如:

@Configuration
public class FooConfiguration {
    @Bean
    @Scope("prototype")
    public Feign.Builder feignBuilder() {
        return Feign.builder();
    }
}

断路器的名称遵循这种模式<feignClientClassName>#<calledMethod>(<parameterTypes>)。当调用@FeignClientwithFooClient接口并且被调用的没有参数的接口方法时,bar断路器名称将为FooClient#bar()

截至 2020.0.2,断路器名称模式已从<feignClientName>_<calledMethod>. 使用CircuitBreakerNameResolver2020.0.4引入的断路器名称可以保留旧模式。

提供 的 bean CircuitBreakerNameResolver,您可以更改断路器名称模式。

@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. 使用配置属性配置断路器

您可以通过配置属性配置断路器。

例如,如果您有这个 Feign 客户端

@FeignClient(url = "http://localhost: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.enabledfalse

1.7. Feign Spring Cloud 断路器回退

Spring Cloud CircuitBreaker 支持回退的概念:当电路打开或出现错误时执行的默认代码路径。要启用给定的回退,@FeignClient请将属性设置fallback为实现回退的类名称。您还需要将您的实现声明为 Spring bean。

@FeignClient(name = "test", url = "http://localhost:${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";
        }

    }

如果需要访问触发回退的原因,可以使用fallbackFactory中的属性@FeignClient

@FeignClient(name = "testClientWithFactory", url = "http://localhost:${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. 假装和@Primary

ApplicationContext当使用 Feign 和 Spring Cloud CircuitBreaker 回退时,同一类型中有多个 bean 。这将导致@Autowired无法工作,因为没有一个 Bean 或标记为主要的 Bean。为了解决这个问题,Spring Cloud OpenFeign 将所有 Feign 实例标记为@Primary,以便 Spring Framework 知道要注入哪个 bean。在某些情况下,这可能是不可取的。要关闭此行为,请将primary的属性设置@FeignClient为 false。

@FeignClient(name = "hello", primary = false)
public interface HelloClient {
    // methods here
}

1.9. Feign 继承支持

Feign 通过单继承接口支持样板 API。这允许将常见操作分组到方便的基本接口中。

用户服务.java
public interface UserService {

    @RequestMapping(method = RequestMethod.GET, value ="/users/{id}")
    User getUser(@PathVariable("id") long id);
}
用户资源.java
@RestController
public class UserResource implements UserService {

}
用户客户端.java
package project.user;

@FeignClient("users")
public interface UserClient extends UserService {

}
@FeignClient接口不应在服务器和客户端之间共享,并且不再支持在类级别 注释@FeignClient接口。@RequestMapping

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 使用“透明”压缩,如果存在content-encoding或标头,则禁用该压缩,因此当存在于类路径中并设置为accept-encoding时,我们不会启用压缩。 feign.okhttp.OkHttpClientspring.cloud.openfeign.okhttp.enabledtrue

1.11. 假日志记录

为每个创建的 Feign 客户端创建一个记录器。默认情况下,记录器的名称是用于创建 Feign 客户端的接口的完整类名。假日志仅响应级别DEBUG

应用程序.yml
logging.level.project.user.UserClient: DEBUG

您可以为每个客户端配置的对象Logger.Level,告诉 Feign 要记录多少内容。选项有:

  • NONE, 不记录(默认)。

  • BASIC,仅记录请求方法和URL以及响应状态码和执行时间。

  • HEADERS,记录基本信息以及请求和响应标头。

  • FULL,记录请求和响应的标头、正文和元数据。

例如,以下将设置Logger.LevelFULL

@Configuration
public class FooConfiguration {
    @Bean
    Logger.Level feignLoggerLevel() {
        return Logger.Level.FULL;
    }
}

1.12. Feign 能力支持

Feign 能力暴露核心 Feign 组件,以便可以修改这些组件。例如,功能可以获取Client装饰它,并将装饰后的实例返回给 Feign。对 Micrometer 的支持就是一个很好的现实例子。请参阅千分尺支持

创建一个或多个Capabilitybean 并将它们放入@FeignClient配置中可以让您注册它们并修改相关客户端的行为。

@Configuration
public class FooConfiguration {
    @Bean
    Capability customCapability() {
        return new CustomCapability();
    }
}

1.13。千分尺支持

如果满足以下所有条件,MicrometerObservationCapability则会创建并注册一个 bean,以便 Micrometer 可以观察您的 Feign 客户端:

  • feign-micrometer在类路径上

  • 有豆ObservationRegistry可用

  • feign 千分尺属性设置为true(默认情况下)

    • spring.cloud.openfeign.micrometer.enabled=true(适用于所有客户)

    • spring.cloud.openfeign.client.config.feignName.micrometer.enabled=true(针对单个客户)

如果您的应用程序已经使用 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

MicrometerObservationCapability您还可以通过注册自己的 bean来自定义:

@Configuration
public class FooConfiguration {
    @Bean
    public MicrometerObservationCapability micrometerObservationCapability(ObservationRegistry registry) {
        return new MicrometerObservationCapability(registry);
    }
}

仍然可以MicrometerCapability与 Feign 一起使用(仅支持指标),您需要禁用 Micrometer 支持 ( spring.cloud.openfeign.micrometer.enabled=false) 并创建一个MicrometerCapabilitybean:

@Configuration
public class FooConfiguration {
    @Bean
    public MicrometerCapability micrometerCapability(MeterRegistry meterRegistry) {
        return new MicrometerCapability(meterRegistry);
    }
}

1.14. 假缓存

如果@EnableCaching使用注释,CachingCapability则会创建并注册一个 bean,以便您的 Feign 客户端识别@Cache*其接口上的注释:

public interface DemoClient {

    @GetMapping("/demo/{filterParam}")
    @Cacheable(cacheNames = "demo-cache", key = "#keyParam")
    String demoEndpoint(String keyParam, @PathVariable String filterParam);
}

您还可以通过 property 禁用该功能spring.cloud.openfeign.cache.enabled=false

1.15。假装 @QueryMap 支持

Spring Cloud OpenFeign 提供了等效的@SpringQueryMap注解,用于将 POJO 或 Map 参数注解为查询参数映射。

例如,该类Params定义参数param1param2

// Params.java
public class Params {
    private String param1;
    private String param2;

    // [Getters and setters omitted for brevity]
}

以下 feign 客户端Params通过使用@SpringQueryMap注释来使用该类:

@FeignClient("demo")
public interface DemoTemplate {

    @GetMapping(path = "/demo")
    String demoEndpoint(@SpringQueryMap Params params);
}

如果您需要对生成的查询参数映射进行更多控制,您可以实现自定义QueryMapEncoderbean。

1.16。HATEOAS 支持

Spring 提供了一些 API 来创建遵循HATEOAS原则、Spring HateoasSpring Data REST 的REST 表示形式。

如果您的项目使用org.springframework.boot:spring-boot-starter-hateoasstarter 或org.springframework.boot:spring-boot-starter-data-reststarter,则默认启用 Feign HATEOAS 支持。

启用 HATEOAS 支持后,Feign 客户端可以序列化和反序列化 HATEOAS 表示模型:EntityModelCollectionModelPagedModel

@FeignClient("demo")
public interface DemoTemplate {

    @GetMapping(path = "/stores")
    CollectionModel<Store> getStores();
}

1.17。Spring @MatrixVariable 支持

Spring Cloud OpenFeign 提供对 Spring@MatrixVariable注解的支持。

如果将映射作为方法参数传递,@MatrixVariable则通过将映射中的键值对与=.

如果传递了不同的对象,则注释name中提供的@MatrixVariable(如果已定义)或注释的变量名称将使用 与提供的方法参数连接=

IMPORTANT

尽管在服务器端,Spring 不要求用户将路径段占位符命名为与矩阵变量名称相同,因为在客户端这会太模糊,Spring Cloud OpenFeign 要求您添加一个路径段占位符与注释name中提供的名称@MatrixVariable(如果已定义)或带注释的变量名称匹配的名称。

例如:

@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。假装CollectionFormat支持

我们feign.CollectionFormat通过提供@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 客户端的方式,您可能会在启动应用程序时看到初始化错误。要解决此问题,您可以使用ObjectProvider自动装配客户端时的方法。

@Autowired
ObjectProvider<TestFeignClient> testFeignClient;

1.20. Spring数据支持

如果 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。弹簧@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
不要用注释@FeignClient来注释接口@RefreshScope

1.22. OAuth2 支持

可以通过设置以下标志来启用 OAuth2 支持:

spring.cloud.openfeign.oauth2.enabled=true

当该标志设置为 true,并且存在 oauth2 客户端上下文资源详细信息时,OAuth2AccessTokenInterceptor将创建一个 Bean 类。在每个请求之前,拦截器都会解析所需的访问令牌并将其作为标头包含在内。 OAuth2AccessTokenInterceptor使用 来OAuth2AuthorizedClientManager获取OAuth2AuthorizedClient持有OAuth2AccessToken. 如果用户clientRegistrationId使用该spring.cloud.openfeign.oauth2.clientRegistrationId属性指定了 OAuth2,它将用于检索令牌。如果未检索到令牌或未clientRegistrationId指定,则将使用serviceId从主机段检索到的令牌。url

TIP

使用serviceIdOAuth2客户端registrationId对于负载均衡的Feign客户端来说很方便。对于非负载平衡的方法,基于属性clientRegistrationId是一种合适的方法。

TIP

如果您不想使用默认设置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 标头支持

X-Forwarded-HostX-Forwarded-Proto可以通过设置以下标志来启用支持:

spring.cloud.loadbalancer.x-forwarded.enabled=true

1.25。向虚拟客户端提供 URL 的受支持方法

您可以通过以下任一方式向 Feign 客户端提供 URL:

案件 例子 细节

URL 在@FeignClient注释中提供。

@FeignClient(name="testClient", url="http://localhost:8081")

URL是从url注释的属性解析的,没有负载平衡。

URL 在@FeignClient注释和配置属性中提供。

@FeignClient(name="testClient", url="http://localhost:8081")application.yml以及定义为的 属性spring.cloud.openfeign.client.config.testClient.url=http://localhost:8081

URL是从url注释的属性解析的,没有负载平衡。配置属性中提供的 URL 保持未使用状态。

URL 未在@FeignClient注释中提供,但在配置属性中提供。

@FeignClient(name="testClient")application.yml以及定义为的 属性spring.cloud.openfeign.client.config.testClient.url=http://localhost:8081

URL 从配置属性解析,无需负载平衡。如果是 ,则可以按照Spring RefreshScope 支持spring.cloud.openfeign.client.refresh-enabled=true中的描述刷新配置属性中定义的 URL 。

注释和配置属性中均未提供 URL @FeignClient

@FeignClient(name="testClient")

URL是从nameannotation的属性解析出来的,具有负载均衡功能。

1.26。AOT 和本机映像支持

Spring Cloud OpenFeign 支持 Spring AOT 转换和原生图像,但是,仅在禁用刷新模式、禁用 Feign 客户端刷新(默认设置)和禁用惰性@FeignClient属性解析(默认设置)的情况下。

如果您想以 AOT 或本机图像模式运行 Spring Cloud OpenFeign 客户端,请确保设置spring.cloud.refresh.enabledfalse
如果您想以 AOT 或本机镜像模式运行 Spring Cloud OpenFeign 客户端,请确保spring.cloud.openfeign.client.refresh-enabled尚未设置为true
如果您想以 AOT 或本机镜像模式运行 Spring Cloud OpenFeign 客户端,请确保spring.cloud.openfeign.lazy-attributes-resolution尚未设置为true
但是,如果通过属性设置该url值,则可以@FeignClient url通过运行带有标志的图像来覆盖该值-Dspring.cloud.openfeign.client.config.[clientId].url=[url]。为了启用覆盖,url还必须@FeignClient在构建时通过属性而不是属性设置值。

2. 配置属性

要查看所有 Spring Cloud OpenFeign 相关配置属性的列表,请查看附录页面