OpenFeign：Spring Cloud声明式服务调用组件

原创于 2025-12-31 14:03:16 发布 · 973 阅读

11 ·

CC 4.0 BY-SA版权

文章标签：

#spring cloud #spring #后端

1.概述

1.1 Feign是什么？

Feign是一个声明式的Web服务客户端（Web服务客户端就是Http客户端），让编写Web服务客户端变得非常容易，只需创建一个接口并在接口上添加注解即可。

Java当中常见的Http客户端有很多，除了Feign，类似的还有Apache 的 HttpClient 以及OKHttp3，还有SpringBoot自带的RestTemplate这些都是Java当中常用的HTTP 请求工具。

1.2 为什么要使用Feign

服务之间如果需要相互访问，可以使用RestTemplate，也可以使用 Feign客户端访问。它默认会使用Ribbon来实现负载均衡。

Feign 旨在使编写 JAVA HTTP 客户端变得更加简单，Feign 简化了RestTemplate代码，实现了Ribbon负载均衡，使代码变得更加简洁，也少了客户端调用的代码，使用 Feign 实现负载均衡是首选方案，只需要创建一个接口，然后在上面添加注解即可。

Feign 是声明式服务调用组件，其核心就是：像调用本地方法一样调用远程方法，无感知远程 HTTP 请求。让开发者调用远程接口就跟调用本地方法一样的体验，开发者完全无感知这是远程方法，无需关注与远程的交互细节，更无需关注分布式环境开发。

1.3 OpenFeign

Netflix Feign 是 Netflix 公司发布的一种实现负载均衡和服务调用的开源组件。Spring Cloud 将其与 Netflix 中的其他开源服务组件（例如 Eureka、Ribbon 以及 Hystrix 等）一起整合进 Spring Cloud Netflix 模块中，整合后全称为 Spring Cloud Netflix Feign。
Feign 对 Ribbon 进行了集成，利用 Ribbon 维护了一份可用服务清单，并通过 Ribbon 实现了客户端的负载均衡。
Feign 是一种声明式服务调用组件，它在 RestTemplate 的基础上做了进一步的封装。通过 Feign，我们只需要声明一个接口并通过注解进行简单的配置（类似于 Dao 接口上面的 Mapper 注解一样）即可实现对 HTTP 接口的绑定。
通过 Feign，我们可以像调用本地方法一样来调用远程服务，而完全感觉不到这是在进行远程调用。
Feign 支持多种注解，例如 Feign 自带的注解以及 JAX-RS 注解等，但遗憾的是 Feign 本身并不支持 Spring MVC 注解，这无疑会给广大 Spring 用户带来不便。
2019 年 Netflix 公司宣布 Feign 组件正式进入停更维护状态，于是 Spring 官方便推出了一个名为 OpenFeign 的组件作为 Feign 的替代方案。

OpenFeign 全称 Spring Cloud OpenFeign，它是 Spring 官方推出的一种声明式服务调用与负载均衡组件，它的出现就是为了替代进入停更维护状态的 Feign。

OpenFeign 是 Spring Cloud 对 Feign 的二次封装，它具有 Feign 的所有功能，并在 Feign 的基础上增加了对 Spring MVC 注解的支持，例如 @RequestMapping、@GetMapping 和 @PostMapping 等。

1.4 OpenFeign 常用注解

使用 OpenFegin 进行远程服务调用时，常用注解如下表。

注解	说明
@FeignClient	该注解用于通知 OpenFeign 组件对 @RequestMapping 注解下的接口进行解析，并通过动态代理的方式产生实现类，实现负载均衡和服务调用。
@EnableFeignClients	该注解用于开启 OpenFeign 功能，当 Spring Cloud 应用启动时，OpenFeign 会扫描标有 @FeignClient 注解的接口，生成代理并注册到 Spring 容器中。
@RequestMapping	Spring MVC 注解，在 Spring MVC 中使用该注解映射请求，通过它来指定控制器（Controller）可以处理哪些 URL 请求，相当于 Servlet 中 web.xml 的配置。
@GetMapping	Spring MVC 注解，用来映射 GET 请求，它是一个组合注解，相当于 @RequestMapping(method = RequestMethod.GET) 。
@PostMapping	Spring MVC 注解，用来映射 POST 请求，它是一个组合注解，相当于 @RequestMapping(method = RequestMethod.POST) 。

Spring Cloud Finchley 及以上版本一般使用 OpenFeign 作为其服务调用组件。由于 OpenFeign 是在 2019 年 Feign 停更进入维护后推出的，因此大多数 2019 年及以后的新项目使用的都是 OpenFeign，而 2018 年以前的项目一般使用 Feign。

@FeignClient

Spring Cloud 应用在启动时，OpenFeign 会扫描标有 @FeignClient 注解的接口生成代理，并注人到 Spring 容器中。

使用OpenFeign就一定会用到这个注解，@FeignClient属性如下：

name：指定该类的容器名称，类似于@Service（容器名称）
url: url一般用于调试，可以手动指定@FeignClient调用的地址
decode404:当发生http 404错误时，如果该字段位true，会调用decoder进行解码，否则抛出FeignException
configuration: Feign配置类，可以自定义Feign的Encoder、Decoder、LogLevel、Contract
fallback: 定义容错的处理类，当调用远程接口失败或超时时，会调用对应接口的容错逻辑，fallback指定的类必须实现@FeignClient标记的接口
fallbackFactory: 工厂类，用于生成fallback类示例，通过这个属性我们可以实现每个接口通用的容错逻辑，减少重复的代码
path: 定义当前FeignClient的统一前缀，当我们项目中配置了server.context-path,server.servlet-path时使用

@SpringQueryMap 介绍 ***

@SpringQueryMap 注解是 spring-cloud-openfeign-core:2.1.0.RELEASE 开始引入的一个新注解，用于将 POJO 或 Map ，映射为 GET 方法的参数。
虽然 OpenFeign 的 @QueryMap注解支持将 POJO 映射到 GET 方法的参数上。但由于缺少value属性而与 Spring 不兼容，为此 Spring Cloud OpenFeign 提供了等效的@SpringQueryMap注解，用于将 POJO 或 Map ，映射为 GET 方法的参数。
@SpringQueryMap 注解用法也很简单，假设有一个叫 StudentDTO的类。
使用@RequestParam
使用@SpringQueryMap
@SpringQueryMap 注解不解析父类字段

例：StudentDTO类继承了 PageDTO;

然后同样使用 @SpringQueryMap 来映射。

上面的写法等效于 String demoEndpoint(@RequestParam String name, @RequestParam String age);

可以看到 StudentDTO exdents PageDTO 中的参数并没有映射上去。

原因：

其实，准确来说，“@SpringQueryMap 注解不解析父类字段” 这种说法并不准确，因为这并不是 @SpringQueryMap 的问题，原生的 OpenFeign 在使用原生的 @QueryMap 注解时，也会出现这个问题。

问题的重点不在于 @QueryMap 注解而是在于 OpenFeign 的 encode 上。

@QueryMap 对应的 encode 为 QueryMapEncoder, 而从 QueryMapEncoder 源码注释中可以看出，FieldQueryMapEncoder 虽然是 QueryMapEncoder 的默认实现，但是已经不推荐使用了，其中一个原因就是因为它不会去映射 POJO 的父类属性。

解决方案

知道了原因，解决方案就很简单了，跟换为 @QueryMap 的 QueryMapEncoder 为推荐的 BeanQueryMapEncoder 就行了。

然后使用上面自定义的配置，如果想让它全局生效，就在 Spting boot 启动类上。

如果只想让它在单个 FeignClient 上生效，就加上 configuration 属性。

1.5 Feign VS OpenFeign

下面我们就来对比下 Feign 和 OpenFeign 的异同。

相同点

Feign 和 OpenFegin 具有以下相同点：

Feign 和 OpenFeign 都是 Spring Cloud 下的远程调用和负载均衡组件。
Feign 和 OpenFeign 作用一样，都可以实现服务的远程调用和负载均衡。
Feign 和 OpenFeign 都对 Ribbon 进行了集成，都利用 Ribbon 维护了可用服务清单，并通过 Ribbon 实现了客户端的负载均衡。
Feign 和 OpenFeign 都是在服务消费者（客户端）定义服务绑定接口并通过注解的方式进行配置，以实现远程服务的调用。

不同点

Feign 和 OpenFeign 具有以下不同：

Feign 和 OpenFeign 的依赖项不同，Feign 的依赖为 spring-cloud-starter-feign，而 OpenFeign 的依赖为 spring-cloud-starter-openfeign。
Feign 和 OpenFeign 支持的注解不同，Feign 支持 Feign 注解和 JAX-RS 注解，但不支持 Spring MVC 注解；OpenFeign 除了支持 Feign 注解和 JAX-RS 注解外，还支持 Spring MVC 注解。
OpenFeign的 @FeignClient可以解析Spring MVC的@RequestMapping注解下的接口，并通过动态代理方式产生实现类，实现类中做负载均衡调用服务。

1.6 Feign的实现流程

首先通过 @EnableFelgnClients注解开启FeignClient的功能，只有这个注解存在，才会在程序启动时开启对 @FeignClient注解的包扫描。
根据Feign的规则实现接口，并在接口上加上@FeignClient注解。
程序启动后，会进行包扫描，扫描所有的@FeignClient注解的类，并将这些信息注入到lOC容器中。
当接口中的方法被调用时，通过JDK的动态代理生成具体的 RequestTemplate模板对象。
根据RequestTemplate再生成HTTP的Request对象。
Request对象交给Client处理，其中Client网络请求框架可以是 HttpURLConnection, HttpClient与OkHttp（主要看依赖是什么)。
最后，Client被封装到LoadBalanceClient类，该类结合Ribbon做到了负载均衡。

2.OpenFeign 使用

2.1 OpenFeign 实现远程服务调用

2.1.1 创建一个名为 micro-service-cloud-consumer-dept-feign 的 Spring Boot 模块，pom.xml 中添加依赖

2.1.2 application.yml

2.1.3 在service 包下创建一个名为 DeptFeignService 的接口，并在该接口上使用 @FeignClient 注解实现对服务接口的绑定，代码如下。

在编写服务绑定接口时，需要注意以下 2 点：

在 @FeignClient 注解中，value 属性的取值为：服务提供者的服务名，即服务提供者配置文件（application.yml）中 spring.application.name 的取值。
接口中定义的每个方法都与服务提供者（即 micro-service-cloud-provider-dept-8001 等）中 Controller 定义的服务方法对应。

2.1.4 在 controller 包下，创建一个名为 DeptController_Consumer 的 Controller 类，代码如下。

2.1.5 在主启动类上添加 @EnableFeignClients 注解开启 OpenFeign 功能，代码如下。

2.1.6 依次启动服务注册中心集群、服务提供者以及 micro-service-cloud-consumer-dept-feign，启动完成后，使用浏览器访问“http://eureka7001.com/consumer/dept/list”，结果如下图。

OpenFeign 实现服务调用

图1：OpenFeign 实现远程服务调用

7. 连续多次访问“http://eureka7001.com/consumer/dept/list”，结果如下图。

OpenFeign 默认负载均衡

图2：OpenFeign 负载均衡

从图 2 可以看出，由于 OpenFeign 集成了 Ribbon，因此它也实现了客户端的负载均衡，其默认负载均衡策略为轮询策略。

2.2 OpenFeign 超时控制

OpenFeign 客户端的默认超时时间为 1 秒钟，如果服务端处理请求的时间超过 1 秒就会报错。为了避免这样的情况，我们需要对 OpenFeign 客户端的超时时间进行控制。

下面我们就通过一个实例，来演示 OpenFeign 是如何进行超时控制的。

1. 在所有的服务提供者（服务端）的 DeptController 中添加一个响应时间为 5 秒的服务，代码如下。

2. 在 micro-service-cloud-consumer-dept-feign 的 DeptFeignService 接口中添加以下代码，绑定服务端刚刚添加的超时服务。

3. 在 micro-service-cloud-consumer-dept-feign 的 DeptController_Consumer 添加以下代码。

4. 重启所有服务提供者，使用浏览器依次访问“http://eureka7001.com:8001/dept/feign/timeout”、“http://eureka7001.com:8002/dept/feign/timeout”和“http://eureka7001.com:8003/dept/feign/timeout”，确保所有服务提供者提供的超时服务都能正常使用，如下图。

服务提供者超时服务

图3：服务提供者的超时服务
5. 重启 micro-service-cloud-consumer-dept-feign，使用浏览器访问“http://eureka7001.com/consumer/dept/feign/timeout”，结果如下图。

OpenFeign 超时报错

图4：OpenFeign 超时报错
6. 在 micro-service-cloud-consumer-dept-feign 的 application.yml 中添加以下配置，将超时时间设置为 6 秒。

ribbon:
ReadTimeout: 6000 #建立连接所用的时间，适用于网络状况正常的情况下，两端两端连接所用的时间
ConnectionTimeout: 6000 #建立连接后，服务器读取到可用资源的时间

注：由于 OpenFeign 集成了 Ribbon ，其服务调用以及负载均衡在底层都是依靠 Ribbon 实现的，因此 OpenFeign 超时控制也是通过 Ribbon 来实现的。

7. 再次重启 micro-service-cloud-consumer-dept-feign，使用浏览器访问“http://eureka7001.com/consumer/dept/feign/timeout”，结果如下图。

OpenFeign 超时控制

图5：OpenFeign 超时控制

2.3 OpenFeign 日志增强

OpenFeign 提供了日志打印功能，我们可以通过配置调整日志级别，来了解请求的细节。

Feign 为每一个 FeignClient 都提供了一个 feign.Logger 实例，通过它可以对 OpenFeign 服务绑定接口的调用情况进行监控。

OpenFeign 日志打印功能的开启方式比较简单，下面我们就通过一个实例进行演示。

1. 在 micro-service-cloud-consumer-dept-feign 的 application.yml 中配置以下内容。

logging:
level:
#feign 日志以什么样的级别监控该接口
com.example.service.DeptFeignService: debug

以上配置说明如下：

com.example.service.DeptFeignService 是开启 @FeignClient 注解的接口（即服务绑定接口）的完整类名。也可以只配置部分路径，表示监控该路径下的所有服务绑定接口
debug：表示监听该接口的日志级别。

以上配置的含义就是，OpenFeign 以 debug 级别监控 com.example.service.DeptFeignService 接口。

2. 在 config 包下创建一个名为 ConfigBean 的配置类，代码如下。

该配置的作用是通过配置的 Logger.Level 对象告诉 OpenFeign 记录哪些日志内容。

Logger.Level 的具体级别如下：

NONE：不记录任何信息。
BASIC：仅记录请求方法、URL 以及响应状态码和执行时间。
HEADERS：除了记录 BASIC 级别的信息外，还会记录请求和响应的头信息。
FULL：记录所有请求与响应的明细，包括头信息、请求体、元数据等等。

3. 重启 micro-service-cloud-consumer-dept-feign，使用浏览器访问“http://eureka7001.com/consumer/dept/list”，控制台输出如下。

2023-11-12 14:33:07.408 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list] ---> GET http://MICROSERVICECLOUDPROVIDERDEPT/dept/list HTTP/1.1
2023-11-12 14:33:07.408 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list] ---> END HTTP (0-byte body)
2023-11-12 14:33:07.983 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list] <--- HTTP/1.1 200 (574ms)
2023-11-12 14:33:07.983 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list] connection: keep-alive
2023-11-12 14:33:07.983 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list] content-type: application/json
2023-11-12 14:33:07.983 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list] date: Tue, 12 Nov 2023 16:33:07 GMT
2023-11-12 14:33:07.983 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list] keep-alive: timeout=60
2023-11-12 14:33:07.983 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list] transfer-encoding: chunked
2023-11-12 14:33:07.983 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list]
2023-11-12 14:33:07.991 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list] [{"deptNo":1,"deptName":"开发部","dbSource":"bianchengbang_jdbc"},{"deptNo":2,"deptName":"人事部","dbSource":"bianchengbang_jdbc"},{"deptNo":3,"deptName":"财务部","dbSource":"bianchengbang_jdbc"},{"deptNo":4,"deptName":"市场部","dbSource":"bianchengbang_jdbc"},{"deptNo":5,"deptName":"运维部","dbSource":"bianchengbang_jdbc"}]
2023-11-12 14:33:07.991 DEBUG 13388 --- [p-nio-80-exec-2] n.biancheng.c.service.DeptFeignService   : [DeptFeignService#list] <--- END HTTP (341-byte body)

以下提供了四种方式：

1.在@RequestMapping中添加，如下：

2：在方法参数前面添加@RequestHeader注解，如下：

设置多个属性时，可以使用Map，如下：

3.使用@Header注解，如下：

4.实现RequestInterceptor接口（拦截器），如下：

只要通过FeignClient访问的接口都会走这个地方，所以使用的时候要注意一下。

2.5 手动创建 Feign 客户端

@FeignClient无法支持同一service具有多种不同配置的FeignClient，因此，在必要时需要手动build FeignClient。

@FeignClient(value = “CLOUD-PAYMENT-SERVICE”)
以这个为例，假如出现两个服务名称为CLOUD-PAYMENT-SERVICE的FeignClient，项目直接会启动报错，但是有时候我们服务之间调用的地方较多，不可能将所有调用都放到一个FeignClient下，这时候就需要自定义来解决这个问题！
官网当中也明确提供了自定义FeignClient，以下是在官网基础上对自定义FeignClient的一个简单封装，供参考！

首先创建FeignClientConfigurer类，这个类相当于build FeignClient的工具类