spring-cloud-openfeign

1.声明式REST客户端：Feign

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

1.1 如何引入Feign

引入依赖 group org.springframework.cloud 和 artifact id spring-cloud-starter-openfeign

开启注解支持：

@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.POST, value = "/stores/{storeId}", consumes = "application/json")
    Store update(@PathVariable("storeId") Long storeId, Store store);
}

@FeignClient注解上的字符串值（上面的“ stores”）是一个任意的客户端名称，该名称用于创建Spring Cloud LoadBalancer客户端。 您还可以使用url属性（绝对值或仅是主机名）指定URL。 应用程序上下文中的Bean名称是接口的标准名称。 要指定自己的别名值，可以使用@FeignClient注解的qualifier属性。

上面的负载平衡器客户端会发现“store”服务的物理地址。 如果您的应用程序是Eureka客户端，则它将在Eureka服务注册表中解析该服务。 如果您不想使用Eureka，则可以使用 SimpleDiscoveryClient 在外部配置中简单地配置服务器列表。

1.2 修改Feign的默认值

Spring Cloud的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扫包中排除，因为如果指定，它将成为feign.Decoder，feign.Encoder，feign.Contract等的默认来源。 可以通过将其放在与@ComponentScan或@SpringBootApplication不同的单独的，不重叠的包中来避免这种情况，也可以使用@ComponentScan中将其明确排除在外。

注意：现在不建议使用serviceId属性，而推荐使用name属性。

注意：除了更改ApplicationContext集合的名称之外，使用@FeignClient批注的contextId属性，会覆盖客户端名称的别名，并将其用作为该客户端创建的配置Bean名称的一部分。

注意： 以前，使用url属性时不需要name属性。 现在需要使用。

name和url属性中支持占位符。

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

Spring Cloud OpenFeign默认为feign提供以下beans（BeanType beanName:className）

• Decoder feignDecoder: ResponseEntityDecoder (which wraps a SpringDecoder)
• Encoder feignEncoder: SpringEncoder
• Logger feignLogger: Slf4jLogger
• Contract feignContract: SpringMvcContract
• Feign.Builder feignBuilder: HystrixFeign.Builder
• Client feignClient :如果Spring Cloud LoadBalancer在类路径中，则使用FeignBlockingLoadBalancerClient。 如果它们都不在类路径中，则使用默认的feign客户端。

可以通过将feign.okhttp.enabled或feign.httpclient.enabled分别设置为true并将它们放在类路径中来使用OkHttpClient和ApacheHttpClient feign客户端。 您可以通过使用Apache时提供org.apache.http.impl.client.CloseableHttpClient的bean或使用OK HTTP时提供okhttp3.OkHttpClient的bean来定制所使用的HTTP客户端。

默认情况下，Spring Cloud Netflix不提供以下用于Feign的bean，但仍会从应用程序上下文中查找这些类型的bean以创建feign客户端：

• Logger.Level
• Retryer
• ErrorDecoder
• Request.Options
• Collection
• SetterFactory
• QueryMapEncoder

创建这些类型之一的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");
    }
}

这用feign.Contract.Default替换SpringMvcContract，并将RequestInterceptor添加到RequestInterceptor的集合中。

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

feign:
  client:
    config:
      feignName:
        connectTimeout: 5000
        readTimeout: 5000
        loggerLevel: full
        errorDecoder: com.example.SimpleErrorDecoder
        retryer: com.example.SimpleRetryer
        requestInterceptors:
          - com.example.FooRequestInterceptor
          - com.example.BarRequestInterceptor
        decode404: false
        encoder: com.example.SimpleEncoder
        decoder: com.example.SimpleDecoder
        contract: com.example.SimpleContract

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

如果您希望使用配置属性来配置所有@FeignClient，则可以使用default 名称创建配置属性。

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

如果我们同时创建@Configuration bean和配置属性，则配置属性将获胜。 它将覆盖@Configuration值。 但是，如果要将优先级更改为@Configuration，可以将feign.client.default-to-properties更改为false。

如果您需要在RequestInterceptor中使用ThreadLocal绑定变量，则需要将Hystrix的线程隔离策略设置为SEMAPHORE或在Feign中禁用Hystrix。

# To disable Hystrix in Feign
feign:
  hystrix:
    enabled: false

# To set thread isolation to SEMAPHORE
hystrix:
  command:
    default:
      execution:
        isolation:
          strategy: SEMAPHORE

如果我们要创建多个具有相同名称或URL的虚拟客户端，以便它们指向同一台服务器，但每个客户端使用不同的自定义配置，则必须使用@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 {
    //..
}

1.3 手动创建Feign客户端

在某些情况下，可能有必要使用上述方法无法实现的方式自定义Feign客户。 在这种情况下，您可以使用Feign Builder API创建客户端。 下面是一个示例，该示例创建具有相同接口的两个Feign Client，但为每个Feign Client配置一个单独的请求拦截器。

@Import(FeignClientsConfiguration.class)
class FooController {

    private FooClient fooClient;

    private FooClient adminClient;

        @Autowired
    public FooController(Decoder decoder, Encoder encoder, Client client, Contract contract) {
        this.fooClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
                .target(FooClient.class, "https://PROD-SVC");

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

在上面的示例中，FeignClientsConfiguration.class是Spring Cloud Netflix提供的默认配置。

PROD-SVC是客户端将向其请求的服务的名称。

Feign Contract对象定义接口支持的注解。 自动装配的Contract bean提供对SpringMVC注解的支持，而不是默认的Feign注解。

1.4 Feign Hystrix支持

如果Hystrix在类路径上并且feign.hystrix.enabled = true，则Feign将使用断路器包装所有方法。 还可以返回com.netflix.hystrix.HystrixCommand。 这使您可以使用响应式（通过调用.toObservable或.observe）或异步使用（通过调用.queue）。

要基于每个客户端禁用Hystrix支持，请创建具有“prototype”范围的Feign.Builder，例如：

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

在Spring Cloud Dalston发行之前，如果Hystrix在类路径中，则Feign默认会将所有方法包装在断路器中。 Spring Cloud Dalston中更改了此默认行为，以支持选择加入方法。

1.5 Feign Hystrix Fallbacks

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

@FeignClient(name = "hello", fallback = HystrixClientFallback.class)
protected interface HystrixClient {
    @RequestMapping(method = RequestMethod.GET, value = "/hello")
    Hello iFailSometimes();
}

static class HystrixClientFallback implements HystrixClient {
    @Override
    public Hello iFailSometimes() {
        return new Hello("fallback");
    }
}

如果需要访问引起回退触发器的原因，则可以使用@FeignClient中的fallbackFactory属性。

@FeignClient(name = "hello", fallbackFactory = HystrixClientFallbackFactory.class)
protected interface HystrixClient {
    @RequestMapping(method = RequestMethod.GET, value = "/hello")
    Hello iFailSometimes();
}

@Component
static class HystrixClientFallbackFactory implements FallbackFactory<HystrixClient> {
    @Override
    public HystrixClient create(Throwable cause) {
        return new HystrixClient() {
            @Override
            public Hello iFailSometimes() {
                return new Hello("fallback; reason was: " + cause.getMessage());
            }
        };
    }
}

Feign中的后备实现以及Hystrix后备如何工作存在局限性。 当前，返回com.netflix.hystrix.HystrixCommand和rx.Observable的方法不支持回退。

1.6 Feign和@Primary

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

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

1.7 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 {

}

通常不建议在服务器和客户端之间共享接口。 它引入了紧密耦合，并且实际上也无法以当前形式与Spring MVC一起使用（方法参数映射不被继承）。

1.8 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

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

对于OkHttpClient以外的http客户端，可以启用默认的gzip解码器以UTF-8编码解码gzip响应：

feign.compression.response.enabled=true
feign.compression.response.useGzipDecoder=true

1.9 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.10 @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客户端通过使用@SpringQueryMap批注来使用Params类：

@FeignClient("demo")
public interface DemoTemplate {

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

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

1.11 HATEOAS 支持

Spring提供了一些API来创建遵循HATEOAS原理的REST表示形式，Spring Hateoas和Spring Data REST。

如果您的项目使用org.springframework.boot：spring-boot-starter-hateoas或org.springframework.boot：spring-boot-starter-data-rest，则默认启用Feign HATEOAS支持。

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

@FeignClient("demo")
public interface DemoTemplate {

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

1.12 @MatrixVariable 支持

Spring Cloud OpenFeign为Spring @MatrixVariable注释提供支持。

如果将map作为方法参数传递，则@MatrixVariable路径段是通过将map中的键/值对与=联接而创建的。

如果传递了一个不同的对象，则@MatrixVariable批注中提供的名称（如果已定义）或带注释的变量名将使用=附带提供的方法参数。

即使在服务器端，Spring不需要用户将路径段占位符命名为与矩阵变量名称相同的名称，因为它在客户端上太含糊不清，Sprig Cloud OpenFeign要求您使用以下命令添加路径段占位符： 与@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.13 故障排除

1.13.1 过早初始化错误

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

@Autowired
ObjectProvider<TestFeginClient> testFeginClient;

2.配置属性

Name	Default	Description
feign.client.config
feign.client.default-config	default
feign.client.default-to-properties	true
feign.compression.request.enabled	false	允许请求压缩
feign.compression.request.mime-types	[text/xml, application/xml, application/json]	T支持压缩的 mime types.
feign.compression.request.min-request-size	2048	The minimum threshold content size.
feign.compression.response.enabled	false	允许响应压缩
feign.compression.response.useGzipDecoder	false	Enables the default gzip decoder to be used.
feign.httpclient.connection-timeout	2000
feign.httpclient.connection-timer-repeat	3000
feign.httpclient.disable-ssl-validation	false
feign.httpclient.enabled	true	Enables the use of the Apache HTTP Client by Feign.
feign.httpclient.follow-redirects	true
feign.httpclient.max-connections	200
feign.httpclient.max-connections-per-route	50
feign.httpclient.time-to-live	900
feign.httpclient.time-to-live-unit
feign.hystrix.enabled	false	If true, an OpenFeign client will be wrapped with a Hystrix circuit breaker.
feign.okhttp.enabled	false	Enables the use of the OK HTTP Client by Feign.