SpringCloud - Spring Cloud Netflix - 声明式Rest客户端Feign

参考：https://cloud.spring.io/spring-cloud-static/Edgware.SR5/multi/multi_spring-cloud-feign.html#spring-cloud-feign

 

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

 

1. 如何添加Feign
要在项目中包含Feign，使用 group为org.springframework.cloud和artifact id为 spring-cloud-starter-openfeign的starter。 

springboot启动应用示例：

@Configuration
@ComponentScan
@EnableAutoConfiguration
@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 getStores();

    @RequestMapping(method = RequestMethod.POST, value = "/stores/{storeId}", consumes = "application/json")
    Store update(@PathVariable("storeId") Long storeId, Store store);
}

在@FeignClient注解中，String值（上面的“stores”）是一个任意客户端名称，用于创建Ribbon负载均衡器。还可以使用url属性指定URL（绝对值或仅指定主机名）。应用程序上下文中bean的名称是接口的完全限定名称。要指定自己的别名值，可以使用@FeignClient注解的qualifier值。

上面的Ribbon客户端将要发现“stores”服务的物理地址。如果应用程序是Eureka客户端，那么它将解析Eureka服务注册表中的服务。如果不想使用Eureka，只需在外部配置中配置服务器列表。

 

2. 覆盖Feign默认值
Spring Cloud的Feign支持的核心是指定客户端的概念。每个feign客户端都是一组组件的一部分，这些组件一起工作以按需联系远程服务器，可以使用@FeignClient注解指定该集合的名称。 Spring Cloud使用FeignClientsConfiguration按需为每个命名客户端创建一个新的集合作为ApplicationContext。这包含（除其他外）feign.Decoder、feign.Encoder和feign.Contract。

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属性。
• 以前，使用url属性不需要name属性。 现在需要使用name属性。

name和url属性支持占位符：

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

Spring Cloud Netflix默认为feign（BeanType beanName：ClassName）提供以下bean：

• Decoder feignDecoder：ResponseEntityDecoder（包装SpringDecoder）
• Encoder feignEncoder：SpringEncoder
• Logger feignLogger：Slf4jLogger
• Contract feignContract：SpringMvcContract
• Feign.Builder feignBuilder：HystrixFeign.Builder
• Client feignClient：如果启用了Ribbon，则它是LoadBalancerFeignClient，否则使用默认的feign客户端。

可以通过将feign.okhttp.enabled或feign.httpclient.enabled分别设置为true并将它们放在类路径上来使用OkHttpClient和ApacheHttpClient feign 客户端。可以通过在使用Apache时提供ClosableHttpClient bean或使用OK HTTP时提供OkHttpClient bean来自定义所使用的HTTP客户端。

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

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

创建其中一种类型的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也可以使用配置属性进行配置。

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

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

如果更喜欢使用配置属性来配置所有@FeignClient，则可以使用default 属性来创建配置属性。application.yml配置如下：

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。

application.yml

# Feign中禁用Hystrix
feign:
  hystrix:
    enabled: false

# 设置线程隔离级别为SEMAPHORE
hystrix:
  command:
    default:
      execution:
        isolation:
          strategy: SEMAPHORE

 

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

@Import(FeignClientsConfiguration.class)
class FooController {

    private FooClient fooClient;

    private FooClient adminClient;

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

注：

• 在上面的示例中，FeignClientsConfiguration.class是Spring Cloud Netflix提供的默认配置。
• PROD-SVC是客户端将向其发出请求的服务的名称。

 

4. Feign Hystrix支持
如果Hystrix在类路径上并且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中更改了此默认行为，采用了选择加入方法。

 

5. Feign Hystrix回退
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 {
    @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的方法目前不支持回退。

 

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

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

 

7. Feign继承支持
Feign通过单继承接口支持样板apis。 这允许将常见操作分组为基本接口。

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（方法参数映射不是继承的）。

 

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

通过这些属性，可以选择压缩介质类型和最小请求阈值长度。

 

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

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