此版本仍在开发中,尚未被视为稳定版本。如需最新的稳定版本,请使用 Spring Cloud OpenFeign 4.1.4spring-doc.cn

Spring Cloud OpenFeign 功能

声明式 REST 客户端:Feign

Feign 是一个声明性 Web 服务客户端。 它使编写 Web 服务客户端变得更加容易。 要使用 Feign,请创建一个接口并对其进行注释。 它具有可插拔的注释支持,包括 Feign 注释和 JAX-RS 注释。 Feign 还支持可插拔编码器和解码器。 Spring Cloud 增加了对 Spring MVC 注释的支持,并支持使用 Spring Web 中默认使用的相同注释。 Spring Cloud 集成了 Eureka、Spring Cloud CircuitBreaker 以及 Spring Cloud LoadBalancer,以便在使用 Feign 时提供负载均衡的 http 客户端。HttpMessageConvertersspring-doc.cn

如何包含 Feign

要在项目中包含 Feign,请使用带有 group 和 artifact id 的 starter 。有关使用当前 Spring Cloud Release Train 设置构建系统的详细信息,请参阅 Spring Cloud 项目页面org.springframework.cloudspring-cloud-starter-openfeignspring-doc.cn

Spring Boot 应用程序示例spring-doc.cn

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

	@GetMapping("/stores")
	Page<Store> getStores(Pageable pageable);

	@PostMapping(value = "/stores/{storeId}", consumes = "application/json",
				params = "mode=upsert")
	Store update(@PathVariable("storeId") Long storeId, Store store);

	@DeleteMapping("/stores/{storeId:\\d+}")
	void delete(@PathVariable Long storeId);
}

在注释中,String 值(上面的 “stores”)是任意客户端名称,用于创建 Spring Cloud LoadBalancer 客户端。 您还可以使用属性指定 URL (绝对值或只是一个主机名)。Bean 在 Application Context 是接口的完全限定名称。 要指定您自己的别名值,您可以使用值 的注释。@FeignClienturlqualifiers@FeignClientspring-doc.cn

上面的负载均衡器客户端将需要发现物理地址 对于 “stores” 服务。如果您的应用程序是 Eureka 客户端,则 它将解析 Eureka 服务注册表中的服务。如果你 不想使用 Eureka,可以配置服务器列表 在外部配置中使用 SimpleDiscoveryClientspring-doc.cn

Spring Cloud OpenFeign 支持 Spring Cloud LoadBalancer 的阻塞模式可用的所有功能。您可以在项目文档中阅读有关它们的更多信息。spring-doc.cn

要在 -annotated-classes 上使用 annotation,请确保指定客户端的位置,例如:或明确列出它们:。@EnableFeignClients@Configuration@EnableFeignClients(basePackages = "com.example.clients")@EnableFeignClients(clients = InventoryServiceFeignClient.class)

为了在多模块设置中加载 Spring Feign 客户端 bean,你需要直接指定包。spring-doc.cn

由于对象可以在初始上下文刷新之前被实例化,并且 Spring Cloud OpenFeign Clients 的实例化会触发上下文刷新,因此不应在类中声明它们。FactoryBeanFactoryBean

属性解析模式

在创建客户端 bean 时,我们解析通过 annotation 传递的值。截至 ,正在急切地解决这些值。对于大多数用例来说,这是一个很好的解决方案,并且它还允许 AOT 支持。Feign@FeignClient4.xspring-doc.cn

如果需要延迟解析属性,请将属性值设置为 。spring.cloud.openfeign.lazy-attributes-resolutiontruespring-doc.cn

对于 Spring Cloud Contract 测试集成,应使用惰性属性解析。

覆盖 Feign Defaults

Spring Cloud 的 Feign 支持中的一个中心概念是命名客户端的概念。每个 Feign 客户端都是组件集合的一部分,这些组件协同工作以按需联系远程服务器,并且该集合具有一个名称,您可以作为应用程序开发人员使用注释为其指定。Spring Cloud 使用为每个命名客户端按需创建一个新的 ensemble。它包含(除其他外)an 、 a 和 a 。 可以使用 Comments 的属性覆盖该 ensemble 的名称。@FeignClientApplicationContextFeignClientsConfigurationfeign.Decoderfeign.Encoderfeign.ContractcontextId@FeignClientspring-doc.cn

Spring Cloud 允许您通过使用 声明其他配置(在 之上 )来完全控制 Feign 客户端。例:FeignClientsConfiguration@FeignClientspring-doc.cn

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

在这种情况下,客户端由已有的组件以及任何 in 组成(其中后者将覆盖前者)。FeignClientsConfigurationFooConfigurationspring-doc.cn

FooConfiguration不需要使用 进行批注。但是,如果是,请注意将其从包含此配置的任何配置中排除,因为在指定时,它将成为 、 、 等的默认源。这可以通过将其放在独立于任何 或 的不重叠的包中来避免,也可以在 中显式排除它。@Configuration@ComponentScanfeign.Decoderfeign.Encoderfeign.Contract@ComponentScan@SpringBootApplication@ComponentScan
Using 属性除了更改 ensemble 中,它将覆盖客户端名称的别名 它将用作为该客户端创建的配置 Bean 名称的一部分。contextId@FeignClientApplicationContext
以前,使用 attribute 时不需要 attribute。现在需要 使用。urlnamename

和 属性中支持占位符。nameurlspring-doc.cn

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

Spring Cloud OpenFeign 默认为 feign ( beanName: ):BeanTypeClassNamespring-doc.cn

  • DecoderfeignDecoder:(它包装了一个ResponseEntityDecoderSpringDecoder)spring-doc.cn

  • EncoderfeignEncoder 的SpringEncoderspring-doc.cn

  • LoggerfeignLogger 中:Slf4jLoggerspring-doc.cn

  • MicrometerObservationCapabilitymicrometerObservationCapability:如果位于 Classpath 上并且可用feign-micrometerObservationRegistryspring-doc.cn

  • MicrometerCapabilitymicrometerCapability:如果 在 Classpath 上,则 is available 和 is not availablefeign-micrometerMeterRegistryObservationRegistryspring-doc.cn

  • CachingCapabilitycachingCapability:如果使用 annotation。可以通过以下方式禁用。@EnableCachingspring.cloud.openfeign.cache.enabledspring-doc.cn

  • ContractfeignContract 的SpringMvcContractspring-doc.cn

  • Feign.BuilderfeignBuilder 中:FeignCircuitBreaker.Builderspring-doc.cn

  • ClientfeignClient:如果 Spring Cloud LoadBalancer 在 Classpath 上,则使用。 如果它们都不在 Classpath 上,则使用默认的 Feign 客户端。FeignBlockingLoadBalancerClientspring-doc.cn

spring-cloud-starter-openfeign支持。但是,与可选依赖项一样,如果要使用它,则需要确保已将其添加到项目中。spring-cloud-starter-loadbalancer

要使用 OkHttpClient 支持的假客户端和 Http2Client 假客户端,请确保要使用的客户端在 Classpath 上并分别设置或到。spring.cloud.openfeign.okhttp.enabledspring.cloud.openfeign.http2client.enabledtruespring-doc.cn

对于 Apache HttpClient 5 支持的假客户端,确保 HttpClient 5 位于 Classpath 上就足够了,但您仍然可以通过设置为 . 在使用 Apache HC5 时,您可以通过提供任一 bean 来定制使用的 HTTP 客户端。spring.cloud.openfeign.httpclient.hc5.enabledfalseorg.apache.hc.client5.http.impl.classic.CloseableHttpClientspring-doc.cn

您可以通过在属性中设置值来进一步自定义 http 客户端。仅以 为前缀的客户端适用于所有客户端,以 Apache HttpClient 5 为前缀的客户端,以 OkHttpClient 为前缀的客户端,以及以 Http2Client 为前缀的客户端。您可以在附录中找到可自定义的属性的完整列表。 如果无法使用 properties 配置 Apache HttpClient 5,则有一个用于编程配置的接口。spring.cloud.openfeign.httpclient.xxxhttpclienthttpclient.hc5httpclient.okhttphttpclient.http2HttpClientBuilderCustomizerspring-doc.cn

从 Spring Cloud OpenFeign 4 开始,不再支持 Feign Apache HttpClient 4。我们建议改用 Apache HttpClient 5。

Spring Cloud OpenFeign 默认情况下为 feign 提供以下 bean,但仍从应用程序上下文中查找这些类型的 bean 以创建 Feign 客户端:spring-doc.cn

默认情况下会创建 具有 类型的 bean,这将禁用重试。 请注意,此重试行为与 Feign 默认行为不同,后者将自动重试 IOExceptions。 将它们视为与网络相关的暂时性异常,以及从 ErrorDecoder 引发的任何 RetryableException。Retryer.NEVER_RETRYRetryerspring-doc.cn

创建其中一种类型的 bean 并将其放置在配置中(如上所示)允许您覆盖所描述的每个 bean。例:@FeignClientFooConfigurationspring-doc.cn

@Configuration
public class FooConfiguration {
	@Bean
	public Contract feignContract() {
		return new feign.Contract.Default();
	}

	@Bean
	public BasicAuthRequestInterceptor basicAuthRequestInterceptor() {
		return new BasicAuthRequestInterceptor("user", "password");
	}
}

这会替换 with 并将 a 添加到 .SpringMvcContractfeign.Contract.DefaultRequestInterceptorRequestInterceptorspring-doc.cn

@FeignClient也可以使用 Configuration Properties 进行配置。spring-doc.cn

application.ymlspring-doc.cn

spring:
	cloud:
		openfeign:
			client:
				config:
					feignName:
                        url: http://remote-service.com
						connectTimeout: 5000
						readTimeout: 5000
						loggerLevel: full
						errorDecoder: com.example.SimpleErrorDecoder
						retryer: com.example.SimpleRetryer
						defaultQueryParameters:
							query: queryValue
						defaultRequestHeaders:
							header: headerValue
						requestInterceptors:
							- com.example.FooRequestInterceptor
							- com.example.BarRequestInterceptor
						responseInterceptor: com.example.BazResponseInterceptor
						dismiss404: false
						encoder: com.example.SimpleEncoder
						decoder: com.example.SimpleDecoder
						contract: com.example.SimpleContract
						capabilities:
							- com.example.FooCapability
							- com.example.BarCapability
						queryMapEncoder: com.example.SimpleQueryMapEncoder
						micrometer.enabled: false

feignName在此示例中,引用 ,该别名也与 和 .在负载均衡方案中,它还对应于将用于检索实例的服务器应用程序的 。为 decoders、retryer 和其他类指定的类必须在 Spring 上下文中具有 bean 或具有默认构造函数。@FeignClientvalue@FeignClientname@FeignClientcontextIdserviceIdspring-doc.cn

默认配置可以按上述类似的方式在属性中指定。区别在于此配置将应用于所有 Feign 客户端。@EnableFeignClientsdefaultConfigurationspring-doc.cn

如果您更喜欢使用配置属性来配置 all ,则可以创建具有 feign name 的配置属性。@FeignClientdefaultspring-doc.cn

您可以使用 和 指定查询参数和标头,这些参数和标头将与名为 .spring.cloud.openfeign.client.config.feignName.defaultQueryParametersspring.cloud.openfeign.client.config.feignName.defaultRequestHeadersfeignNamespring-doc.cn

application.ymlspring-doc.cn

spring:
	cloud:
		openfeign:
			client:
				config:
					default:
						connectTimeout: 5000
						readTimeout: 5000
						loggerLevel: basic

如果我们同时创建 bean 和配置属性,则配置属性将获胜。 它将覆盖值。但是,如果要将优先级更改为 , 您可以更改为 。@Configuration@Configuration@Configurationspring.cloud.openfeign.client.default-to-propertiesfalsespring-doc.cn

如果我们想创建多个具有相同名称或 url 的 Feign 客户端 这样它们就会指向同一个服务器,但每个服务器都有不同的自定义配置 我们必须使用 的 attribute 以避免 name 这些配置 bean 的冲突。contextId@FeignClientspring-doc.cn

@FeignClient(contextId = "fooClient", name = "stores", configuration = FooConfiguration.class)
public interface FooClient {
	//..
}
@FeignClient(contextId = "barClient", name = "stores", configuration = BarConfiguration.class)
public interface BarClient {
	//..
}

也可以将 FeignClient 配置为不从父上下文继承 bean。 您可以通过覆盖 bean 中的 return 来执行此操作:inheritParentConfiguration()FeignClientConfigurerfalsespring-doc.cn

@Configuration
public class CustomConfiguration {
	@Bean
	public FeignClientConfigurer feignClientConfigurer() {
		return new FeignClientConfigurer() {
			@Override
			public boolean inheritParentConfiguration() {
				 return false;
			}
		};
	}
}
默认情况下,Feign 客户端不对斜杠字符进行编码。您可以通过将 的值设置为 来更改此行为。/spring.cloud.openfeign.client.decodeSlashfalse

SpringEncoder配置

在我们提供的 中,我们为二进制内容类型和所有其他类型设置了 charset。SpringEncodernullUTF-8spring-doc.cn

您可以修改此行为以从 Headers charset 派生 charset,而不是通过将 的值设置为 。Content-Typespring.cloud.openfeign.encoder.charset-from-content-typetruespring-doc.cn

超时处理

我们可以在默认客户端和命名客户端上配置超时。OpenFeign 使用两个超时参数:spring-doc.cn

  • connectTimeout防止由于服务器处理时间长而阻止调用方。spring-doc.cn

  • readTimeout从建立连接时开始应用,并在返回响应时间过长时触发。spring-doc.cn

如果服务器未运行或不可用,则数据包会导致连接被拒绝。通信以错误消息或回退结束。这可能发生在 if 它设置得非常低之前。执行查找和接收此类数据包所花费的时间会导致此延迟的很大一部分。它可能会根据涉及 DNS 查找的远程主机而更改。connectTimeout

手动创建假客户端

在某些情况下,可能需要以一种不是 可以使用上述方法。在这种情况下,您可以使用 Feign Builder API 创建客户端。下面是一个示例 这会创建两个具有相同接口的假客户端,但为每个客户端配置 一个单独的请求拦截器。spring-doc.cn

@Import(FeignClientsConfiguration.class)
class FooController {

	private FooClient fooClient;

	private FooClient adminClient;

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

		this.adminClient = Feign.builder().client(client)
				.encoder(encoder)
				.decoder(decoder)
				.contract(contract)
				.addCapability(micrometerObservationCapability)
				.requestInterceptor(new BasicAuthRequestInterceptor("admin", "admin"))
				.target(FooClient.class, "https://PROD-SVC");
	}
}
在上面的示例中是默认配置 由 Spring Cloud OpenFeign 提供。FeignClientsConfiguration.class
PROD-SVC是 Client 将向其发出请求的服务的名称。
Feign 对象定义哪些 annotation 和值在接口上有效。这 autowired bean 提供了对 SpringMVC 注释的支持,而不是 默认的 Feign 本机注释。不建议将 Spring MVC 注释和本机 Feign 注释混合在一起。ContractContract

您也可以在 .Builder`to configure FeignClient not to inherit beans from the parent context. You can do this by overriding calling `inheritParentContext(false)Builderspring-doc.cn

Feign Spring Cloud CircuitBreaker 支持

如果 Spring Cloud CircuitBreaker 位于 Classpath 和 上,则 Feign 将用断路器包装所有方法。spring.cloud.openfeign.circuitbreaker.enabled=truespring-doc.cn

要在每个客户端的基础上禁用 Spring Cloud CircuitBreaker 支持,请创建一个具有“原型”范围的 vanilla,例如:Feign.Builderspring-doc.cn

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

断路器名称遵循此 pattern 。当调用 with 接口且被调用的接口方法没有参数时,则熔断器名称将为 。<feignClientClassName>#<calledMethod>(<parameterTypes>)@FeignClientFooClientbarFooClient#bar()spring-doc.cn

自 2020.0.2 起,断路器名称模式已从 . 使用 2020.0.4 中引入的电路断路器名称可以保留旧模式。<feignClientName>_<calledMethod>CircuitBreakerNameResolver

提供 的 bean,您可以更改断路器名称模式。CircuitBreakerNameResolverspring-doc.cn

@Configuration
public class FooConfiguration {
	@Bean
	public CircuitBreakerNameResolver circuitBreakerNameResolver() {
		return (String feignClientName, Target<?> target, Method method) -> feignClientName + "_" + method.getName();
	}
}

要启用 Spring Cloud CircuitBreaker 组,请将属性设置为 (by default)。spring.cloud.openfeign.circuitbreaker.group.enabledtruefalsespring-doc.cn

使用配置属性配置 CircuitBreaker

您可以通过配置属性配置 CircuitBreaker。spring-doc.cn

例如,如果您有这个 Feign 客户端spring-doc.cn

@FeignClient(url = "http://localhost:8080")
public interface DemoClient {

    @GetMapping("demo")
    String getDemo();
}

您可以通过执行以下操作,使用配置属性对其进行配置spring-doc.cn

spring:
  cloud:
    openfeign:
      circuitbreaker:
        enabled: true
        alphanumeric-ids:
          enabled: true
resilience4j:
  circuitbreaker:
    instances:
      DemoClientgetDemo:
        minimumNumberOfCalls: 69
  timelimiter:
    instances:
      DemoClientgetDemo:
        timeoutDuration: 10s
如果要切换回 Spring Cloud 之前使用的断路器名称 2022.0.0 可以设置为 。spring.cloud.openfeign.circuitbreaker.alphanumeric-ids.enabledfalse

Feign Spring Cloud CircuitBreaker 回退

Spring Cloud CircuitBreaker 支持回退的概念:当电路打开或出现错误时执行的默认代码路径。要为给定启用回退,请将 set 属性设置为实现回退的类名。您还需要将实现声明为 Spring Bean。@FeignClientfallbackspring-doc.cn

@FeignClient(name = "test", url = "http://localhost:${server.port}/", fallback = Fallback.class)
protected interface TestClient {

	@GetMapping("/hello")
	Hello getHello();

	@GetMapping("/hellonotfound")
	String getException();

}

@Component
static class Fallback implements TestClient {

	@Override
	public Hello getHello() {
		throw new NoFallbackAvailableException("Boom!", new RuntimeException());
	}

	@Override
	public String getException() {
		return "Fixed response";
	}

}

如果需要访问导致回退触发器的原因,可以在 .fallbackFactory@FeignClientspring-doc.cn

@FeignClient(name = "testClientWithFactory", url = "http://localhost:${server.port}/",
			fallbackFactory = TestFallbackFactory.class)
protected interface TestClientWithFactory {

	@GetMapping("/hello")
	Hello getHello();

	@GetMapping("/hellonotfound")
	String getException();

}

@Component
static class TestFallbackFactory implements FallbackFactory<FallbackWithFactory> {

	@Override
	public FallbackWithFactory create(Throwable cause) {
		return new FallbackWithFactory();
	}

}

static class FallbackWithFactory implements TestClientWithFactory {

	@Override
	public Hello getHello() {
		throw new NoFallbackAvailableException("Boom!", new RuntimeException());
	}

	@Override
	public String getException() {
		return "Fixed response";
	}

}

Feign 和@Primary

当将 Feign 与 Spring Cloud CircuitBreaker 回退一起使用时,同一类型中有多个 bean。这将导致 不起作用,因为没有一个 bean,或者一个标记为 primary 的 bean。为了解决这个问题, Spring Cloud OpenFeign 将所有 Feign 实例标记为 ,以便 Spring Framework 将知道要注入哪个 bean。在某些情况下,这可能并不可取。要关闭此行为,请将 的属性设置为 false。ApplicationContext@Autowired@Primaryprimary@FeignClientspring-doc.cn

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

Feign Inheritance 支持

Feign 通过单继承接口支持样板 API。 这允许将常见操作分组到方便的 base interfaces 中。spring-doc.cn

UserService.java
public interface UserService {

	@GetMapping("/users/{id}")
	User getUser(@PathVariable("id") long id);
}
UserResource.java
@RestController
public class UserResource implements UserService {

}
UserClient.java
@FeignClient("users")
public interface UserClient extends UserService {

}
@FeignClient不应在服务器和客户端之间共享接口,并且不再支持使用 ON 类级别对接口进行注释。@FeignClient@RequestMapping

假请求/响应压缩

您可以考虑为您的 假装请求。您可以通过启用以下属性之一来执行此操作:spring-doc.cn

spring.cloud.openfeign.compression.request.enabled=true
spring.cloud.openfeign.compression.response.enabled=true

假请求压缩为您提供的设置类似于您为 Web 服务器设置的设置:spring-doc.cn

spring.cloud.openfeign.compression.request.enabled=true
spring.cloud.openfeign.compression.request.mime-types=text/xml,application/xml,application/json
spring.cloud.openfeign.compression.request.min-request-size=2048

这些属性允许您选择压缩媒体类型和最小请求阈值长度。spring-doc.cn

当请求与 中设置的 MIME 类型和 中设置的大小匹配时,将导致将压缩标头添加到请求中。 标头的功能是向服务器发出信号,表明客户端需要压缩的正文。服务器端应用程序负责根据客户端提供的标头提供压缩的正文。spring.cloud.openfeign.compression.request.mime-typesspring.cloud.openfeign.compression.request.min-request-sizespring.cloud.openfeign.compression.request.enabled=truespring-doc.cn

由于 OkHttpClient 使用“透明”压缩,如果存在 or 标头,则将其禁用,因此当 Classpath 中存在该压缩并设置为 .content-encodingaccept-encodingfeign.okhttp.OkHttpClientspring.cloud.openfeign.okhttp.enabledtrue

Feign logging (假日志记录)

为创建的每个 Feign 客户端创建一个 Logger。默认情况下,Logger 的名称是用于创建 Feign Client 端的接口的完整类名。假日志记录仅响应级别。DEBUGspring-doc.cn

application.yml
logging.level.project.user.UserClient: DEBUG

您可以为每个客户端配置的对象告诉 Feign 要记录多少。选项包括:Logger.Levelspring-doc.cn

  • NONE、无日志记录 (DEFAULT)。spring-doc.cn

  • BASIC,仅记录请求方法和 URL 以及响应状态代码和执行时间。spring-doc.cn

  • HEADERS,记录基本信息以及请求和响应标头。spring-doc.cn

  • FULL,记录请求和响应的标头、正文和元数据。spring-doc.cn

例如,以下会将 设置为 :Logger.LevelFULLspring-doc.cn

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

Feign Capability 支持

Feign 功能公开核心 Feign 组件,以便可以修改这些组件。例如,功能可以采用 、 装饰它,并将装饰后的实例返回给 Feign。 对 Micrometer 的支持就是一个很好的真实示例。请参阅 Micrometer Support (千分尺支持)。Clientspring-doc.cn

创建一个或多个 bean 并将它们放在配置中,可以注册它们并修改相关客户端的行为。Capability@FeignClientspring-doc.cn

@Configuration
public class FooConfiguration {
	@Bean
	Capability customCapability() {
		return new CustomCapability();
	}
}

千分尺支持

如果满足以下所有条件,则创建并注册一个 bean,以便 Micrometer 可以观察您的 Feign 客户端:MicrometerObservationCapabilityspring-doc.cn

  • feign-micrometer位于 Classpath 上spring-doc.cn

  • 一个 bean 可用ObservationRegistryspring-doc.cn

  • Feign Micrometer 属性设置为 (默认情况下)truespring-doc.cn

    • spring.cloud.openfeign.micrometer.enabled=true(适用于所有客户)spring-doc.cn

    • spring.cloud.openfeign.client.config.feignName.micrometer.enabled=true(对于单个客户)spring-doc.cn

如果您的应用程序已经使用 Micrometer,则启用此功能就像将 classpath 放在 classpath 上一样简单。feign-micrometer

您还可以通过以下任一方式禁用该功能:spring-doc.cn

  • 从 Classpath 中排除feign-micrometerspring-doc.cn

  • 将 Feign Micrometer 属性之一设置为falsespring-doc.cn

    • spring.cloud.openfeign.micrometer.enabled=falsespring-doc.cn

    • spring.cloud.openfeign.client.config.feignName.micrometer.enabled=falsespring-doc.cn

spring.cloud.openfeign.micrometer.enabled=false禁用对所有假客户端的 Micrometer 支持,而不管客户端级标志的值如何: 。 如果要启用或禁用每个客户端的 Micrometer 支持,请不要设置和使用 。spring.cloud.openfeign.client.config.feignName.micrometer.enabledspring.cloud.openfeign.micrometer.enabledspring.cloud.openfeign.client.config.feignName.micrometer.enabled

您还可以通过注册自己的 bean 来自定义:MicrometerObservationCapabilityspring-doc.cn

@Configuration
public class FooConfiguration {
	@Bean
	public MicrometerObservationCapability micrometerObservationCapability(ObservationRegistry registry) {
		return new MicrometerObservationCapability(registry);
	}
}

仍然可以与 Feign 一起使用(仅支持度量),您需要禁用 Micrometer support () 并创建一个 bean:MicrometerCapabilityspring.cloud.openfeign.micrometer.enabled=falseMicrometerCapabilityspring-doc.cn

@Configuration
public class FooConfiguration {
	@Bean
	public MicrometerCapability micrometerCapability(MeterRegistry meterRegistry) {
		return new MicrometerCapability(meterRegistry);
	}
}

假装缓存

如果使用 annotation ,则会创建并注册一个 bean,以便您的 Feign Client 端识别其接口上的 Comments:@EnableCachingCachingCapability@Cache*spring-doc.cn

public interface DemoClient {

	@GetMapping("/demo/{filterParam}")
    @Cacheable(cacheNames = "demo-cache", key = "#keyParam")
	String demoEndpoint(String keyParam, @PathVariable String filterParam);
}

您还可以通过 property 禁用该功能 。spring.cloud.openfeign.cache.enabled=falsespring-doc.cn

Spring @RequestMapping 支持

Spring Cloud OpenFeign 提供了对 Spring 注释及其派生注释(例如 、 等)的支持。 注释上的属性(包括 、 、 、 、 和 )将作为请求的内容进行解析。@RequestMapping@GetMapping@PostMapping@RequestMappingvaluemethodparamsheadersconsumesproducesSpringMvcContractspring-doc.cn

请考虑以下示例:spring-doc.cn

使用 属性定义接口。paramsspring-doc.cn

@FeignClient("demo")
public interface DemoTemplate {

        @PostMapping(value = "/stores/{storeId}", params = "mode=upsert")
        Store update(@PathVariable("storeId") Long storeId, Store store);
}

在上面的示例中,请求 URL 解析为 。
params 属性还支持使用多个或仅使用一个:
/stores/storeId?mode=upsertkey=valuekey
spring-doc.cn

  • 当 时,请求 URL 解析为 。params = { "key1=v1", "key2=v2" }/stores/storeId?key1=v1&key2=v2spring-doc.cn

  • 当 时,请求 URL 解析为 。params = "key"/stores/storeId?keyspring-doc.cn

假装@QueryMap支持

Spring Cloud OpenFeign 提供了一个等效的注释,该注释 用于将 POJO 或 Map 参数注释为查询参数 map。@SpringQueryMapspring-doc.cn

例如,该类定义 parameters 和 :Paramsparam1param2spring-doc.cn

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

	// [Getters and setters omitted for brevity]
}

以下 Feign 客户端通过使用 Comments 来使用该类:Params@SpringQueryMapspring-doc.cn

@FeignClient("demo")
public interface DemoTemplate {

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

如果需要对生成的查询参数 map 进行更多控制,可以实现自定义 Bean。QueryMapEncoderspring-doc.cn

HATEOAS 支持

Spring 提供了一些 API 来创建遵循 HATEOAS 原则、Spring HateoasSpring Data REST 的 REST 表示。spring-doc.cn

如果您的项目使用 Starter 或Starters,默认情况下启用 Feign HATEOAS 支持。org.springframework.boot:spring-boot-starter-hateoasorg.springframework.boot:spring-boot-starter-data-restspring-doc.cn

启用 HATEOAS 支持后,允许 Feign 客户端进行序列化 并反序列化 HATEOAS 表示模型:EntityModelCollectionModelPagedModelspring-doc.cn

@FeignClient("demo")
public interface DemoTemplate {

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

Spring @MatrixVariable 支持

Spring Cloud OpenFeign 提供了对 Spring 注解的支持。@MatrixVariablespring-doc.cn

如果将 map 作为方法参数传递,则通过将 map 中的键值对与 .@MatrixVariable=spring-doc.cn

如果传递了不同的对象,则注解中提供的(如果已定义)或带注解的变量名称为 使用 .name@MatrixVariable=spring-doc.cn

重要

尽管在服务器端, Spring 不要求用户将路径段占位符命名为与矩阵变量名称相同的名称,因为在客户端上太模糊了,Spring Cloud OpenFeign 要求你添加一个路径段占位符,其名称与 Comments 中提供的名称(如果已定义)或带注释的变量名称相匹配。name@MatrixVariablespring-doc.cn

例如:spring-doc.cn

@GetMapping("/objects/links/{matrixVars}")
Map<String, List<String>> getObjects(@MatrixVariable Map<String, List<String>> matrixVars);

请注意,变量 name 和路径段占位符都称为 。matrixVarsspring-doc.cn

@FeignClient("demo")
public interface DemoTemplate {

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

假支持CollectionFormat

我们通过提供 annotation 来支持。 您可以通过传递 desired as annotation 值来注释 Feign 客户端方法(或影响所有方法的整个类)。feign.CollectionFormat@CollectionFormatfeign.CollectionFormatspring-doc.cn

在以下示例中,使用 format 而不是 default 来处理方法。CSVEXPLODEDspring-doc.cn

@FeignClient(name = "demo")
protected interface DemoFeignClient {

    @CollectionFormat(feign.CollectionFormat.CSV)
    @GetMapping(path = "/test")
    ResponseEntity performRequest(String test);

}

反应式支持

由于在 Spring Cloud OpenFeign 积极开发时,OpenFeign 项目不支持反应式客户端,例如 Spring WebClient,因此也无法将此类支持添加到 Spring Cloud OpenFeign 中。spring-doc.cn

由于 Spring Cloud OpenFeign 项目现在被认为功能完整,因此即使它在上游项目中可用,我们也不打算添加支持。我们建议迁移到 Spring Interface Clients。那里支持阻塞和反应堆栈。spring-doc.cn

早期初始化错误

我们不鼓励在应用程序生命周期的早期阶段使用 Feign 客户端,同时处理配置和初始化 bean。不支持在 bean 初始化期间使用 clients。spring-doc.cn

同样,根据您使用 Feign 客户端的方式,您可能会在启动应用程序时看到初始化错误。要临时解决这个问题,您可以使用 when autowiring your client。ObjectProviderspring-doc.cn

@Autowired
ObjectProvider<TestFeignClient> testFeignClient;

Spring Data 支持

如果 Jackson Databind 和 Spring Data Commons 在 Classpath 上,则 和 的转换器将自动添加。org.springframework.data.domain.Pageorg.springframework.data.domain.Sortspring-doc.cn

要禁用此行为,请将spring-doc.cn

spring.cloud.openfeign.autoconfiguration.jackson.enabled=false

有关详细信息,请参阅。org.springframework.cloud.openfeign.FeignAutoConfiguration.FeignJacksonConfigurationspring-doc.cn

弹簧支撑@RefreshScope

如果启用了 Feign 客户端刷新,则每个 Feign 客户端都将使用以下方式创建:spring-doc.cn

  • feign.Request.Options作为刷新范围的 Bean。这意味着可以针对任何 Feign 客户端实例刷新 和 等属性。connectTimeoutreadTimeoutspring-doc.cn

  • 包装在 .这意味着 Feign 客户端的 URL(如果已定义) with 属性,可以针对任何 Feign 客户端实例进行刷新。org.springframework.cloud.openfeign.RefreshableUrlspring.cloud.openfeign.client.config.{feignName}.urlspring-doc.cn

您可以通过 刷新这些属性。POST /actuator/refreshspring-doc.cn

默认情况下,Feign 客户端中的刷新行为处于禁用状态。使用以下属性启用刷新行为:spring-doc.cn

spring.cloud.openfeign.client.refresh-enabled=true
请勿使用注释对接口进行注释。@FeignClient@RefreshScope

OAuth2 支持

可以通过将依赖项添加到您的项目并设置以下标志来启用 OAuth2 支持:spring-boot-starter-oauth2-clientspring-doc.cn

spring.cloud.openfeign.oauth2.enabled=true

当该标志设置为 true 并且存在 oauth2 客户端上下文资源详细信息时,将创建一个类的 bean。在每个请求之前,侦听器会解析所需的访问令牌并将其作为标头包含在内。 使用 to get 来保存一个 .如果用户使用该属性指定了 OAuth2,则该 OAuth2 将用于检索令牌。如果未检索到令牌或未指定 ,则将使用从主机 segment 检索到的令牌。OAuth2AccessTokenInterceptorOAuth2AccessTokenInterceptorOAuth2AuthorizedClientManagerOAuth2AuthorizedClientOAuth2AccessTokenclientRegistrationIdspring.cloud.openfeign.oauth2.clientRegistrationIdclientRegistrationIdserviceIdurlspring-doc.cn

提示

使用 as OAuth2 客户端 registrationId 便于负载均衡的 Feign 客户端。对于非负载均衡的,基于属性是一种合适的方法。serviceIdclientRegistrationIdspring-doc.cn

提示

如果不想使用 的默认设置,则可以在配置中实例化此类型的 bean。OAuth2AuthorizedClientManagerspring-doc.cn

转换负载均衡的 HTTP 请求

您可以使用 selected 来转换负载均衡的 HTTP 请求。ServiceInstancespring-doc.cn

对于 ,您需要实现和定义 ,如下所示:RequestLoadBalancerFeignRequestTransformerspring-doc.cn

@Bean
public LoadBalancerFeignRequestTransformer transformer() {
	return new LoadBalancerFeignRequestTransformer() {

		@Override
		public Request transformRequest(Request request, ServiceInstance instance) {
			Map<String, Collection<String>> headers = new HashMap<>(request.headers());
			headers.put("X-ServiceId", Collections.singletonList(instance.getServiceId()));
			headers.put("X-InstanceId", Collections.singletonList(instance.getInstanceId()));
			return Request.create(request.httpMethod(), request.url(), headers, request.body(), request.charset(),
					request.requestTemplate());
		}
	};
}

如果定义了多个转换器,则按照定义 bean 的顺序应用它们。 或者,您可以使用 来指定顺序。LoadBalancerFeignRequestTransformer.DEFAULT_ORDERspring-doc.cn

X-Forwarded 标头支持

X-Forwarded-Host并且支持可以通过设置以下标志来启用:X-Forwarded-Protospring-doc.cn

spring.cloud.loadbalancer.x-forwarded.enabled=true

向假客户端提供 URL 的支持方法

您可以通过以下任一方式提供 Feign 客户端的 URL:spring-doc.cn

该 URL 在注释中提供。@FeignClientspring-doc.cn

@FeignClient(name="testClient", url="http://localhost:8081")spring-doc.cn

URL 是从注释的属性解析的,无需负载均衡。urlspring-doc.cn

该 URL 在注释和 configuration 属性。@FeignClientspring-doc.cn

@FeignClient(name="testClient", url="http://localhost:8081")和 定义为application.ymlspring.cloud.openfeign.client.config.testClient.url=http://localhost:8081spring-doc.cn

URL 是从注释的属性解析的,无需负载均衡。 配置属性中提供的 URL 将保持未使用状态。urlspring-doc.cn

该 URL 未在注释中提供,但在配置属性中提供。@FeignClientspring-doc.cn

@FeignClient(name="testClient")和 定义为application.ymlspring.cloud.openfeign.client.config.testClient.url=http://localhost:8081spring-doc.cn

URL 是从配置属性解析的,无需负载均衡。如果,则可以刷新配置属性中定义的 URL,如 Spring RefreshScope 支持中所述。spring.cloud.openfeign.client.refresh-enabled=truespring-doc.cn

该 URL 既未在 annotation 中提供,也未在配置属性中提供。@FeignClientspring-doc.cn

@FeignClient(name="testClient")spring-doc.cn

URL 是通过 annotation 的属性解析的,具有负载平衡。namespring-doc.cn

AOT 和本机映像支持

Spring Cloud OpenFeign 支持 Spring AOT 转换和本机图像,但是,仅在禁用刷新模式、禁用 Feign 客户端刷新(默认设置)和禁用惰性 @FeignClient 属性分辨率(默认设置)的情况下。spring-doc.cn

如果要以 AOT 或本机映像模式运行 Spring Cloud OpenFeign 客户端,请确保设置为 。spring.cloud.refresh.enabledfalse
如果要以 AOT 或本机映像模式运行 Spring Cloud OpenFeign 客户端,请确保未设置为 。spring.cloud.openfeign.client.refresh-enabledtrue
如果要以 AOT 或本机映像模式运行 Spring Cloud OpenFeign 客户端,请确保未设置为 。spring.cloud.openfeign.lazy-attributes-resolutiontrue
但是,如果通过 properties 设置值,则可以通过使用 flag 运行图像来覆盖该值。为了启用覆盖,在构建时还必须通过 properties 而不是 attribute 设置值。url@FeignClienturl-Dspring.cloud.openfeign.client.config.[clientId].url=[url]url@FeignClient

配置属性

要查看所有 Spring Cloud OpenFeign 相关配置属性的列表,请查看附录页面spring-doc.cn