译者： 王鸿飞 / brucewhf@gmail.com

声明式REST客户端：Feign

Feign是一个声明式Web Service客户端。使用Feign能让编写Web Service客户端更加简单, 它的使用方法是定义一个接口，然后在上面添加注解，同时也支持JAX-RS标准的注解。Feign也支持可拔插式的编码器和解码器。Spring Cloud对Feign进行了封装，使其支持了Spring MVC标准注解和HttpMessageConverters。Feign可以与Eureka和Ribbon组合使用以支持负载均衡。

主类示例：

  1. @Configuration
  2. @ComponentScan
  3. @EnableAutoConfiguration
  4. @EnableEurekaClient
  5. @EnableFeignClients
  6. public class Application {
  8.     public static void main(String[] args) {
  9.         SpringApplication.run(Application.class, args);
  10.     }
  12. }

StoreClient.java:

  1. @FeignClient("stores")
  2. public interface StoreClient {
  3.     @RequestMapping(method = RequestMethod.GET, value = "/stores")
  4.     List<Store> getStores();
  6.     @RequestMapping(method = RequestMethod.POST, value = "/stores/{storeId}", consumes = "application/json")
  7.     Store update(@PathVariable("storeId") Long storeId, Store store);
  8. }

@FeignClient注解中的stores属性可以是一个任意字符串(译者注：如果与Eureka组合使用，则stores应为Eureka中的服务名)，Feign用它来创建一个Ribbon负载均衡器。你也可以通过url属性来指定一个地址(可以是完整的URL，也可以是一个主机名)。标注了@FeignClient注解的接口在ApplicationContext中的Bean实例名是这个接口的全限定名，同时这个Bean还有一个别名，为Bean名 + FeignClient。在本例中，可以使用@Qualifier("storesFeignClient")来注入该组件。


如果classpath中有Ribbon, 上面的例子中Ribbon Client会想办法查找stores服务的IP地址。如果Eureka也在classpath中，那么Ribbon会从Eureka的注册信息中查找。如果你不想用Eureka,你也可以在配置文件中直接指定一组服务器地址。


覆盖Feign的默认配置

Spring Cloud对Feign的封装中一个核心的概念就是客户端要有一个名字。每一个客户端随时可以向远程服务发起请求，并且每个服务都可以像使用@FeignClient注解一样指定一个名字。Spring Cloud会将所有的@FeignClient组合在一起创建一个新的ApplicationContext, 并使用FeignClientsConfiguration对Clients进行配置。配置中包括编码器、解码器和一个feign.Contract。


Spring Cloud允许你通过configuration属性完全控制Feign的配置信息，这些配置比FeignClientsConfiguration优先级要高：

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

在这个例子中，FooConfiguration中的配置信息会覆盖掉FeignClientsConfiguration中对应的配置。

注意：FooConfiguration虽然是个配置类，但是它不应该被主上下文(ApplicationContext)扫描到，否则该类中的配置信息就会被应用于所有的@FeignClient客户端(本例中FooConfiguration中的配置应该只对StoreClient起作用)。

注意：serviceId属性已经被弃用了，取而代之的是name属性。

在先前的版本中在指定了url属性时name是可选属性，现在无论什么时候name都是必填属性。

name和url属性也支持占位符：

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

Spring Cloud Netflix为Feign提供了以下默认的配置Bean：(下面最左侧是Bean的类型，中间是Bean的name, 右侧是类名)

  • Decoder feignDecoder: ResponseEntityDecoder(这是对SpringDecoder的封装)
  • Encoder feignEncoder: SpringEncoder
  • Logger feignLogger: Slf4jLogger
  • Contract feignContract: SpringMvcContract
  • Feign.Builder feignBuilder: HystrixFeign.Builder

下列Bean默认情况下Spring Cloud Netflix并没有提供，但是在应用启动时依然会从上下文中查找这些Bean来构造客户端对象：

  • Logger.Level
  • Retryer
  • ErrorDecoder
  • Request.Options
  • Collection<RequestInterceptor>

如果想要覆盖Spring Cloud Netflix提供的默认配置Bean, 需要在@FeignClient的configuration属性中指定一个配置类，并提供想要覆盖的Bean即可：

  1. @Configuration
  2. public class FooConfiguration {
  3.     @Bean
  4.     public Contract feignContract() {
  5.         return new feign.Contract.Default();
  6.     }
  8.     @Bean
  9.     public BasicAuthRequestInterceptor basicAuthRequestInterceptor() {
  10.         return new BasicAuthRequestInterceptor("user", "password");
  11.     }
  12. }

本例子中，我们用feign.Contract.Default代替了SpringMvcContract, 并添加了一个RequestInterceptor。以这种方式做的配置会在所有的@FeignClient中生效。

Feign对Hystrix的支持

如果Hystrix在classpath中，Feign会默认将所有方法都封装到断路器中。Returning acom.netflix.hystrix.HystrixCommand is also available。这样一来你就可以使用Reactive Pattern了。(调用.toObservalbe()或.observe()方法，或者通过.queue()进行异步调用)。

将feign.hystrix.enabled=false参数设为false可以关闭对Hystrix的支持。

如果想只关闭指定客户端的Hystrix支持，创建一个Feign.Builder组件并标注为@Scope(prototype)：

  1. @Configuration
  2. public class FooConfiguration {
  3.     @Bean
  4.     @Scope("prototype")
  5.     public Feign.Builder feignBuilder() {
  6.         return Feign.builder();
  7.     }
  8. }

Feign对Hystrix Fallback的支持

Hystrix支持fallback的概念，即当断路器打开或发生错误时执行指定的失败逻辑。要为指定的@FeignClient启用Fallback支持， 需要在fallback属性中指定实现类：

  1. @FeignClient(name = "hello", fallback = HystrixClientFallback.class)
  2. protected interface HystrixClient {
  3.     @RequestMapping(method = RequestMethod.GET, value = "/hello")
  4.     Hello iFailSometimes();
  5. }
  7. static class HystrixClientFallback implements HystrixClient {
  8.     @Override
  9.     public Hello iFailSometimes() {
  10.         return new Hello("fallback");
  11.     }
  12. }

注意：Feign对Hystrix Fallback的支持有一个限制：对于返回com.netflix.hystrix.HystrixCommand或rx.Observable对象的方法，fallback不起作用。

Feign对继承的支持

Feign可以通过Java的接口支持继承。你可以把一些公共的操作放到父接口中，然后定义子接口继承之：

UserService.java

  1. public interface UserService {
  3.     @RequestMapping(method = RequestMethod.GET, value ="/users/{id}")
  4.     User getUser(@PathVariable("id") long id);
  5. }

UserResource.java

  1. @RestController
  2. public class UserResource implements UserService {
  4. }

UserClient.java

  1. package project.user;
  3. @FeignClient("users")
  4. public interface UserClient extends UserService {
  6. }

注意: 在服务的调用端和提供端共用同一个接口定义是不明智的，这会将调用端和提供端的代码紧紧耦合在一起。同时在SpringMVC中会有问题，因为请求参数映射是不能被继承的。

Feign对压缩的支持

你可能会想要对请求/响应数据进行Gzip压缩，指定以下参数即可：

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

也可以添加一些更细粒度的配置：

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

上面的3个参数可以让你选择对哪种请求进行压缩，并设置一个最小请求大小的阀值。

Feign的日志

每一个@FeignClient都会创建一个Logger, Logger的名字就是接口的全限定名。Feign的日志配置参数仅支持DEBUG：

application.properties

  1. logging.level.project.user.UserClient: DEBUG

Logger.Level对象允许你为指定客户端配置想记录哪些信息：

  • NONE, 不记录任何信息，默认值。
  • BASIC, 记录请求方法、请求URL、状态码和用时。
  • HEADERS, 在BASIC的基础上再记录一些常用信息。
  • FULL: 记录请求和响应报文的全部内容。

将Level设置为FULL的示例如下：

  1. @Configuration
  2. public class FooConfiguration {
  3.     @Bean
  4.     Logger.Level feignLoggerLevel() {
  5.         return Logger.Level.FULL;
  6.     }
  7. }