1. 声明式 REST 客户端：Feign (1. Declarative REST Client: Feign) _ Spring Cloud OpenFeign3.1.9中文文档(官方文档中文翻译)|Spring 教程 —

1. 声明式 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

1.1. 如何包含 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();

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

    @RequestMapping(method = RequestMethod.DELETE, value = "/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，可以配置服务器列表在外部配置中使用 SimpleDiscoveryClient。spring-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)

1.2. 覆盖 Feign 默认值

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

Spring Cloud 允许您通过使用声明其他配置（在之上）来完全控制假客户端。例：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
MicrometerCapabilitymicrometerCapability：如果在 Classpath 上并且可用feign-micrometerMeterRegistryspring-doc.cn
CachingCapabilitycachingCapability：如果使用 annotation。可以通过以下方式禁用。@EnableCachingfeign.cache.enabledspring-doc.cn
ContractfeignContract 的SpringMvcContractspring-doc.cn
Feign.BuilderfeignBuilder 中：FeignCircuitBreaker.Builderspring-doc.cn
ClientfeignClient：如果 Spring Cloud LoadBalancer 在 Classpath 上，则使用。如果它们都不在 Classpath 上，则使用默认的假客户端。FeignBlockingLoadBalancerClientspring-doc.cn

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

可以通过分别将 or 或设置为 OkHttpClient 和 ApacheHttpClient 以及 ApacheHC5 假客户端，并将它们放在 Classpath 上来使用。您可以通过提供 Bean 来定制使用 Apache 或使用 OK HTTP 或使用 Apache HC5 时使用的 Bean。feign.okhttp.enabledfeign.httpclient.enabledfeign.httpclient.hc5.enabledtrueorg.apache.http.impl.client.CloseableHttpClientokhttp3.OkHttpClientorg.apache.hc.client5.http.impl.classic.CloseableHttpClientspring-doc.cn

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

Logger.Levelspring-doc.cn
Retryerspring-doc.cn
ErrorDecoderspring-doc.cn
Request.Optionsspring-doc.cn
Collection<RequestInterceptor>spring-doc.cn
SetterFactoryspring-doc.cn
QueryMapEncoderspring-doc.cn
Capability (MicrometerCapability，并且默认提供）CachingCapabilityspring-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

feign:
    client:
        config:
            feignName:
                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
                decode404: false
                encoder: com.example.SimpleEncoder
                decoder: com.example.SimpleDecoder
                contract: com.example.SimpleContract
                capabilities:
                    - com.example.FooCapability
                    - com.example.BarCapability
                queryMapEncoder: com.example.SimpleQueryMapEncoder
                metrics.enabled: false

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

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

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

您可以使用和指定查询参数和标头，这些参数和标头将与名为 .feign.client.config.feignName.defaultQueryParametersfeign.client.config.feignName.defaultRequestHeadersfeignNamespring-doc.cn

application.ymlspring-doc.cn

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

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

如果我们想创建多个具有相同名称或 url 的假客户端这样它们就会指向同一个服务器，但每个服务器都有不同的自定义配置我们必须使用的 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 客户端不对斜杠字符进行编码。您可以通过将的值设置为来更改此行为。/feign.client.decodeSlashfalse

1.2.1. `SpringEncoder` 配置

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

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

1.3. 超时处理

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

connectTimeout防止由于服务器处理时间长而阻止调用方。spring-doc.cn
readTimeout从建立连接时开始应用，并在返回响应时间过长时触发。spring-doc.cn

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

1.4. 手动创建假客户端

在某些情况下，可能需要以一种不是可以使用上述方法。在这种情况下，您可以使用 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, MicrometerCapability micrometerCapability) {
        this.fooClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .addCapability(micrometerCapability)
                .requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
                .target(FooClient.class, "https://PROD-SVC");

        this.adminClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .addCapability(micrometerCapability)
                .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 本机注释。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

1.5. Feign Spring Cloud CircuitBreaker 支持

如果 Spring Cloud CircuitBreaker 位于 Classpath 和上，则 Feign 将用断路器包装所有方法。feign.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）。feign.circuitbreaker.group.enabledtruefalsespring-doc.cn

1.6. 使用配置属性配置 CircuitBreaker

您可以通过配置属性配置 CircuitBreaker。To do 设置为。因为您不能在配置属性名称中使用、、等字符，我们需要更改 OpenFeign 生成的断路器 ID 的命名规则。以上内容 property 将为您执行此操作。feign.circuitbreaker.alphanumeric-ids.enabledtrue#(),spring-doc.cn

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

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

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

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

feign:
  circuitbreaker:
    enabled: true
    alphanumeric-ids:
      enabled: true
resilience4j:
  circuitbreaker:
    instances:
      DemoClientgetDemo:
        minimumNumberOfCalls: 69
  timelimiter:
    instances:
      DemoClientgetDemo:
        timeoutDuration: 10s

1.7. 假装 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 {

    @RequestMapping(method = RequestMethod.GET, value = "/hello")
    Hello getHello();

    @RequestMapping(method = RequestMethod.GET, value = "/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 {

    @RequestMapping(method = RequestMethod.GET, value = "/hello")
    Hello getHello();

    @RequestMapping(method = RequestMethod.GET, value = "/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";
    }

}

1.8. 假装和`@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
}

1.9. 假继承支持

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

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 {

}

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

1.10. 假装请求 / 响应压缩

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

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

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

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

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

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

1.11. 假装日志记录

为创建的每个 Feign 客户端创建一个 Logger。默认情况下，Logger 的名称是用于创建 Feign 客户端的接口的完整类名。假日志记录仅响应级别。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;
    }
}

1.12. Feign Capability 支持

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

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

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

1.13. 假量度

如果满足以下所有条件，则创建并注册一个 bean，以便您的 Feign 客户端将度量发布到 Micrometer：MicrometerCapabilityspring-doc.cn

feign-micrometer位于 Classpath 上spring-doc.cn
一个 bean 可用MeterRegistryspring-doc.cn
Feign Metrics 属性设置为（默认情况下）truespring-doc.cn
- feign.metrics.enabled=true（适用于所有客户）spring-doc.cn
- feign.client.config.feignName.metrics.enabled=true（对于单个客户）spring-doc.cn

如果您的应用程序已经使用 Micrometer，则启用 metrics 就像将 Metrics 放在 Classpath 上一样简单。feign-micrometer

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

从 Classpath 中排除feign-micrometerspring-doc.cn
将其中一个 Feign metrics 属性设置为falsespring-doc.cn
- feign.metrics.enabled=falsespring-doc.cn
- feign.client.config.feignName.metrics.enabled=falsespring-doc.cn

feign.metrics.enabled=false禁用对所有 Feign 客户端的度量支持，而不管客户端级别标志的值如何：。如果要为每个客户端启用或禁用 merics，请不要设置和使用。feign.client.config.feignName.metrics.enabledfeign.metrics.enabledfeign.client.config.feignName.metrics.enabled

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

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

1.14. 假装缓存

如果使用 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 禁用该功能。feign.cache.enabled=falsespring-doc.cn

1.15. 假装@QueryMap支持

OpenFeign 注解支持将 POJO 用作 GET 参数映射。不幸的是，默认的 OpenFeign QueryMap 注释是与 Spring 不兼容，因为它缺少属性。@QueryMapvaluespring-doc.cn

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]
}

以下假客户端通过使用 annotation 来使用该类：Params@SpringQueryMapspring-doc.cn

@FeignClient("demo")
public interface DemoTemplate {

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

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

1.16. HATEOAS 支持

Spring 提供了一些 API 来创建遵循 HATEOAS 原则、Spring Hateoas 和 Spring 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 表示模型：EntityModel、CollectionModel 和 PagedModel。spring-doc.cn

@FeignClient("demo")
public interface DemoTemplate {

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

1.17. 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();
}

1.18. 假装 `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);

}

1.19. 反应式支持

由于 OpenFeign 项目目前不支持反应式客户端，例如 Spring WebClient，因此 Spring Cloud OpenFeign 也不支持。spring-doc.cn

在此之前，我们建议使用 feign-reactive 来支持 Spring WebClient。spring-doc.cn

1.19.1. 早期初始化错误

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

@Autowired
ObjectProvider<TestFeignClient> testFeignClient;

1.20. Spring Data 支持

您可以考虑启用 Jackson Modules 来支持和解码。org.springframework.data.domain.Pageorg.springframework.data.domain.Sortspring-doc.cn

feign.autoconfiguration.jackson.enabled=true

1.21. Spring `@RefreshScope` 支持

如果启用了 Feign Client 刷新，则每个 Feign Client 端都将创建为刷新范围的 Bean。这意味着可以通过针对任何 Feign 客户端实例刷新和等属性。feign.Request.OptionsconnectTimeoutreadTimeoutPOST /actuator/refreshspring-doc.cn

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

feign.client.refresh-enabled=true

请勿使用注释对接口进行注释。@FeignClient@RefreshScope

1.22. OAuth2 支持

可以通过设置以下标志来启用 OAuth2 支持：spring-doc.cn

feign.oauth2.enabled=true

1.22.1. 已弃用的 OAuth2 支持

当该标志设置为，并且它存在于 Classpath 中，并且存在 oauth2 客户端上下文资源详细信息并且存在 bean 时，将创建一个 class 为的 bean。在每个请求之前，侦听器会解析所需的访问令牌并将其作为标头包含在内。有时，当为 Feign 客户端启用负载均衡时，您可能还希望使用负载均衡来获取访问令牌。为此，您应该确保负载均衡器位于 Classpath（spring-cloud-starter-loadbalancer）上，并通过设置以下标志显式启用 OAuth2FeignRequestInterceptor 的负载平衡：truespring-security-oauth2-autoconfigureOAuth2ClientContextOAuth2ProtectedResourceDetailsOAuth2FeignRequestInterceptorspring-doc.cn

feign.oauth2.load-balanced=true

警告: 如上所述的 OAuth2 支持现已弃用，因为生命周期已结束。请改用下面描述的模式。spring-security-oauth2-autoconfigurespring-doc.cn

1.22.2. 当前的 OAuth2 支持

当该标志设置为 true 并且存在于 Classpath 中时，将创建一个 class 的 bean。在每个请求之前，侦听器会解析所需的访问令牌并将其作为标头包含在内。使用 to get 来保存一个 .如果用户使用该属性指定了 OAuth2，则该 OAuth2 将用于检索令牌。如果未检索到令牌或未指定，则将使用从主机 segment 检索到的令牌。feign.client.refresh-enabledspring-security-oauth2-clientOAuth2AccessTokenInterceptorOAuth2AccessTokenInterceptorOAuth2AuthorizedClientManagerOAuth2AuthorizedClientOAuth2AccessTokenclientRegistrationIdfeign.oauth2.clientRegistrationIdclientRegistrationIdserviceIdurlspring-doc.cn

提示: 使用 as OAuth2 客户端 registrationId 便于负载均衡的 Feign 客户端。对于非负载均衡的，基于属性是一种合适的方法。serviceIdclientRegistrationIdspring-doc.cn
提示: 如果不想使用的默认设置，则可以在配置中实例化此类型的 bean。OAuth2AuthorizedClientManagerspring-doc.cn