Spring Cloud OpenFeign

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

声明式 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 客户端。

如何包含 Feign

要将 Feign 包含在您的项目中，请使用带有 grouporg.springframework.cloud 和 artifact id的 starter spring-cloud-starter-openfeign。

示例 Spring Boot 应用程序

@SpringBootApplication
@EnableFeignClients
public class Application {

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

}

StoreClient.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注解中，String 值（上面的“stores”）是一个任意的客户端名称，用于创建Spring Cloud LoadBalancer 客户端。您还可以使用url属性（绝对值或仅主机名）指定 URL。应用程序上下文中 bean 的名称是接口的完全限定名称。要指定您自己的别名值，您可以使用注释的qualifiers值。@FeignClient

上面的负载均衡器客户端将想要发现“存储”服务的物理地址。如果您的应用程序是 Eureka 客户端，那么它将解析 Eureka 服务注册表中的服务。如果您不想使用 Eureka，可以使用SimpleDiscoveryClient

Spring Cloud OpenFeign 支持 Spring Cloud LoadBalancer 的阻塞模式可用的所有功能。

覆盖 Feign 默认值

Spring Cloud 的 Feign 支持的一个核心概念是命名客户端。每个 feign 客户端都是组件集合的一部分，这些组件协同工作以按需联系远程服务器，并且集合具有一个名称，您作为应用程序开发人员使用@FeignClient注释为其命名。Spring Cloud ApplicationContext使用FeignClientsConfiguration. 这包含（除其他外）feign.Decoder、feign.Encoder和feign.Contract。可以通过使用注释的contextId属性来覆盖该集合的名称。@FeignClient`

Spring Cloud 允许您通过FeignClientsConfiguration使用@FeignClient. 例子：

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

在这种情况下，客户端由已经存在的组件FeignClientsConfiguration和任何组成FooConfiguration（后者将覆盖前者）。

FooConfiguration不需要用 注释@Configuration。但是，如果是，请注意将其从任何@ComponentScan包含此配置的内容中排除，因为在指定时它将成为feign.Decoder默认feign.Encoder来源feign.Contract。这可以通过将它与任何@ComponentScanor放在一个单独的、不重叠的包中来避免@SpringBootApplication，或者它可以被明确地排除在@ComponentScan`.

除了更改整体的名称之外， 使用注释的contextId属性，它将覆盖客户端名称的别名，并将用作为该客户端创建的配置 bean 的名称的一部分。

name和url属性支持占位符。

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

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

• DecoderfeignDecoder: ResponseEntityDecoder（包装 a SpringDecoder）
• Encoder 编码器： SpringEncoder
• Logger 记录器： Slf4jLogger
• MicrometerCapabilitymicrometerCapability：如果feign-micrometer在类路径上并且MeterRegistry可用
• CachingCapabilitycacheCapability：如果@EnableCaching使用了注解。可以通过 禁用feign.cache.enabled。
• Contract 合同： SpringMvcContract
• Feign.Builder feignBuilder： FeignCircuitBreaker.Builder
• ClientfeignClient：如果 Spring Cloud LoadBalancer 在类路径上，FeignBlockingLoadBalancerClient则使用。如果它们都不在类路径上，则使用默认的 feign 客户端。

OkHttpClient 和 ApacheHttpClient 和 ApacheHC5 feign 客户端可以通过分别设置feign.okhttp.enabledorfeign.httpclient.enabled或feign.httpclient.hc5.enabledto来使用true，并将它们放在类路径中。org.apache.http.impl.client.CloseableHttpClient您可以通过在使用 Apache 或okhttp3.OkHttpClient使用 OK HTTP 或org.apache.hc.client5.http.impl.classic.CloseableHttpClient使用 Apache HC5 时提供 bean 来自定义使用的 HTTP 客户端。

Spring Cloud OpenFeign默认不为 feign提供以下 bean，但仍会从应用上下文中查找这些类型的 bean 来创建 feign 客户端：

• Logger.Level
• Retryer
• ErrorDecoder
• Request.Options
• Collection
• SetterFactory
• QueryMapEncoder
• Capability（MicrometerCapability并且CachingCapability默认提供）

Retryer.NEVER_RETRY默认情况下会创建一个具有该类型的 bean Retryer，这将禁用重试。请注意，这种重试行为与 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");
    }
}

这将替换SpringMvcContractwithfeign.Contract.Default并将 添加RequestInterceptor到 的集合中RequestInterceptor。

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

应用程序.yml

feign:
    client:
        config:
            feignName:
                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
                decode404: false
                encoder: com.example.SimpleEncoder
                decoder: com.example.SimpleDecoder
                contract: com.example.SimpleContract
                capabilities:
                    - com.example.FooCapability
                    - com.example.BarCapability
                metrics.enabled: false

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

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

您可以使用feign.client.config.feignName.defaultQueryParametersandfeign.client.config.feignName.defaultRequestHeaders指定将随名为feignName.

应用程序.yml

feign:
    client:
        config:
            default:
                connectTimeout: 5000
                readTimeout: 5000
                loggerLevel: basic

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

如果我们想创建多个具有相同名称或 url 的 feign 客户端，以便它们指向同一个服务器，但每个都有不同的自定义配置，那么我们必须使用contextId的属性@FeignClient以避免这些配置 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。您可以通过覆盖 bean 来执行此操作inheritParentConfiguration()以FeignClientConfigurer 返回false：

@Configuration
public class CustomConfiguration{

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

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

        }
}

SpringEncoder配置

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

您可以修改此行为以从Content-Type标头字符集派生字符集，而不是通过将值设置为feign.encoder.charset-from-content-type= true。

超时处理

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

• connectTimeout 防止由于服务器处理时间长而阻塞调用者。
• readTimeout 从连接建立时开始应用，在返回响应时间过长时触发。

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

手动创建 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, MicrometerCapability micrometerCapability) {
        this.fooClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .addCapability(micrometerCapability)
                .requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
                .target(FooClient.class, "https://PROD-SVC");

        this.adminClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .addCapability(micrometerCapability)
                .requestInterceptor(new BasicAuthRequestInterceptor("admin", "admin"))
                .target(FooClient.class, "https://PROD-SVC");
    }
}

上例FeignClientsConfiguration.class中是 Spring Cloud OpenFeign 提供的默认配置。

FeignContract对象定义了哪些注解和值在接口上是有效的。自动装配的Contractbean 提供对 SpringMVC 注解的支持，而不是默认的 Feign 原生注解。

断路器支持

如果 Spring Cloud CircuitBreaker 在 classpath 上，并且feign.circuitbreaker.enabled=trueFeign 将使用断路器包装所有方法。

要在每个客户端上禁用 Spring Cloud CircuitBreaker 支持，请创建一个Feign.Builder具有“原型”范围的变量，例如：

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

断路器名称遵循此模式#()。当调用一个@FeignClient带有FooClient接口并且被调用的没有参数的接口方法时，bar断路器名称将是FooClient#bar()。

提供一个 bean CircuitBreakerNameResolver，您可以更改断路器名称模式。

@Configuration
public class FooConfiguration {
    @Bean
    public CircuitBreakerNameResolver circuitBreakerNameResolver() {
        return (String feignClientName, Target<?> target, Method method) -> feignClientName + "_" + method.getName();
    }
}

要启用 Spring Cloud CircuitBreaker 组，请将feign.circuitbreaker.group.enabled属性设置为true（默认情况下false）。

断路器回退

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";
        }

    }

@Primary

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

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

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

Feign 请求/响应压缩

您可以考虑为您的 Feign 请求启用请求或响应 GZIP 压缩。您可以通过启用以下属性之一来做到这一点：

feign.compression.request.enabled=true
feign.compression.response.enabled=true

Feign 请求压缩为您提供类似于您为 Web 服务器设置的设置：

feign.compression.request.enabled=true
feign.compression.request.mime-types=text/xml,application/xml,application/json
feign.compression.request.min-request-size=2048

这些属性允许您选择压缩媒体类型和最小请求阈值长度。

Feign 日志记录

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

应用程序.yml

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;
    }
}

Feign 能力支持

Feign 功能公开了核心 Feign 组件，以便可以修改这些组件。例如，功能可以获取Client，装饰它，并将装饰的实例返回给 Feign。对度量库的支持就是一个很好的现实例子。

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

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

Feign 指标

如果以下所有条件都为真，MicrometerCapability则会创建并注册一个bean，以便您的 Feign 客户端将指标发布到 Micrometer：

• feign-micrometer在类路径上
• 有一个MeterRegistry
• feign 指标属性设置为true（默认情况下）
  • feign.metrics.enabled=true（适用于所有客户）
  • feign.client.config.feignName.metrics.enabled=true（针对单个客户）

如果您的应用程序已经使用了 Micrometer，那么启用指标就像放入feign-micrometer您的类路径一样简单。

您也可以通过以下任一方式禁用该功能：

• feign-micrometer从你的类路径中排除

• 将 feign 度量属性之一设置为false

  • feign.metrics.enabled=false
  • feign.client.config.feignName.metrics.enabled=false

  feign.metrics.enabled=false无论客户端级别标志的值如何，都禁用对所有Feign 客户端的指标支持feign.client.config.feignName.metrics.enabled：如果要为每个客户端启用或禁用 merics，请不要设置feign.metrics.enabled和使用feign.client.config.feignName.metrics.enabled.

您还可以MicrometerCapability通过注册自己的 bean 来自定义：

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

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);
}

您还可以通过 property 禁用该功能feign.cache.enabled=false。

Feign @QueryMap 支持

OpenFeign@QueryMap注解支持将 POJO 用作 GET 参数映射。不幸的是，默认的 OpenFeign QueryMap 注解与 Spring 不兼容，因为它缺少value属性。

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 客户端通过注解使用Params该类：@SpringQueryMap

@FeignClient("demo")
public interface DemoTemplate {

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

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

HATEOAS 支持

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

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

启用 HATEOAS 支持后，允许 Feign 客户端序列化和反序列化 HATEOAS 表示模型：EntityModel、CollectionModel和PagedModel。

@FeignClient("demo")
public interface DemoTemplate {

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

Spring @MatrixVariable 支持

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

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

如果传递了不同的对象，name则注释中提供的@MatrixVariable（如果已定义）或带注释的变量名称使用=.

• 重要的

  即使在服务器端，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();
}

CollectionFormat支持

我们feign.CollectionFormat通过提供@CollectionFormat注释来支持。您可以通过传递所需feign.CollectionFormat的注释值来注释 Feign 客户端方法（或影响所有方法的整个类）。

在以下示例中，使用CSV格式而不是默认格式EXPLODED来处理方法。

@FeignClient(name = "demo")
protected interface PageableFeignClient {

    @CollectionFormat(feign.CollectionFormat.CSV)
    @GetMapping(path = "/page")
    ResponseEntity performRequest(Pageable page);

}

	在作为查询参数发送时设置CSV格式Pageable，以便正确编码。

反应式支持

由于OpenFeign 项目目前不支持响应式客户端，例如Spring WebClient，因此 Spring Cloud OpenFeign 也不支持。一旦它在核心项目中可用，我们将在此处添加对它的支持。

在此之前，我们建议使用feign-reactive来支持 Spring WebClient。

早期初始化错误

根据您使用 Feign 客户端的方式，您可能会在启动应用程序时看到初始化错误。要解决此问题，您可以ObjectProvider在自动装配客户端时使用。

@Autowired
ObjectProvider<TestFeginClient> testFeginClient;

Spring 数据支持

您可以考虑启用 Jackson Modules 来支持org.springframework.data.domain.Page和org.springframework.data.domain.Sort解码。

feign.autoconfiguration.jackson.enabled=true

@RefreshScope支持

如果启用了 Feign 客户端刷新，则每个 feign 客户端都被创建feign.Request.Options为一个刷新范围的 bean。这意味着诸如connectTimeout和之类的属性readTimeout可以通过POST /actuator/refresh.

默认情况下，Feign 客户端中的刷新行为是禁用的。使用以下属性启用刷新行为：

feign.client.refresh-enabled=true

请勿使用注释对@FeignClient接口进行@RefreshScope注释。