Docs4dev
Docs
spring-cloud / Greenwich.RELEASE / reference / multi_spring-cloud-feign.html

23. 声明式 RESTClient 端：Feign

Feign是声明性 Web 服务 Client 端。它使编写 Web 服务 Client 端更加容易。要使用 Feign，请创建一个接口并对其进行 Comments。它具有可插入 Comments 支持，包括 FeignComments 和 JAX-RSComments。 Feign 还支持可插拔编码器和解码器。 Spring Cloud 添加了对 Spring MVCComments 的支持，并支持使用 Spring Web 中默认使用的HttpMessageConverters。当使用 Feign 时，Spring Cloud 集成了 Ribbon 和 Eureka 以提供负载平衡的 httpClient 端。

23.1 如何包含Feign

要将 Feign 包含在您的项目中，请使用带有org.springframework.cloud组和工件 ID spring-cloud-starter-openfeign的启动器。有关使用当前 Spring Cloud Release Train 设置构建系统的详细信息，请参见Spring Cloud Project 页面。

Spring 启动应用程序示例

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

在@FeignClient注解中，String 值(上面的“ stores”)是一个任意的 Client 端名称，用于创建 Ribbon 负载均衡器(请参阅以下是功能区支持的详细信息)。您还可以使用url属性(绝对值或仅是主机名)来指定 URL。应用程序上下文中的 Bean 名称是接口的标准名称。要指定自己的别名值，可以使用@FeignClient注解的qualifier值。

上面的功能区 Client 端将要发现“Store”服务的物理地址。如果您的应用程序是 EurekaClient 端，则它将在 Eureka 服务注册表中解析该服务。如果您不想使用 Eureka，则只需在外部配置中配置服务器列表即可(请参阅以上例如)。

23.2 覆盖Feign默认值

Spring Cloud 的 Feign 支持的中心概念是指定 Client 端的概念。每个虚拟 Client 端都是组件的一部分，这些组件可以一起工作以按需联系远程服务器，并且该组件具有一个名称，您可以使用@FeignClientComments 将其命名为应用程序开发人员。 Spring Cloud 使用FeignClientsConfiguration为每个命名 Client 端按需创建一个新的集合作为ApplicationContext。其中包含feign.Decoder，feign.Encoder和feign.Contract。通过使用@FeignClient注解的contextId属性，可以覆盖该集合的名称。

通过使用@FeignClient声明其他配置(在FeignClientsConfiguration之上)，Spring Cloud 使您可以完全控制假 Client 端。例：

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

在这种情况下，Client 端是由FeignClientsConfiguration中已有的组件以及FooConfiguration中的任何组件组成的(后者将覆盖前者)。

Note

FooConfiguration不需要用@ConfigurationComments。但是，如果是这样，则请注意将其从任何会包含此配置的@ComponentScan中排除，因为如果指定，它将成为feign.Decoder，feign.Encoder，feign.Contract等的默认来源。可以通过将其与任何@ComponentScan或@SpringBootApplication放在单独的，不重叠的包中来避免这种情况，也可以在@ComponentScan中将其明确排除在外。

Note

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

Note

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

Warning

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

name和url属性支持占位符。

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

Spring Cloud Netflix 默认为Feign提供以下 bean(BeanType beanName：ClassName)：

  • Decoder feignDecoder：ResponseEntityDecoder(其中包含SpringDecoder)

  • Encoder feignEncoder：SpringEncoder

  • Logger feignLogger：Slf4jLogger

  • Contract feignContract：SpringMvcContract

  • Feign.Builder feignBuilder：HystrixFeign.Builder

  • Client feignClient：如果启用了功能区，则它是LoadBalancerFeignClient，否则将使用默认的Feign Client 端。

可以通过分别将feign.okhttp.enabled或feign.httpclient.enabled设置为true并将它们放在 Classpath 中来使用 OkHttpClient 和 ApacheHttpClient 虚拟 Client 端。您可以通过使用 Bean 时提供ClosableHttpClient或使用 OK HTTP 时提供OkHttpClient来定制 HTTPClient 端。

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

  • Logger.Level

  • Retryer

  • ErrorDecoder

  • Request.Options

  • Collection<RequestInterceptor>

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

这将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中指定默认配置。区别在于此配置将应用于所有伪 Client 端。

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

application.yml

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

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

Note

如果您需要在RequestInterceptors you will need to either set the thread isolation strategy for Hystrix to SEMAPHORE中使用ThreadLocal绑定变量或在 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 的伪 Client 端，以便它们指向同一台服务器，但每个 Client 端具有不同的自定义配置，则必须使用@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 {
    //..
}

23.3 手动创建外来 Client

在某些情况下，可能有必要使用上述方法无法实现的方式自定义 FeignClient。在这种情况下，您可以使用Feign Builder API创建 Client 端。下面是一个示例，该示例创建具有相同接口的两个 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, "http://PROD-SVC");

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

Note

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

Note

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

Note

Feign Contract对象定义在接口上有效的 Comments 和值。自动连接的Contract bean 提供对 SpringMVCComments 的支持，而不是默认的 Feign 本机 Comments。

23.4 Feign Hystrix 支持

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

要基于每个 Client 端禁用 Hystrix 支持，请创建一个具有“ prototype”作用域的普通Feign.Builder，例如：

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

Warning

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

23.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<HystrixClient> {
	@Override
	public HystrixClient create(Throwable cause) {
		return new HystrixClient() {
			@Override
			public Hello iFailSometimes() {
				return new Hello("fallback; reason was: " + cause.getMessage());
			}
		};
	}
}

Warning

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

23.6Feign 和@Primary

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

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

23.7 假继承支持

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 {

}

Note

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

23.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

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

23.9 Feign日志

为每个创建的 FeignClient 端创建一个 Logger。默认情况下，Logger 的名称是用于创建 FeignClient 端的接口的全类名称。Feign日志仅响应DEBUG级别。

application.yml.

logging.level.project.user.UserClient: DEBUG

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

  • NONE，不记录( DEFAULT )。

  • BASIC，仅记录请求方法和 URL 以及响应状态代码和执行时间。

  • HEADERS，记录基本信息以及请求和响应 Headers。

  • FULL，记录请求和响应的标题，正文和元数据。

例如，以下将Logger.Level设置为FULL：

@Configuration
public class FooConfiguration {
    @Bean
    Logger.Level feignLoggerLevel() {
        return Logger.Level.FULL;
    }
}

23.10 Feign @QueryMap 支持

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

Spring Cloud OpenFeign 提供了等效的@SpringQueryMapComments，该 Comments 用于将 POJO 或 Map 参数 Comments 为查询参数 Map。

例如，Params类定义参数param1和param2：

// Params.java
public class Params {
    private String param1;
    private String param2;

    // [Getters and setters omitted for brevity]
}

以下Feign Client 端通过使用@SpringQueryMapComments 来使用Params类：

@FeignClient("demo")
public class DemoTemplate {

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