Spring Cloud OpenFeign 中文手册菜鸡翻译

文章目录

官网地址： https://docs.spring.io/spring-cloud-openfeign/docs/2.2.5.RELEASE/reference/html/

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

在这里插入图片描述

1.声明式REST客户端：Feign

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

1.1 如何引入Feign

pom.xml增加依赖如下：

        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-openfeign</artifactId>
        </dependency>

应用程序示例

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

在@FeignClient注释中，String值（上面的“ stores”）是一个任意的客户端名称，用于创建Ribbon负载平衡器（请参见下面的Ribbon支持的详细信息）或Spring Cloud LoadBalancer。您也可以使用url属性（绝对值或仅主机名）指定URL 。应用程序上下文中的Bean名称是接口的标准名称。要指定自己的别名值，可以使用注释的qualifier值@FeignClient。

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

为了保持向后兼容性，用作默认的负载均衡器实现。但是，Spring Cloud Netflix Ribbon现在处于维护模式，因此我们建议改用Spring Cloud LoadBalancer。为此，将的值设置spring.cloud.loadbalancer.ribbon.enabled为false。

1.2 覆盖默认配置

Spring Cloud的Feign支持的中心概念是指定客户端的概念。每个虚拟客户端都是组件的一部分，这些组件可以一起工作以按需联系远程服务器，并且该组件的名称是您使用@FeignClient注释作为应用程序开发人员提供的。Spring CloudApplicationContext使用来为每个命名客户端按需创建一个新的合奏 FeignClientsConfiguration。这包含（除其他事项外）feign.Decoder，feign.Encoder和afeign.Contract。通过使用批注的contextId 属性，可以覆盖该集合的名称@FeignClient。

您可以通过声明额外的配置（在顶部取佯客户端的完全控制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。

serviceId现在不推荐使用该属性，而推荐使用该name属性。

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

以前，使用url属性不需要name属性。name现在需要使用。

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

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

Spring Cloud OpenFeign默认为假装提供以下bean（BeanTypebeanName ：）ClassName：

DecoderfeignDecoder ：（ResponseEntityDecoder包含SpringDecoder）
Encoder feignEncoder： SpringEncoder
Logger feignLogger： Slf4jLogger
Contract feignContract： SpringMvcContract
Feign.Builder feignBuilder： HystrixFeign.Builder
ClientfeignClient：如果Ribbon在类路径中且已启用，则为LoadBalancerFeignClient，否则，如果Spring Cloud LoadBalancer在类路径中，FeignBlockingLoadBalancerClient则使用。如果它们都不在类路径中，则使用默认的客户端。

spring-cloud-starter-openfeign同时支持spring-cloud-starter-netflix-ribbon和spring-cloud-starter-loadbalancer。但是，由于它们是可选的依赖项，因此需要确保将要使用的依赖项添加到项目中。

OkHttpClient和ApacheHttpClient客户端可以通过设置一起使用feign.okhttp.enabled或feign.httpclient.enabled以true分别，以及具有它们的类路径上。您可以通过org.apache.http.impl.client.CloseableHttpClient在使用Apache或okhttp3.OkHttpClient使用OK HTTP时提供Bean来定制所使用的HTTP客户端。

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

Logger.Level
Retryer
ErrorDecoder
Request.Options
Collection<RequestInterceptor>
SetterFactory
QueryMapEncoder

默认情况下会创建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.Default添加。RequestInterceptor``RequestInterceptor

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

application.yml

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中指定默认配置。不同之处在于此配置将适用于所有客户端。

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

application.yml

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

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

如果需要ThreadLocal在您的系统中使用绑定变量，RequestInterceptors you will need to either set the thread isolation strategy for Hystrix to SEMAPHORE或者在Feign中禁用Hystrix。

application.yml

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

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

如果我们要创建多个具有相同名称或URL的伪客户端，以便它们指向同一台服务器，但每个客户端具有不同的自定义配置，则必须使用的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。您可以通过重写这样做inheritParentConfiguration()的FeignClientConfigurer bean来回报false：

@Configuration
public class CustomConfiguration{
    
    

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

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

        }
}

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 OpenFeign提供的默认配置。

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

FeignContract对象定义在接口上有效的注释和值。自动装配的Contractbean提供对SpringMVC注释的支持，而不是默认的Feign本机注释。

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

1.4 Feign Hystrix支持

如果Hystrix在classpath和上feign.hystrix.enabled=true，Feign将使用断路器包装所有方法。com.netflix.hystrix.HystrixCommand还可以返回。这允许您使用反应模式（与以打电话.toObservable()或.observe()或异步使用（通过调用.queue()）。

要基于每个客户端禁用Hystrix支持，请创建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");
    }
}

如果需要访问引起后备触发器的原因，则可以使用fallbackFactory里面的属性@FeignClient。

@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后备一起使用ApplicationContext时，同一类型的多个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.7 Feign支持继承

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

UserService.java

public interface UserService {
    
    

    @RequestMapping(method = RequestMethod.GET, value ="/users/{id}")
    User getUser(@PathVariable("id") long id);
}

UserResource.java

@RestController
public class UserResource implements UserService {
    
    

}

UserClient.java

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

伪装请求压缩为您提供的设置类似于您为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客户端的接口的全类名称。伪日志仅响应该DEBUG级别。

application.yml

logging.level.project.user.UserClient: DEBUG

Logger.Level您可以为每个客户端配置的对象告诉Feign要记录多少。选择是：

NONE，不记录（DEFAULT）。
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]
}

以下伪装客户端Params通过使用@SpringQueryMap注释使用该类：

@FeignClient("demo")
public interface DemoTemplate {
    
    

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

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

1.11 HATEOAS支持

跳过

1.12 Spring @MatrixVariable支持

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

如果将地图作为方法参数传递，则通过@MatrixVariable将地图中的键值对与相连来创建路径段=。

如果一个不同的对象被传递，无论是name在所提供的@MatrixVariable注释（如果定义）或注释的变量名接合用所提供的方法的参数使用=。

重要

即使在服务器端，Spring不需要用户将路径段占位符命名为与矩阵变量名称相同的名称，因为它在客户端上太含糊不清，Sprig 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.13 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作为查询参数，以便正确编码。

1.14 反应性支持

由于OpenFeign项目当前不支持Spring WebClient之类的反应式客户端，因此Spring Cloud OpenFeign也不支持。我们将在核心项目中尽快在此处添加对它的支持。

在完成此操作之前，我们建议使用feign-active以获取Spring WebClient支持。

1.14.1 早期初始化错误

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

@Autowired
ObjectProvider<TestFeginClient> testFeginClient;

2.配置属性

可以在application.properties文件内部application.yml，文件内部或命令行开关中指定各种属性。本附录提供了常见的Spring Cloud OpenFeign属性的列表以及对使用它们的基础类的引用。

属性贡献可能来自类路径上的其他jar文件，因此您不应将其视为详尽的列表。另外，您可以定义自己的属性。

Name	Default	Description
feign.client.config
feign.client.default-config	default
feign.client.default-to-properties	true
feign.compression.request.enabled	false	Enables the request sent by Feign to be compressed.
feign.compression.request.mime-types	[text/xml, application/xml, application/json]	The list of supported mime types.
feign.compression.request.min-request-size	2048	The minimum threshold content size.
feign.compression.response.enabled	false	Enables the response from Feign to be compressed.
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.