From d7b0b5378b8d52de6ba8abd04b7a7983a4e6b89e Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Fri, 1 Apr 2022 20:41:28 +0800 Subject: [PATCH 01/11] =?UTF-8?q?Feign=E6=B5=8B=E8=AF=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- changelog.md | 2 +- .../pom.xml | 19 +++++++ .../com/github/cloud/examples/FeignTest.java | 52 +++++++++++++++++++ 3 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/test/java/com/github/cloud/examples/FeignTest.java diff --git a/changelog.md b/changelog.md index abf9444..22ca5b0 100644 --- a/changelog.md +++ b/changelog.md @@ -912,7 +912,7 @@ public class RibbonLoadBalancerClient implements LoadBalancerClient { } ``` -- reconstructURI方法，重建请求URI，将服务名称替换为服务实例的IP:端口，例如http://provider-application/echo被重建为http://192.168.100.1:8888/echo +- reconstructURI方法，重建请求URI，将服务名称替换为服务实例的IP:端口，例如```http://provider-application/echo``` 被重建为```http://192.168.100.1:8888/echo``` - execute方法，处理http请求 有了RibbonLoadBalancerClient的reconstructURI和execute方法，将所有http请求委托给RibbonLoadBalancerClient即可。其实spring-cloud-commons已经帮我们配置好拦截RestTemplate的http请求委托给RibbonLoadBalancerClient的拦截器LoadBalancerInterceptor，配置类如下: diff --git a/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml index 3bf5f17..a9c5f04 100644 --- a/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml +++ b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml @@ -18,6 +18,12 @@ spring-boot-starter-web + + org.springframework.boot + spring-boot-starter-test + test + + com.github mini-spring-cloud-tutu-discovery @@ -27,6 +33,19 @@ com.github mini-spring-cloud-load-balancer + + + io.github.openfeign + feign-core + test + + + + org.springframework.cloud + spring-cloud-starter-feign + 1.4.7.RELEASE + test + diff --git a/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/test/java/com/github/cloud/examples/FeignTest.java b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/test/java/com/github/cloud/examples/FeignTest.java new file mode 100644 index 0000000..47e0821 --- /dev/null +++ b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/test/java/com/github/cloud/examples/FeignTest.java @@ -0,0 +1,52 @@ +package com.github.cloud.examples; + +import feign.Feign; +import feign.RequestLine; +import org.junit.jupiter.api.Test; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.cloud.openfeign.support.SpringMvcContract; +import org.springframework.web.bind.annotation.GetMapping; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * @author derek(易仁川) + * @date 2022/3/27 + */ +public class FeignTest { + private static Logger logger = LoggerFactory.getLogger(FeignTest.class); + + interface HelloService { + + @RequestLine("GET /hello") + String hello(); + } + + @Test + public void testOpenFeign() { + HelloService helloService = Feign.builder() + .target(HelloService.class, "http://localhost:8080"); + String response = helloService.hello(); + logger.info("response: {}", response); + boolean succ = response.startsWith("Port of the service provider"); + assertThat(succ).isTrue(); + } + + interface WorldService { + + @GetMapping("/world") + String world(); + } + + @Test + public void testSpringCloudOpenFeign() { + WorldService worldService = Feign.builder() + .contract(new SpringMvcContract()) + .target(WorldService.class, "http://localhost:8080"); + String response = worldService.world(); + logger.info("response: {}", response); + boolean succ = response.startsWith("Port of the service provider"); + assertThat(succ).isTrue(); + } +} From b3238e6fdbffb61ef21d2e31f67780e1d7920936 Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Wed, 6 Apr 2022 20:11:20 +0800 Subject: [PATCH 02/11] =?UTF-8?q?=E6=9B=B4=E6=96=B0readme=E5=92=8Cchangelo?= =?UTF-8?q?g?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 8 ++------ changelog.md | 12 ++++++------ 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 0ee9f61..871af07 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # mini-spring-cloud +[![License](https://img.shields.io/badge/license-license-blue)](https://github.com/DerekYRC/mini-spring-cloud) [![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/DerekYRC/mini-spring-cloud) -[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html) [![Stars](https://img.shields.io/github/stars/DerekYRC/mini-spring-cloud)](https://img.shields.io/github/stars/DerekYRC/mini-spring-cloud) [![Forks](https://img.shields.io/github/forks/DerekYRC/mini-spring-cloud)](https://img.shields.io/github/forks/DerekYRC/mini-spring-cloud) @@ -45,8 +45,4 @@ 邮箱：**15521077528@163.com** ## 参考 -- [《精尽 Spring Cloud 学习指南》](http://svip.iocoder.cn/Spring-Cloud/tutorials/) - -## 版权说明 - -本项目可用于个人学习、非商业性或非盈利性用途。将本项目用于其他用途时，须征得本人的书面许可。 \ No newline at end of file +- [《精尽Spring Cloud学习指南》](http://svip.iocoder.cn/Spring-Cloud/tutorials/) \ No newline at end of file diff --git a/changelog.md b/changelog.md index 22ca5b0..ff14ea6 100644 --- a/changelog.md +++ b/changelog.md @@ -3,10 +3,11 @@ 前置知识。阅读spring、springboot、spring cloud三者的源码必须严格按照 spring => springboot => spring cloud 的顺序进行，阅读spring cloud源码的必备前置知识： - spring，推荐本人写的简化版的spring框架 [**mini-spring**](https://github.com/DerekYRC/mini-spring/blob/main/README_CN.md) 。熟悉spring源码，阅读springboot源码会非常轻松。 -- springboot，重点掌握：1、启动流程 2、**自动装配的原理! 自动装配的原理!! 自动装配的原理!!!** 推荐文章: +- spring boot，重点掌握：1、启动流程 2、**自动装配的原理! 自动装配的原理!! 自动装配的原理!!!** 推荐文章: - [《Spring Boot精髓：启动流程源码分析》](https://www.cnblogs.com/java-chen-hao/p/11829344.html) - [《细说SpringBoot的自动装配原理》](https://blog.csdn.net/qq_38526573/article/details/107084943) - [《Spring Boot 自动装配原理》](https://www.cnblogs.com/javaguide/p/springboot-auto-config.html) +- spring cloud，先学会使用再研究源码，切勿本末倒置。推荐[《精尽Spring Cloud学习指南》](http://svip.iocoder.cn/Spring-Cloud/tutorials/) 关于spring cloud。spring cloud是构建通用模式的分布式系统的工具集，通过[**spring-cloud-commons**](https://github.com/spring-cloud/spring-cloud-commons) 定义了统一的抽象API，相当于定义了一套协议标准，具体的实现需要符合这套协议标准。spring cloud官方整合第三方组件Eureka、Ribbon、Hystrix等实现了spring-cloud-netflix，阿里巴巴结合自身的Nacos、Sentinel等实现了spring-cloud-alibaba。本项目基于spring-cloud-commons的协议标准自主开发或整合第三方组件提供具体的实现。 @@ -758,14 +759,13 @@ public class TutuRibbonClientConfiguration { } ``` -每一个Provider服务对应一套ribbon核心API，相互隔离，SpringClientFactory为每一个Provider服务对应的ribbon核心API创建一个子spring应用上下文（ApplicationContext）。 +每一个Provider服务集群（应用名称即spring.application.name相同的所有应用服务提供者）对应一套ribbon核心API。**SpringClientFactory继承自NamedContextFactory，为每一套ribbon核心API创建一个子spring应用上下文（ApplicationContext）**，来隔离不同服务的ribbon核心API配置，可以定制化不同服务的负载均衡规则（扩展篇实现）。 -子spring应用上下文的配置类来自于: +SpringClientFactory的构造函数参数**RibbonClientConfiguration**配置ribbon默认的核心API。 -- SpringClientFactory的构造函数参数RibbonClientConfiguration配置类 -- 修饰RibbonTutuAutoConfiguration的注解指定的属性defaultConfiguration = TutuRibbonClientConfiguration配置类（处理RibbonClients注解的RibbonClientConfigurationRegistrar，会将TutuRibbonClientConfiguration配置类包装为RibbonClientSpecification供SpringClientFactory使用） +修饰RibbonTutuAutoConfiguration配置类的注解RibbonClients引入了**自动配置类RibbonClientConfigurationRegistrar**，将RibbonClients注解指定的defaultConfiguration属性的值即TutuRibbonClientConfiguration配置类**包装为RibbonClientSpecification**。**RibbonClientSpecification作为SpringClientFactory的属性，用来覆盖RibbonClientConfiguration配置类指定的默认的核心API**，比如TutuRibbonClientConfiguration配置类使用TutuServerList替换RibbonClientConfiguration配置类中指定的ConfigurationBasedServerList。 -为了充分理解子spring容器的创建逻辑，可以在下面的测试环节debug如下几个方法: +可能表述得不清楚，为了充分理解子spring容器的创建逻辑，可以在下面的测试环节debug如下几个方法: - RibbonClientConfigurationRegistrar#registerBeanDefinitions - RibbonAutoConfiguration#springClientFactory From cbd9092c4e736e4fcf9eb912dfe2b1fc20b0d1ca Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Thu, 7 Apr 2022 19:54:14 +0800 Subject: [PATCH 03/11] update changelog --- changelog.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/changelog.md b/changelog.md index ff14ea6..d5939f8 100644 --- a/changelog.md +++ b/changelog.md @@ -5,18 +5,17 @@ - spring，推荐本人写的简化版的spring框架 [**mini-spring**](https://github.com/DerekYRC/mini-spring/blob/main/README_CN.md) 。熟悉spring源码，阅读springboot源码会非常轻松。 - spring boot，重点掌握：1、启动流程 2、**自动装配的原理! 自动装配的原理!! 自动装配的原理!!!** 推荐文章: - [《Spring Boot精髓：启动流程源码分析》](https://www.cnblogs.com/java-chen-hao/p/11829344.html) - - [《细说SpringBoot的自动装配原理》](https://blog.csdn.net/qq_38526573/article/details/107084943) - - [《Spring Boot 自动装配原理》](https://www.cnblogs.com/javaguide/p/springboot-auto-config.html) -- spring cloud，先学会使用再研究源码，切勿本末倒置。推荐[《精尽Spring Cloud学习指南》](http://svip.iocoder.cn/Spring-Cloud/tutorials/) + - [《SpringBoot自动装配原理，这一篇就够了!》](https://mp.weixin.qq.com/s/f6oED1hbiWat_0HOwxgfnA) +- spring cloud，先学会使用再研究源码，切勿本末倒置。推荐[《精尽Spring Cloud学习指南》](http://svip.iocoder.cn/Spring-Cloud/tutorials/) 。 关于spring cloud。spring cloud是构建通用模式的分布式系统的工具集，通过[**spring-cloud-commons**](https://github.com/spring-cloud/spring-cloud-commons) 定义了统一的抽象API，相当于定义了一套协议标准，具体的实现需要符合这套协议标准。spring cloud官方整合第三方组件Eureka、Ribbon、Hystrix等实现了spring-cloud-netflix，阿里巴巴结合自身的Nacos、Sentinel等实现了spring-cloud-alibaba。本项目基于spring-cloud-commons的协议标准自主开发或整合第三方组件提供具体的实现。 -写作本项目的目的之一是降低阅读原始spring cloud源码的难度。希望掌握本项目讲解的内容之后再阅读原始spring-cloud的源码能起到事半功倍的效果，所以本项目的功能实现逻辑及原理和官方保持一致但追求代码最大精简化，可以理解为一个源码导读的项目。 +写作本项目的目的之一是降低阅读原始spring cloud源码的难度。希望掌握本项目讲解的内容之后再阅读原始spring-cloud的源码能起到事半功倍的效果，所以本项目的功能实现逻辑及原理和官方保持一致但追求代码最大精简化，**本项目可以理解为一个源码导读的项目**。 技术能力有限且文采欠佳，大家可以在此[**issue**](https://github.com/DerekYRC/mini-spring-cloud/issues/1) 留言提问题和发表建议，也欢迎Pull Request完善此项目。 # [服务注册](#服务注册) -> 分支: service-registry +> 代码分支: service-registry 为了演示，写一个非常简单的单机版的服务注册和发现中心，命名图图 ```java @@ -338,7 +337,7 @@ server: ``` # [服务发现](#服务发现) -> 分支: service-discovery +> 代码分支: service-discovery spring-cloud-commons定义的服务发现接口```org.springframework.cloud.client.discovery.DiscoveryClient```: ```java @@ -478,7 +477,7 @@ Port of the service provider: 19922 # [集成ribbon实现客户端负载均衡](#集成ribbon实现客户端负载均衡) -> 分支: load-balancer +> 代码分支: load-balancer ## 关于ribbon > (翻译自官方文档)ribbon是一个提供如下功能的依赖包: @@ -915,11 +914,11 @@ public class RibbonLoadBalancerClient implements LoadBalancerClient { - reconstructURI方法，重建请求URI，将服务名称替换为服务实例的IP:端口，例如```http://provider-application/echo``` 被重建为```http://192.168.100.1:8888/echo``` - execute方法，处理http请求 -有了RibbonLoadBalancerClient的reconstructURI和execute方法，将所有http请求委托给RibbonLoadBalancerClient即可。其实spring-cloud-commons已经帮我们配置好拦截RestTemplate的http请求委托给RibbonLoadBalancerClient的拦截器LoadBalancerInterceptor，配置类如下: +有了RibbonLoadBalancerClient的reconstructURI和execute方法，将所有http请求委托给RibbonLoadBalancerClient即可。其实spring-cloud-commons已经帮我们配置好拦截RestTemplate的http请求委托给RibbonLoadBalancerClient的拦截器LoadBalancerInterceptor，配置类（有删减）如下: ![](./assets/load-balancer-LoadBalancerAutoConfiguration.png) -LoadBalancerAutoConfiguration配置类为每一个被LoadBalanced注解修饰的RestTemplate增加LoadBalancerInterceptor拦截器。 +LoadBalancerAutoConfiguration配置类**为每一个被LoadBalanced注解修饰的RestTemplate增加LoadBalancerInterceptor拦截器。** ![](./assets/load-balancer-LoadBalancerInterceptor.png) From 41b51974dbbea6041163726f8ae24610e8b49af4 Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Thu, 7 Apr 2022 23:03:36 +0800 Subject: [PATCH 04/11] =?UTF-8?q?=E9=9B=86=E6=88=90Feign=E7=AE=80=E5=8C=96?= =?UTF-8?q?=E8=B0=83=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../pom.xml | 6 -- mini-spring-cloud-load-balancer/pom.xml | 1 - mini-spring-cloud-openfeign/pom.xml | 65 +++++++++++++++++++ .../cloud/openfeign/EnableFeignClients.java | 18 +++++ .../github/cloud/openfeign/FeignClient.java | 17 +++++ .../openfeign/FeignClientFactoryBean.java | 52 +++++++++++++++ .../openfeign/FeignClientsRegistrar.java | 45 +++++++++++++ pom.xml | 8 +++ 8 files changed, 205 insertions(+), 7 deletions(-) create mode 100644 mini-spring-cloud-openfeign/pom.xml create mode 100644 mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/EnableFeignClients.java create mode 100644 mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClient.java create mode 100644 mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java create mode 100644 mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientsRegistrar.java diff --git a/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml index a9c5f04..a545464 100644 --- a/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml +++ b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml @@ -34,12 +34,6 @@ mini-spring-cloud-load-balancer - - io.github.openfeign - feign-core - test - - org.springframework.cloud spring-cloud-starter-feign diff --git a/mini-spring-cloud-load-balancer/pom.xml b/mini-spring-cloud-load-balancer/pom.xml index 9a963e0..82a27f2 100644 --- a/mini-spring-cloud-load-balancer/pom.xml +++ b/mini-spring-cloud-load-balancer/pom.xml @@ -54,7 +54,6 @@ org.springframework.boot spring-boot-starter-web - test diff --git a/mini-spring-cloud-openfeign/pom.xml b/mini-spring-cloud-openfeign/pom.xml new file mode 100644 index 0000000..99a980a --- /dev/null +++ b/mini-spring-cloud-openfeign/pom.xml @@ -0,0 +1,65 @@ + + + + mini-spring-cloud + com.github + 1.0.0-SNAPSHOT + + 4.0.0 + + mini-spring-cloud-openfeign + + + + com.github + mini-spring-cloud-load-balancer + + + + io.github.openfeign + feign-core + + + + org.springframework.boot + spring-boot-configuration-processor + true + + + + org.springframework.boot + spring-boot + true + + + + org.springframework.boot + spring-boot-autoconfigure + true + + + + org.springframework.boot + spring-boot-starter + true + + + + org.springframework.cloud + spring-cloud-commons + + + + org.springframework.cloud + spring-cloud-context + + + + org.springframework.boot + spring-boot-starter-web + + + + \ No newline at end of file diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/EnableFeignClients.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/EnableFeignClients.java new file mode 100644 index 0000000..3c51eb7 --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/EnableFeignClients.java @@ -0,0 +1,18 @@ +package com.github.cloud.openfeign; + +import org.springframework.context.annotation.Import; + +import java.lang.annotation.*; + +/** + * 启用Feign + * + * @author derek(易仁川) + * @date 2022/4/7 + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.TYPE) +@Documented +@Import(FeignClientsRegistrar.class) +public @interface EnableFeignClients { +} diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClient.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClient.java new file mode 100644 index 0000000..ffdaa7b --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClient.java @@ -0,0 +1,17 @@ +package com.github.cloud.openfeign; + +/** + * Feign客户端注解 + * + * @author derek(易仁川) + * @date 2022/4/7 + */ +public @interface FeignClient { + + /** + * 服务提供者应用名称 + * + * @return + */ + String value(); +} diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java new file mode 100644 index 0000000..2141931 --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java @@ -0,0 +1,52 @@ +package com.github.cloud.openfeign; + +import org.springframework.beans.BeansException; +import org.springframework.beans.factory.FactoryBean; +import org.springframework.context.ApplicationContext; +import org.springframework.context.ApplicationContextAware; + +/** + * 生成Feign客户端的FactoryBean + * + * @author derek(易仁川) + * @date 2022/4/7 + */ +public class FeignClientFactoryBean implements FactoryBean, ApplicationContextAware { + + private String contextId; + + private Class type; + + private ApplicationContext applicationContext; + + @Override + public Object getObject() throws Exception { + return null; + } + + @Override + public Class getObjectType() { + return this.type; + } + + @Override + public void setApplicationContext(ApplicationContext applicationContext) throws BeansException { + this.applicationContext = applicationContext; + } + + public String getContextId() { + return contextId; + } + + public void setContextId(String contextId) { + this.contextId = contextId; + } + + public Class getType() { + return type; + } + + public void setType(Class type) { + this.type = type; + } +} diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientsRegistrar.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientsRegistrar.java new file mode 100644 index 0000000..082b777 --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientsRegistrar.java @@ -0,0 +1,45 @@ +package com.github.cloud.openfeign; + +import cn.hutool.core.util.ClassUtil; +import org.springframework.beans.factory.support.BeanDefinitionRegistry; +import org.springframework.beans.factory.support.GenericBeanDefinition; +import org.springframework.context.annotation.ImportBeanDefinitionRegistrar; +import org.springframework.core.type.AnnotationMetadata; +import org.springframework.util.ClassUtils; + +import java.util.Set; + +/** + * 往bean容器中注册Feign客户端 + * + * @author derek(易仁川) + * @date 2022/4/7 + */ +public class FeignClientsRegistrar implements ImportBeanDefinitionRegistrar { + + /** + * 往bean容器中注册Feign客户端 + * + * @param importingClassMetadata + * @param registry + */ + @Override + public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata, BeanDefinitionRegistry registry) { + //为FeignClient注解修饰的接口生成代理bean即Feign客户端，并注册到bean容器 + String packageName = ClassUtils.getPackageName(importingClassMetadata.getClassName()); + //扫描所有被FeignClient注解修饰的接口 + Set> classes = ClassUtil.scanPackageByAnnotation(packageName, FeignClient.class); + for (Class clazz : classes) { + GenericBeanDefinition beanDefinition = new GenericBeanDefinition(); + //使用FeignClientFactoryBean生成Feign客户端 + beanDefinition.setBeanClass(FeignClientFactoryBean.class); + String clientName = clazz.getAnnotation(FeignClient.class).value(); + beanDefinition.getPropertyValues().addPropertyValue("contextId", clientName); + beanDefinition.getPropertyValues().addPropertyValue("type", clazz); + + //将Feign客户端注册进bean容器 + String beanName = clazz.getName(); + registry.registerBeanDefinition(beanName, beanDefinition); + } + } +} diff --git a/pom.xml b/pom.xml index fb339f5..eb28a04 100644 --- a/pom.xml +++ b/pom.xml @@ -22,6 +22,7 @@ mini-spring-cloud-examples/mini-spring-cloud-provider-example mini-spring-cloud-examples/mini-spring-cloud-consumer-examples mini-spring-cloud-load-balancer + mini-spring-cloud-openfeign @@ -29,6 +30,7 @@ 1.2.79 5.7.21 2.3.0 + 11.8 @@ -90,6 +92,12 @@ ribbon-core ${ribbon.version} + + + io.github.openfeign + feign-core + ${feign.version} + From 2dd322f07fe462d965cefa47808fa811cef2ce14 Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Sat, 9 Apr 2022 10:06:19 +0800 Subject: [PATCH 05/11] =?UTF-8?q?=E9=9B=86=E6=88=90Feign=E7=AE=80=E5=8C=96?= =?UTF-8?q?=E8=B0=83=E7=94=A8=E6=96=B9=E5=BC=8F(=E4=B8=80)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- .../pom.xml | 5 ++ .../cloud/examples/ConsumerApplication.java | 10 ++++ .../github/cloud/examples/EchoService.java | 15 ++++++ .../github/cloud/openfeign/FeignClient.java | 5 ++ .../openfeign/FeignClientFactoryBean.java | 6 ++- .../openfeign/support/SpringMvcContract.java | 46 +++++++++++++++++++ pom.xml | 6 +++ 8 files changed, 93 insertions(+), 2 deletions(-) create mode 100644 mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/main/java/com/github/cloud/examples/EchoService.java create mode 100644 mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/support/SpringMvcContract.java diff --git a/README.md b/README.md index 871af07..81e6af0 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ * [服务注册](https://github.com/DerekYRC/mini-spring-cloud/blob/main/changelog.md#服务注册) * [服务发现](https://github.com/DerekYRC/mini-spring-cloud/blob/main/changelog.md#服务发现) * [负载均衡](https://github.com/DerekYRC/mini-spring-cloud/blob/main/changelog.md#集成ribbon实现客户端负载均衡) -* [集成Feign简化调用]() +* [集成Feign简化调用方式]() * [流量控制]() * [熔断降级]() * [API 网关]() diff --git a/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml index a545464..265f3ff 100644 --- a/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml +++ b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/pom.xml @@ -34,6 +34,11 @@ mini-spring-cloud-load-balancer + + com.github + mini-spring-cloud-openfeign + + org.springframework.cloud spring-cloud-starter-feign diff --git a/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/main/java/com/github/cloud/examples/ConsumerApplication.java b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/main/java/com/github/cloud/examples/ConsumerApplication.java index cb07b8f..276cd77 100644 --- a/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/main/java/com/github/cloud/examples/ConsumerApplication.java +++ b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/main/java/com/github/cloud/examples/ConsumerApplication.java @@ -1,5 +1,6 @@ package com.github.cloud.examples; +import com.github.cloud.openfeign.EnableFeignClients; import com.github.cloud.tutu.discovery.TutuDiscoveryClient; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.SpringApplication; @@ -20,6 +21,7 @@ import java.util.List; * @author derek(易仁川) * @date 2022/3/20 */ +@EnableFeignClients @SpringBootApplication public class ConsumerApplication { @@ -54,6 +56,9 @@ public class ConsumerApplication { @Autowired private RestTemplate loadBalancedRestTemplate; + @Autowired + private EchoService echoService; + private RestTemplate restTemplate = new RestTemplate(); @GetMapping("/hello") @@ -85,6 +90,11 @@ public class ConsumerApplication { public String foo() { return loadBalancedRestTemplate.postForObject("http://provider-application/echo", null, String.class); } + + @GetMapping("/bar") + public String bar() { + return echoService.echo(); + } } } diff --git a/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/main/java/com/github/cloud/examples/EchoService.java b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/main/java/com/github/cloud/examples/EchoService.java new file mode 100644 index 0000000..02c8cb0 --- /dev/null +++ b/mini-spring-cloud-examples/mini-spring-cloud-consumer-examples/src/main/java/com/github/cloud/examples/EchoService.java @@ -0,0 +1,15 @@ +package com.github.cloud.examples; + +import com.github.cloud.openfeign.FeignClient; +import org.springframework.web.bind.annotation.PostMapping; + +/** + * @author derek(易仁川) + * @date 2022/4/9 + */ +@FeignClient("provider-application") +public interface EchoService { + + @PostMapping("echo") + String echo(); +} diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClient.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClient.java index ffdaa7b..c4e8278 100644 --- a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClient.java +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClient.java @@ -1,11 +1,16 @@ package com.github.cloud.openfeign; +import java.lang.annotation.*; + /** * Feign客户端注解 * * @author derek(易仁川) * @date 2022/4/7 */ +@Target(ElementType.TYPE) +@Retention(RetentionPolicy.RUNTIME) +@Documented public @interface FeignClient { /** diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java index 2141931..dd9a0a5 100644 --- a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java @@ -1,5 +1,7 @@ package com.github.cloud.openfeign; +import com.github.cloud.openfeign.support.SpringMvcContract; +import feign.Feign; import org.springframework.beans.BeansException; import org.springframework.beans.factory.FactoryBean; import org.springframework.context.ApplicationContext; @@ -21,7 +23,9 @@ public class FeignClientFactoryBean implements FactoryBean, ApplicationC @Override public Object getObject() throws Exception { - return null; + return Feign.builder() + .contract(new SpringMvcContract()) + .target(type, "http://localhost:1234"); } @Override diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/support/SpringMvcContract.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/support/SpringMvcContract.java new file mode 100644 index 0000000..fa570f6 --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/support/SpringMvcContract.java @@ -0,0 +1,46 @@ +package com.github.cloud.openfeign.support; + +import feign.Contract; +import feign.MethodMetadata; +import feign.Request; +import org.springframework.web.bind.annotation.PostMapping; + +import java.lang.annotation.Annotation; +import java.lang.reflect.Method; + +/** + * feign支持Spring MVC的注解 + * + * @author derek(易仁川) + * @date 2022/4/9 + */ +public class SpringMvcContract extends Contract.BaseContract { + + @Override + protected void processAnnotationOnClass(MethodMetadata data, Class clz) { + //TODO 解析接口注解 + } + + @Override + protected void processAnnotationOnMethod(MethodMetadata data, Annotation annotation, Method method) { + //解析方法注解 + //解析PostMapping注解 + if (annotation instanceof PostMapping) { + PostMapping postMapping = (PostMapping) annotation; + data.template().method(Request.HttpMethod.POST); + String path = postMapping.value()[0]; + if (!path.startsWith("/") && !data.template().path().endsWith("/")) { + path = "/" + path; + } + data.template().uri(path, true); + } + + //TODO 解析其他注解 + } + + @Override + protected boolean processAnnotationsOnParameter(MethodMetadata data, Annotation[] annotations, int paramIndex) { + //TODO 解析参数 + return true; + } +} diff --git a/pom.xml b/pom.xml index eb28a04..3495d09 100644 --- a/pom.xml +++ b/pom.xml @@ -63,6 +63,12 @@ 1.0.0-SNAPSHOT + + com.github + mini-spring-cloud-openfeign + 1.0.0-SNAPSHOT + + com.alibaba fastjson From c4cf557e30b6f82917aeb53fa634db0267cfc8d3 Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Sun, 10 Apr 2022 20:35:26 +0800 Subject: [PATCH 06/11] =?UTF-8?q?=E9=9B=86=E6=88=90Feign=E7=AE=80=E5=8C=96?= =?UTF-8?q?=E8=B0=83=E7=94=A8=E6=96=B9=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mini-spring-cloud-openfeign/pom.xml | 5 + .../openfeign/FeignAutoConfiguration.java | 17 +++ .../openfeign/FeignClientFactoryBean.java | 19 ++- .../openfeign/FeignClientSpecification.java | 55 +++++++++ .../openfeign/FeignClientsConfiguration.java | 46 +++++++ .../github/cloud/openfeign/FeignContext.java | 16 +++ .../ribbon/LoadBalancerFeignClient.java | 112 ++++++++++++++++++ .../main/resources/META-INF/spring.factories | 2 + 8 files changed, 269 insertions(+), 3 deletions(-) create mode 100644 mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignAutoConfiguration.java create mode 100644 mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientSpecification.java create mode 100644 mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientsConfiguration.java create mode 100644 mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignContext.java create mode 100644 mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/ribbon/LoadBalancerFeignClient.java create mode 100644 mini-spring-cloud-openfeign/src/main/resources/META-INF/spring.factories diff --git a/mini-spring-cloud-openfeign/pom.xml b/mini-spring-cloud-openfeign/pom.xml index 99a980a..c2146ea 100644 --- a/mini-spring-cloud-openfeign/pom.xml +++ b/mini-spring-cloud-openfeign/pom.xml @@ -60,6 +60,11 @@ org.springframework.boot spring-boot-starter-web + + + cn.hutool + hutool-all + \ No newline at end of file diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignAutoConfiguration.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignAutoConfiguration.java new file mode 100644 index 0000000..64b88b8 --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignAutoConfiguration.java @@ -0,0 +1,17 @@ +package com.github.cloud.openfeign; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +/** + * @author derek(易仁川) + * @date 2022/4/9 + */ +@Configuration +public class FeignAutoConfiguration { + + @Bean + public FeignContext feignContext() { + return new FeignContext(); + } +} diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java index dd9a0a5..5aa76cc 100644 --- a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientFactoryBean.java @@ -1,7 +1,11 @@ package com.github.cloud.openfeign; -import com.github.cloud.openfeign.support.SpringMvcContract; +import feign.Client; +import feign.Contract; import feign.Feign; +import feign.Target.HardCodedTarget; +import feign.codec.Decoder; +import feign.codec.Encoder; import org.springframework.beans.BeansException; import org.springframework.beans.factory.FactoryBean; import org.springframework.context.ApplicationContext; @@ -23,9 +27,18 @@ public class FeignClientFactoryBean implements FactoryBean, ApplicationC @Override public Object getObject() throws Exception { + FeignContext feignContext = applicationContext.getBean(FeignContext.class); + Encoder encoder = feignContext.getInstance(contextId, Encoder.class); + Decoder decoder = feignContext.getInstance(contextId, Decoder.class); + Contract contract = feignContext.getInstance(contextId, Contract.class); + Client client = feignContext.getInstance(contextId, Client.class); + return Feign.builder() - .contract(new SpringMvcContract()) - .target(type, "http://localhost:1234"); + .encoder(encoder) + .decoder(decoder) + .contract(contract) + .client(client) + .target(new HardCodedTarget<>(type, contextId, "http://" + contextId)); } @Override diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientSpecification.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientSpecification.java new file mode 100644 index 0000000..93427ff --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientSpecification.java @@ -0,0 +1,55 @@ +package com.github.cloud.openfeign; + +import org.springframework.cloud.context.named.NamedContextFactory; + +import java.util.Arrays; +import java.util.Objects; + +/** + * @author derek(易仁川) + * @date 2022/4/9 + */ +public class FeignClientSpecification implements NamedContextFactory.Specification { + + private String name; + + private Class[] configuration; + + public FeignClientSpecification(String name, Class[] configuration) { + this.name = name; + this.configuration = configuration; + } + + @Override + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + @Override + public Class[] getConfiguration() { + return configuration; + } + + public void setConfiguration(Class[] configuration) { + this.configuration = configuration; + } + + @Override + public boolean equals(Object o) { + if (this == o) return true; + if (o == null || getClass() != o.getClass()) return false; + FeignClientSpecification that = (FeignClientSpecification) o; + return name.equals(that.name) && Arrays.equals(configuration, that.configuration); + } + + @Override + public int hashCode() { + int result = Objects.hash(name); + result = 31 * result + Arrays.hashCode(configuration); + return result; + } +} diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientsConfiguration.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientsConfiguration.java new file mode 100644 index 0000000..f85e312 --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignClientsConfiguration.java @@ -0,0 +1,46 @@ +package com.github.cloud.openfeign; + +import com.github.cloud.openfeign.ribbon.LoadBalancerFeignClient; +import com.github.cloud.openfeign.support.SpringMvcContract; +import feign.Client; +import feign.Contract; +import feign.codec.Decoder; +import feign.codec.Encoder; +import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; +import org.springframework.cloud.client.loadbalancer.LoadBalancerClient; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +/** + * 配置feign的核心API + * + * @author derek(易仁川) + * @date 2022/4/9 + */ +@Configuration +public class FeignClientsConfiguration { + + @Bean + @ConditionalOnMissingBean + public Encoder encoder() { + return new Encoder.Default(); + } + + @Bean + @ConditionalOnMissingBean + public Decoder decoder() { + return new Decoder.Default(); + } + + @Bean + @ConditionalOnMissingBean + public Contract contract() { + return new SpringMvcContract(); + } + + @Bean + @ConditionalOnMissingBean + public Client client(LoadBalancerClient loadBalancerClient) { + return new LoadBalancerFeignClient(loadBalancerClient, new Client.Default(null, null)); + } +} diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignContext.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignContext.java new file mode 100644 index 0000000..8b2b8f8 --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/FeignContext.java @@ -0,0 +1,16 @@ +package com.github.cloud.openfeign; + +import org.springframework.cloud.context.named.NamedContextFactory; + +/** + * 为每个feign客户端创建一个应用上下文(ApplicationContext)，隔离每个feign客户端的配置 + * + * @author derek(易仁川) + * @date 2022/4/9 + */ +public class FeignContext extends NamedContextFactory { + + public FeignContext() { + super(FeignClientsConfiguration.class, "feign", "feign.client.name"); + } +} diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/ribbon/LoadBalancerFeignClient.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/ribbon/LoadBalancerFeignClient.java new file mode 100644 index 0000000..c347068 --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/ribbon/LoadBalancerFeignClient.java @@ -0,0 +1,112 @@ +package com.github.cloud.openfeign.ribbon; + +import com.netflix.client.ClientException; +import com.netflix.client.ClientRequest; +import com.netflix.client.IResponse; +import feign.Client; +import feign.Request; +import feign.Response; +import org.springframework.cloud.client.ServiceInstance; +import org.springframework.cloud.client.loadbalancer.LoadBalancerClient; + +import java.io.IOException; +import java.net.URI; +import java.nio.charset.StandardCharsets; +import java.util.HashMap; +import java.util.Map; + +/** + * 具备负载均衡能力的feign client + * + * @author derek(易仁川) + * @date 2022/4/9 + */ +public class LoadBalancerFeignClient implements Client { + + private LoadBalancerClient loadBalancerClient; + + private Client delegate; + + public LoadBalancerFeignClient(LoadBalancerClient loadBalancerClient, Client delegate) { + this.loadBalancerClient = loadBalancerClient; + this.delegate = delegate; + } + + @Override + public Response execute(Request request, Request.Options options) throws IOException { + //客户端负载均衡 + URI original = URI.create(request.url()); + String serviceId = original.getHost(); + //选择服务实例 + ServiceInstance serviceInstance = loadBalancerClient.choose(serviceId); + //重建请求URI + URI uri = loadBalancerClient.reconstructURI(serviceInstance, original); + + Response response = delegate.execute(new RibbonRequest(request, uri).toRequest(), options); + return new RibbonResponse(uri, response).getResponse(); + } + + private static class RibbonRequest extends ClientRequest { + + private Request request; + + public RibbonRequest(Request request, URI uri) { + this.request = request; + setUri(uri); + } + + @SuppressWarnings("deprecation") + private Request toRequest() { + return Request.create(request.httpMethod(), getUri().toASCIIString(), new HashMap<>(), + request.body(), StandardCharsets.UTF_8); + } + } + + private static class RibbonResponse implements IResponse { + + private final URI uri; + + private final Response response; + + protected RibbonResponse(URI uri, Response response) { + this.uri = uri; + this.response = response; + } + + @Override + public Object getPayload() throws ClientException { + return response.body(); + } + + @Override + public boolean hasPayload() { + return response.body() != null; + } + + @Override + public boolean isSuccess() { + return response.status() == 200; + } + + @Override + public URI getRequestedURI() { + return uri; + } + + @Override + public Map getHeaders() { + return new HashMap<>(); + } + + @Override + public void close() throws IOException { + if (response != null && response.body() != null) { + response.body().close(); + } + } + + public Response getResponse() { + return response; + } + } +} diff --git a/mini-spring-cloud-openfeign/src/main/resources/META-INF/spring.factories b/mini-spring-cloud-openfeign/src/main/resources/META-INF/spring.factories new file mode 100644 index 0000000..cc5e1f6 --- /dev/null +++ b/mini-spring-cloud-openfeign/src/main/resources/META-INF/spring.factories @@ -0,0 +1,2 @@ +org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ + com.github.cloud.openfeign.FeignAutoConfiguration \ No newline at end of file From d769f6d459f75c22fac8846280b2cf2ecc9baeed Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Mon, 11 Apr 2022 22:31:32 +0800 Subject: [PATCH 07/11] =?UTF-8?q?=E9=9B=86=E6=88=90Feign=E7=AE=80=E5=8C=96?= =?UTF-8?q?=E8=B0=83=E7=94=A8=E6=96=B9=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- assets/feign工作流程.png | Bin 0 -> 82672 bytes changelog.md | 80 ++++++++++++++-- .../ribbon/LoadBalancerFeignClient.java | 90 +++--------------- 3 files changed, 88 insertions(+), 82 deletions(-) create mode 100644 assets/feign工作流程.png diff --git a/assets/feign工作流程.png b/assets/feign工作流程.png new file mode 100644 index 0000000000000000000000000000000000000000..6fe26a2477d663db430064d2ebeb841d90eab049 GIT binary patch literal 82672 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 x2XGQPm*E|!WM^ literal 0 HcmV?d00001 diff --git a/changelog.md b/changelog.md index d5939f8..2e3e6e3 100644 --- a/changelog.md +++ b/changelog.md @@ -475,16 +475,16 @@ spring: Port of the service provider: 19922 ``` - # [集成ribbon实现客户端负载均衡](#集成ribbon实现客户端负载均衡) > 代码分支: load-balancer ## 关于ribbon -> (翻译自官方文档)ribbon是一个提供如下功能的依赖包: -> - 负载均衡 -> - 容错机制 -> - 支持多种协议(HTTP, TCP, UDP)，支持异步和响应式的调用方式 -> - 缓存和批处理 + +(翻译自官方文档)ribbon是一个提供如下功能的依赖包: +- 负载均衡 +- 容错机制 +- 支持多种协议(HTTP, TCP, UDP)，支持异步和响应式的调用方式 +- 缓存和批处理 #### ribbon核心API @@ -971,6 +971,74 @@ public class ConsumerApplication { 访问```http://localhost:8080/foo``` +# [集成Feign简化调用方式](#集成Feign简化调用方式) +> 代码分支: open-feign + +## 关于feign +[Open Feign](https://github.com/OpenFeign/feign) 是一个简化http调用方式的Java客户端，通过处理接口的注解生成响应报文。使用示例: + +```java +interface HelloService { + + @RequestLine("GET /hello") + String hello(); +} + +@Test +public void testOpenFeign() { + HelloService helloService = Feign.builder() + .target(HelloService.class, "http://localhost:8080"); + String response = helloService.hello(); +} +``` + +Spring Cloud基于Open Feign开发了[Spring Cloud OpenFeign](https://github.com/spring-cloud/spring-cloud-openfeign) ，得以支持Spring Mvc的注解（通过实现feign的Contract接口，实现类为SpringMvcContract），使用示例: + +```java +interface WorldService { + + @GetMapping("/world") + String world(); +} + +@Test +public void testSpringCloudOpenFeign() { + WorldService worldService = Feign.builder() + .contract(new SpringMvcContract()) + .target(WorldService.class, "http://localhost:8080"); + String response = worldService.world(); +} +``` + +可以dubug上面两个示例，代码放在测试类FeignTest中，重点关注Contract接口对注解的解析 + + +#### Open Feign核心API + +Open Feign工作流程: + +![](./assets/feign工作流程.png) + +一、Contract接口 + +负责解析Feign客户端接口的类注解、方法注解和参数。实现类```feign.Contract.Default```支持Open Feign的注解，比如上面第一个示例中的RequestLine注解；Spring Cloud OpenFeign开发的实现类```SpringMvcContract```支持Spring MVC的注解，如GetMapping、PostMapping、RequestMapping。 + +二、Encoder接口 + +编码器，将请求对象编码为请求体 + +三、Decoder接口 + +解码器，将响应体解码为对象 + +四、RequestInterceptor拦截器接口 + +对请求进行拦截处理 + +五、Client接口 + +提交http请求的接口 + diff --git a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/ribbon/LoadBalancerFeignClient.java b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/ribbon/LoadBalancerFeignClient.java index c347068..d172492 100644 --- a/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/ribbon/LoadBalancerFeignClient.java +++ b/mini-spring-cloud-openfeign/src/main/java/com/github/cloud/openfeign/ribbon/LoadBalancerFeignClient.java @@ -1,8 +1,5 @@ package com.github.cloud.openfeign.ribbon; -import com.netflix.client.ClientException; -import com.netflix.client.ClientRequest; -import com.netflix.client.IResponse; import feign.Client; import feign.Request; import feign.Response; @@ -13,7 +10,6 @@ import java.io.IOException; import java.net.URI; import java.nio.charset.StandardCharsets; import java.util.HashMap; -import java.util.Map; /** * 具备负载均衡能力的feign client @@ -32,81 +28,23 @@ public class LoadBalancerFeignClient implements Client { this.delegate = delegate; } + @SuppressWarnings("deprecation") @Override public Response execute(Request request, Request.Options options) throws IOException { - //客户端负载均衡 - URI original = URI.create(request.url()); - String serviceId = original.getHost(); - //选择服务实例 - ServiceInstance serviceInstance = loadBalancerClient.choose(serviceId); - //重建请求URI - URI uri = loadBalancerClient.reconstructURI(serviceInstance, original); - - Response response = delegate.execute(new RibbonRequest(request, uri).toRequest(), options); - return new RibbonResponse(uri, response).getResponse(); - } - - private static class RibbonRequest extends ClientRequest { - - private Request request; - - public RibbonRequest(Request request, URI uri) { - this.request = request; - setUri(uri); - } - - @SuppressWarnings("deprecation") - private Request toRequest() { - return Request.create(request.httpMethod(), getUri().toASCIIString(), new HashMap<>(), + try { + //客户端负载均衡 + URI original = URI.create(request.url()); + String serviceId = original.getHost(); + //选择服务实例 + ServiceInstance serviceInstance = loadBalancerClient.choose(serviceId); + //重建请求URI + URI uri = loadBalancerClient.reconstructURI(serviceInstance, original); + + Request newRequest = Request.create(request.httpMethod(), uri.toASCIIString(), new HashMap<>(), request.body(), StandardCharsets.UTF_8); - } - } - - private static class RibbonResponse implements IResponse { - - private final URI uri; - - private final Response response; - - protected RibbonResponse(URI uri, Response response) { - this.uri = uri; - this.response = response; - } - - @Override - public Object getPayload() throws ClientException { - return response.body(); - } - - @Override - public boolean hasPayload() { - return response.body() != null; - } - - @Override - public boolean isSuccess() { - return response.status() == 200; - } - - @Override - public URI getRequestedURI() { - return uri; - } - - @Override - public Map getHeaders() { - return new HashMap<>(); - } - - @Override - public void close() throws IOException { - if (response != null && response.body() != null) { - response.body().close(); - } - } - - public Response getResponse() { - return response; + return delegate.execute(newRequest, options); + } catch (IOException e) { + throw new RuntimeException(e); } } } From 4a0459865d67ff0397e3d63b0608233b325f2459 Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Mon, 11 Apr 2022 22:37:22 +0800 Subject: [PATCH 08/11] update changelog --- changelog.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/changelog.md b/changelog.md index 2e3e6e3..f5b1e3f 100644 --- a/changelog.md +++ b/changelog.md @@ -975,7 +975,7 @@ public class ConsumerApplication { > 代码分支: open-feign ## 关于feign -[Open Feign](https://github.com/OpenFeign/feign) 是一个简化http调用方式的Java客户端，通过处理接口的注解生成响应报文。使用示例: +[Open Feign](https://github.com/OpenFeign/feign) 是一个简化http调用方式的Java客户端。使用示例: ```java interface HelloService { @@ -992,7 +992,7 @@ public void testOpenFeign() { } ``` -Spring Cloud基于Open Feign开发了[Spring Cloud OpenFeign](https://github.com/spring-cloud/spring-cloud-openfeign) ，得以支持Spring Mvc的注解（通过实现feign的Contract接口，实现类为SpringMvcContract），使用示例: +Spring Cloud基于Open Feign开发了[Spring Cloud OpenFeign](https://github.com/spring-cloud/spring-cloud-openfeign) ，得以支持Spring Mvc的注解（通过实现了feign的Contract接口的实现类SpringMvcContract），使用示例: ```java interface WorldService { From e67f700f828e4cf897ef18f91e4aa55b088012be Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Mon, 11 Apr 2022 22:39:52 +0800 Subject: [PATCH 09/11] update changelog --- changelog.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/changelog.md b/changelog.md index f5b1e3f..21f1dbd 100644 --- a/changelog.md +++ b/changelog.md @@ -1012,13 +1012,12 @@ public void testSpringCloudOpenFeign() { 可以dubug上面两个示例，代码放在测试类FeignTest中，重点关注Contract接口对注解的解析 - -#### Open Feign核心API - -Open Feign工作流程: +#### Open Feign工作流程: ![](./assets/feign工作流程.png) +#### Open Feign核心API + 一、Contract接口 负责解析Feign客户端接口的类注解、方法注解和参数。实现类```feign.Contract.Default```支持Open Feign的注解，比如上面第一个示例中的RequestLine注解；Spring Cloud OpenFeign开发的实现类```SpringMvcContract```支持Spring MVC的注解，如GetMapping、PostMapping、RequestMapping。 From 5c09633b7c3c38ebfd18a698d5591695f574294c Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Mon, 11 Apr 2022 22:41:56 +0800 Subject: [PATCH 10/11] update changelog --- changelog.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/changelog.md b/changelog.md index 21f1dbd..c01639c 100644 --- a/changelog.md +++ b/changelog.md @@ -1016,11 +1016,15 @@ public void testSpringCloudOpenFeign() { ![](./assets/feign工作流程.png) -#### Open Feign核心API +#### Open Feign核心API: 一、Contract接口 -负责解析Feign客户端接口的类注解、方法注解和参数。实现类```feign.Contract.Default```支持Open Feign的注解，比如上面第一个示例中的RequestLine注解；Spring Cloud OpenFeign开发的实现类```SpringMvcContract```支持Spring MVC的注解，如GetMapping、PostMapping、RequestMapping。 +负责解析Feign客户端接口的类注解、方法注解和参数。 + +实现类```feign.Contract.Default```支持Open Feign的注解，比如上面第一个示例中的RequestLine注解。 + +Spring Cloud OpenFeign开发的实现类```SpringMvcContract```支持Spring MVC的注解，如GetMapping、PostMapping、RequestMapping。 二、Encoder接口 From cc6bcb5896b99e106a1b79fc99e8c36a09e61f81 Mon Sep 17 00:00:00 2001 From: DerekYRC <15521077528@163.com> Date: Wed, 13 Apr 2022 00:18:01 +0800 Subject: [PATCH 11/11] update changelog --- README.md | 2 +- changelog.md | 225 +++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 221 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 81e6af0..d7ee3d9 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ * [服务注册](https://github.com/DerekYRC/mini-spring-cloud/blob/main/changelog.md#服务注册) * [服务发现](https://github.com/DerekYRC/mini-spring-cloud/blob/main/changelog.md#服务发现) * [负载均衡](https://github.com/DerekYRC/mini-spring-cloud/blob/main/changelog.md#集成ribbon实现客户端负载均衡) -* [集成Feign简化调用方式]() +* [集成Feign简化调用方式](https://github.com/DerekYRC/mini-spring-cloud/blob/main/changelog.md#集成Feign简化调用方式) * [流量控制]() * [熔断降级]() * [API 网关]() diff --git a/changelog.md b/changelog.md index c01639c..3b9c1f2 100644 --- a/changelog.md +++ b/changelog.md @@ -1042,59 +1042,274 @@ Spring Cloud OpenFeign开发的实现类```SpringMvcContract```支持Spring MVC 提交http请求的接口 +## 功能实现 +**@EnableFeignClients注解**开启集成Feign客户端，该注解Import配置类FeignClientsRegistrar: +```java +/** + * 启用Feign + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.TYPE) +@Documented +@Import(FeignClientsRegistrar.class) +public @interface EnableFeignClients { +} +``` +配置类FeignClientsRegistrar扫描每个被FeignClient注解修饰的接口，基于JDK动态代理生成对象，注册到bean容器: +```java +/** + * 往bean容器中注册Feign客户端 + */ +public class FeignClientsRegistrar implements ImportBeanDefinitionRegistrar { + /** + * 往bean容器中注册Feign客户端 + */ + @Override + public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata, BeanDefinitionRegistry registry) { + //为FeignClient注解修饰的接口生成代理bean即Feign客户端，并注册到bean容器 + String packageName = ClassUtils.getPackageName(importingClassMetadata.getClassName()); + //扫描所有被FeignClient注解修饰的接口 + Set> classes = ClassUtil.scanPackageByAnnotation(packageName, FeignClient.class); + for (Class clazz : classes) { + GenericBeanDefinition beanDefinition = new GenericBeanDefinition(); + //使用FeignClientFactoryBean生成Feign客户端 + beanDefinition.setBeanClass(FeignClientFactoryBean.class); + String clientName = clazz.getAnnotation(FeignClient.class).value(); + beanDefinition.getPropertyValues().addPropertyValue("contextId", clientName); + beanDefinition.getPropertyValues().addPropertyValue("type", clazz); + + //将Feign客户端注册进bean容器 + String beanName = clazz.getName(); + registry.registerBeanDefinition(beanName, beanDefinition); + } + } +} +``` +注意BeanDefinition指定的beanClass为FeignClientFactoryBean，它是FactoryBean的实现类，bean容器取其getObject方法返回值作为bean: +```java +/** + * 生成Feign客户端的FactoryBean + */ +public class FeignClientFactoryBean implements FactoryBean, ApplicationContextAware { + private String contextId; + private Class type; + private ApplicationContext applicationContext; + @Override + public Object getObject() throws Exception { + FeignContext feignContext = applicationContext.getBean(FeignContext.class); + Encoder encoder = feignContext.getInstance(contextId, Encoder.class); + Decoder decoder = feignContext.getInstance(contextId, Decoder.class); + Contract contract = feignContext.getInstance(contextId, Contract.class); + Client client = feignContext.getInstance(contextId, Client.class); + + return Feign.builder() + .encoder(encoder) + .decoder(decoder) + .contract(contract) + .client(client) + .target(new HardCodedTarget<>(type, contextId, "http://" + contextId)); + } + //other methods +} +``` +跟ribbon一样，每一个Provider服务集群（应用名称即spring.application.name相同的所有应用服务提供者）对应一套feign核心API。**FeignContext继承自NamedContextFactory，为每一套feign核心API创建一个子spring应用上下文（ApplicationContext）**，来隔离不同服务的feign核心API配置(扩展篇实现)。 +FeignContext: +```java +/** + * 为每个feign客户端创建一个应用上下文(ApplicationContext)，隔离每个feign客户端的配置 + */ +public class FeignContext extends NamedContextFactory { + public FeignContext() { + super(FeignClientsConfiguration.class, "feign", "feign.client.name"); + } +} +``` +FeignClientsConfiguration配置类配置feign的核心API +```java +/** + * 配置feign的核心API + */ +@Configuration +public class FeignClientsConfiguration { + @Bean + @ConditionalOnMissingBean + public Encoder encoder() { + return new Encoder.Default(); + } + @Bean + @ConditionalOnMissingBean + public Decoder decoder() { + return new Decoder.Default(); + } + @Bean + @ConditionalOnMissingBean + public Contract contract() { + return new SpringMvcContract(); + } + @Bean + @ConditionalOnMissingBean + public Client client(LoadBalancerClient loadBalancerClient) { + return new LoadBalancerFeignClient(loadBalancerClient, new Client.Default(null, null)); + } +} +``` +SpringMvcContract简单实现支持Spring MVC的PostMapping注解: +```java +/** + * feign支持Spring MVC的注解 + */ +public class SpringMvcContract extends Contract.BaseContract { + @Override + protected void processAnnotationOnClass(MethodMetadata data, Class clz) { + //TODO 解析接口注解 + } + @Override + protected void processAnnotationOnMethod(MethodMetadata data, Annotation annotation, Method method) { + //解析方法注解 + //解析PostMapping注解 + if (annotation instanceof PostMapping) { + PostMapping postMapping = (PostMapping) annotation; + data.template().method(Request.HttpMethod.POST); + String path = postMapping.value()[0]; + if (!path.startsWith("/") && !data.template().path().endsWith("/")) { + path = "/" + path; + } + data.template().uri(path, true); + } + //TODO 解析其他注解 + } + @Override + protected boolean processAnnotationsOnParameter(MethodMetadata data, Annotation[] annotations, int paramIndex) { + //TODO 解析参数 + return true; + } +} +``` +LoadBalancerFeignClient组合ribbon的客户端负责均衡能力选择服务示例，然后发送http请求: +```java +/** + * 具备负载均衡能力的feign client + */ +public class LoadBalancerFeignClient implements Client { + private LoadBalancerClient loadBalancerClient; + private Client delegate; + public LoadBalancerFeignClient(LoadBalancerClient loadBalancerClient, Client delegate) { + this.loadBalancerClient = loadBalancerClient; + this.delegate = delegate; + } + @SuppressWarnings("deprecation") + @Override + public Response execute(Request request, Request.Options options) throws IOException { + try { + //客户端负载均衡 + URI original = URI.create(request.url()); + String serviceId = original.getHost(); + //选择服务实例 + ServiceInstance serviceInstance = loadBalancerClient.choose(serviceId); + //重建请求URI + URI uri = loadBalancerClient.reconstructURI(serviceInstance, original); + + Request newRequest = Request.create(request.httpMethod(), uri.toASCIIString(), new HashMap<>(), + request.body(), StandardCharsets.UTF_8); + return delegate.execute(newRequest, options); + } catch (IOException e) { + throw new RuntimeException(e); + } + } +} +``` +自动装配: +```java +@Configuration +public class FeignAutoConfiguration { + @Bean + public FeignContext feignContext() { + return new FeignContext(); + } +} +``` +spring.factories: +```yaml +org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ + com.github.cloud.openfeign.FeignAutoConfiguration +``` +测试: +消费者代码，使用@EnableFeignClients注解启用Feign: +```java +@EnableFeignClients +@SpringBootApplication +public class ConsumerApplication { + public static void main(String[] args) { + SpringApplication.run(ConsumerApplication.class, args); + } + @RestController + static class HelloController { + @Autowired + private EchoService echoService; + @GetMapping("/bar") + public String bar() { + return echoService.echo(); + } + } +} +``` +Feign客户端: +```java +@FeignClient("provider-application") +public interface EchoService { + @PostMapping("echo") + String echo(); +} +``` - - - - - +访问```http://localhost:8080/bar```