Merge pull request #798 from pigxcloud/master

add sentinel feign example and doc

spring-cloud-alibaba-examples/pom.xml

@@ -20,6 +20,8 @@
         <module>sentinel-example/sentinel-dubbo-example/sentinel-dubbo-provider-example</module>
         <module>sentinel-example/sentinel-dubbo-example/sentinel-dubbo-consumer-example</module>
         <module>sentinel-example/sentinel-dubbo-example/sentinel-dubbo-api</module>
+        <module>sentinel-example/sentinel-feign-example/sentinel-feign-consumer-example</module>
+        <module>sentinel-example/sentinel-feign-example/sentinel-feign-provider-example</module>
         <module>sentinel-example/sentinel-webflux-example</module>
         <module>sentinel-example/sentinel-spring-cloud-gateway-example</module>
         <module>sentinel-example/sentinel-zuul-example</module>

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/readme-zh.md

@@ -0,0 +1,125 @@
+# Sentinel Feign Example
+
+## 项目说明
+
+本项目演示如何使用 Sentinel starter 完成 Spring Cloud 应用调用。
+
+[Sentinel](https://github.com/alibaba/Sentinel) 是阿里巴巴开源的分布式系统的流量防卫组件，Sentinel 把流量作为切入点，从流量控制，熔断降级，系统负载保护等多个维度保护服务的稳定性。
+
+[OpenFeign](https://github.com/spring-cloud/spring-cloud-openfeign)是一款声明式、模板化的HTTP客户端， Feign可以帮助我们更快捷、优雅地调用HTTP API。
+
+本项目专注于Sentinel与Feign的整合，关于Sentinel的更多特性可以查看[sentinel-core-example](https://github.com/alibaba/spring-cloud-alibaba/tree/master/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example)。
+
+## 示例
+
+### 服务消费方
+在启动示例进行演示之前，我们先了解一下 Feign 如何接入 Sentinel。
+**注意 本章节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您无需再进行修改。**
+
+1. 首先，修改 pom.xml 文件，引入 Sentinel starter 和 Dubbo starter。
+
+```xml
+<dependency>
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-starter-openfeign</artifactId>
+</dependency>
+
+<dependency>
+    <groupId>com.alibaba.cloud</groupId>
+    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
+</dependency>
+
+```
+2. 其次, 使用nacos 注册中心
+	
+```xml
+<dependency>
+    <groupId>com.alibaba.cloud</groupId>
+    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
+</dependency>
+```
+
+3. 定义FeignClient,及其降级配置
+
+- 定义FeignClient
+```java
+@FeignClient(name = "service-provider", fallbackFactory = EchoServiceFallbackFactory.class)
+public interface EchoService {
+
+    /**
+     * 调用服务提供方的输出接口
+     *
+     * @param str 用户输入
+     * @return
+     */
+    @GetMapping(value = "/echo/{str}")
+    String echo(@PathVariable("str") String str);
+}
+```
+- 定义fallback 工厂，获取异常
+
+```java
+@Component
+public class EchoServiceFallbackFactory implements FallbackFactory<EchoServiceFallback> {
+    @Override
+    public EchoServiceFallback create(Throwable throwable) {
+        return new EchoServiceFallback(throwable);
+    }
+}
+```
+
+- 定义具体的fallback 实现
+```java
+public class EchoServiceFallback implements EchoService {
+    private Throwable throwable;
+
+    EchoServiceFallback(Throwable throwable) {
+        this.throwable = throwable;
+    }
+
+    @Override
+    public String echo(String str) {
+        return "consumer-fallback-default-str" + throwable.getMessage();
+    }
+}
+```
+### 服务提供方
+
+1. 首先， 依赖nacos 注册中心
+
+```xml
+<dependency>
+    <groupId>com.alibaba.cloud</groupId>
+    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
+</dependency>
+```
+
+2. 定义服务提供方接口
+
+```java
+@RestController
+public class EchoController {
+
+    @GetMapping("/echo/{str}")
+    public String echo(@PathVariable String str) {
+        return "provider-" + str;
+    }
+
+}
+```
+### 应用启动 
+
+
+支持 IDE 直接启动和编译打包后启动。
+
+- 启动nacos 注册中心
+
+- 启动服务提供方：
+
+1. IDE直接启动：找到主类 `ProviderApplication`，执行 main 方法启动应用。
+2. 打包编译后启动：首先执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar sentinel-feign-provider-example.jar`启动应用。
+
+- 启动服务消费方：
+
+1. IDE直接启动：找到主类 `ConsumerApplication`，执行 main 方法启动应用。
+2. 打包编译后启动：首先执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar sentinel-feign-consumer-example.jar`启动应用。

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/readme.md

@@ -0,0 +1,126 @@
+# Sentinel Feign Example
+
+Project description
+
+This project demonstrates how to use Sentinel starter to complete the Spring Cloud application call.
+
+[Sentinel](https://github.com/alibaba/Sentinel) is alibaba open source distributed system flow defense components, Sentinel flow as the breakthrough point, from the flow control, fusing the drop, the stability of the system load multiple dimensions, such as protection services.
+
+[OpenFeign](https://github.com/spring-cloud/spring-cloud-openfeign) is a declarative, templated HTTP client, Feign can help us faster and gracefully HTTP API calls.
+
+By focusing on this project, the integration of Sentinel and Feign more characteristics about Sentinel can view [Sentinel - core - example](https://github.com/alibaba/spring-cloud-alibaba/tree/master/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example).
+
+## sample
+
+Service consumer
+Before launching the example, let's see how Feign can access Sentinel.
+** note that this section is for your convenience only. The access has been completed in this sample code and you do not need to modify it. * *
+
+First, modify the pom.xml file to introduce Sentinel starter and Dubbo starter.
+
+```xml
+<dependency>
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-starter-openfeign</artifactId>
+</dependency>
+
+<dependency>
+    <groupId>com.alibaba.cloud</groupId>
+    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
+</dependency>
+
+```
+2. Secondly, nacos registries are used
+
+```xml
+<dependency>
+    <groupId>com.alibaba.cloud</groupId>
+    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
+</dependency>
+```
+
+3. Define the FeignClient and its degraded configuration
+
+```java
+@FeignClient(name = "service-provider", fallbackFactory = EchoServiceFallbackFactory.class)
+public interface EchoService {
+
+    /**
+     * 调用服务提供方的输出接口
+     *
+     * @param str 用户输入
+     * @return
+     */
+    @GetMapping(value = "/echo/{str}")
+    String echo(@PathVariable("str") String str);
+}
+```
+- define a fallback factory to get an exception
+
+```java
+@Component
+public class EchoServiceFallbackFactory implements FallbackFactory<EchoServiceFallback> {
+    @Override
+    public EchoServiceFallback create(Throwable throwable) {
+        return new EchoServiceFallback(throwable);
+    }
+}
+```
+
+- define a specific fallback implementation
+```java
+public class EchoServiceFallback implements EchoService {
+    private Throwable throwable;
+
+    EchoServiceFallback(Throwable throwable) {
+        this.throwable = throwable;
+    }
+
+    @Override
+    public String echo(String str) {
+        return "consumer-fallback-default-str" + throwable.getMessage();
+    }
+}
+```
+Service provider
+
+1. First, rely on the nacos registry
+
+```xml
+<dependency>
+    <groupId>com.alibaba.cloud</groupId>
+    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
+</dependency>
+```
+
+
+2. Define the service provider interface
+
+```java
+@RestController
+public class EchoController {
+
+    @GetMapping("/echo/{str}")
+    public String echo(@PathVariable String str) {
+        return "provider-" + str;
+    }
+
+}
+```
+
+Application launch
+
+
+Support for IDE startup directly and after compilation and packaging.
+
+- launch the nacos registry
+
+- starting service provider:
+
+1. IDE starts directly: find the main class `ProviderApplication` and execute the main method to start the application.
+2. Start after packaging and compilation: first execute `mvn clean package` to compile and package the project, and then execute `java-jar sentinel-feign-provider-example.jar` to start the application.
+
+- starting service consumer:
+
+1. IDE launch directly: find the main class `ConsumerApplication` and execute the main method to launch the application.
+2. Start after packaging and compilation: first execute `mvn clean package` to compile and package the project, and then execute `java-jar sentinel-feign-consumer-example.jar` to start the application.

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-consumer-example/pom.xml

@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+    <parent>
+        <groupId>com.alibaba.cloud</groupId>
+        <artifactId>spring-cloud-alibaba-examples</artifactId>
+        <version>2.1.1.BUILD-SNAPSHOT</version>
+        <relativePath>../../../pom.xml</relativePath>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+
+    <artifactId>sentinel-feign-consumer-example</artifactId>
+    <packaging>jar</packaging>
+    <description>Example demonstrating how to use sentinel with feign</description>
+
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.alibaba.cloud</groupId>
+            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.cloud</groupId>
+            <artifactId>spring-cloud-starter-openfeign</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>com.alibaba.cloud</groupId>
+            <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
+        </dependency>
+
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-deploy-plugin</artifactId>
+                <version>${maven-deploy-plugin.version}</version>
+                <configuration>
+                    <skip>true</skip>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-consumer-example/src/main/java/com/alibaba/cloud/examples/ConsumerApplication.java

@@ -0,0 +1,20 @@
+package com.alibaba.cloud.examples;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.cloud.client.SpringCloudApplication;
+import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
+import org.springframework.cloud.openfeign.EnableFeignClients;
+
+/**
+ * @author lengleng
+ */
+@EnableFeignClients
+@SpringCloudApplication
+public class ConsumerApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(ConsumerApplication.class, args);
+    }
+
+}

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-consumer-example/src/main/java/com/alibaba/cloud/examples/controller/TestController.java

@@ -0,0 +1,23 @@
+package com.alibaba.cloud.examples.controller;
+
+import com.alibaba.cloud.examples.service.EchoService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * @author lengleng
+ */
+@RestController
+public class TestController {
+
+    @Autowired
+    private EchoService echoService;
+
+    @GetMapping(value = "/echo-feign/{str}")
+    public String feign(@PathVariable String str) {
+        return echoService.echo(str);
+    }
+
+}

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-consumer-example/src/main/java/com/alibaba/cloud/examples/fallback/EchoServiceFallback.java

@@ -0,0 +1,28 @@
+package com.alibaba.cloud.examples.fallback;
+
+import com.alibaba.cloud.examples.service.EchoService;
+
+/**
+ * @author lengleng
+ * @date 2019-08-01
+ * <p>
+ * sentinel 降级处理
+ */
+public class EchoServiceFallback implements EchoService {
+    private Throwable throwable;
+
+    EchoServiceFallback(Throwable throwable) {
+        this.throwable = throwable;
+    }
+
+    /**
+     * 调用服务提供方的输出接口
+     *
+     * @param str 用户输入
+     * @return
+     */
+    @Override
+    public String echo(String str) {
+        return "consumer-fallback-default-str" + throwable.getMessage();
+    }
+}

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-consumer-example/src/main/java/com/alibaba/cloud/examples/fallback/EchoServiceFallbackFactory.java

@@ -0,0 +1,16 @@
+package com.alibaba.cloud.examples.fallback;
+
+import feign.hystrix.FallbackFactory;
+import org.springframework.stereotype.Component;
+
+/**
+ * @author lengleng
+ * @date 2019-08-01
+ */
+@Component
+public class EchoServiceFallbackFactory implements FallbackFactory<EchoServiceFallback> {
+    @Override
+    public EchoServiceFallback create(Throwable throwable) {
+        return new EchoServiceFallback(throwable);
+    }
+}

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-consumer-example/src/main/java/com/alibaba/cloud/examples/service/EchoService.java

@@ -0,0 +1,25 @@
+package com.alibaba.cloud.examples.service;
+
+import com.alibaba.cloud.examples.fallback.EchoServiceFallbackFactory;
+import org.springframework.cloud.openfeign.FeignClient;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+
+/**
+ * @author lengleng
+ * @date 2019-08-01
+ * <p>
+ * example feign client
+ */
+@FeignClient(name = "service-provider", fallbackFactory = EchoServiceFallbackFactory.class)
+public interface EchoService {
+
+    /**
+     * 调用服务提供方的输出接口
+     *
+     * @param str 用户输入
+     * @return
+     */
+    @GetMapping(value = "/echo/{str}")
+    String echo(@PathVariable("str") String str);
+}

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-consumer-example/src/main/resources/application.yml

@@ -0,0 +1,20 @@
+server:
+  port: 18087
+
+spring:
+  application:
+    name: service-consumer
+  cloud:
+    nacos:
+      discovery:
+        server-addr: 127.0.0.1:8848
+
+feign:
+  sentinel:
+    enabled: true
+
+management:
+  endpoints:
+    web:
+      exposure:
+        include: '*'

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-provider-example/pom.xml

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+    <parent>
+        <groupId>com.alibaba.cloud</groupId>
+        <artifactId>spring-cloud-alibaba-examples</artifactId>
+        <version>2.1.1.BUILD-SNAPSHOT</version>
+        <relativePath>../../../pom.xml</relativePath>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+
+    <artifactId>sentinel-feign-provider-example</artifactId>
+    <packaging>jar</packaging>
+    <description>Example demonstrating how to use sentinel with feign</description>
+
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.alibaba.cloud</groupId>
+            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-deploy-plugin</artifactId>
+                <version>${maven-deploy-plugin.version}</version>
+                <configuration>
+                    <skip>true</skip>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-provider-example/src/main/java/com/alibaba/cloud/examples/ProviderApplication.java

@@ -0,0 +1,17 @@
+package com.alibaba.cloud.examples;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
+
+/**
+ * @author lengleng
+ */
+@EnableDiscoveryClient
+@SpringBootApplication
+public class ProviderApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(ProviderApplication.class, args);
+    }
+}

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-provider-example/src/main/java/com/alibaba/cloud/examples/controller/EchoController.java

@@ -0,0 +1,19 @@
+package com.alibaba.cloud.examples.controller;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * @author lengleng
+ * @date 2019-08-01
+ */
+@RestController
+public class EchoController {
+
+    @GetMapping("/echo/{str}")
+    public String echo(@PathVariable String str) {
+        return "provider-" + str;
+    }
+
+}

spring-cloud-alibaba-examples/sentinel-example/sentinel-feign-example/sentinel-feign-provider-example/src/main/resources/application.yml

@@ -0,0 +1,16 @@
+server:
+  port: 18088
+
+spring:
+  application:
+    name: service-provider
+  cloud:
+    nacos:
+      discovery:
+        server-addr: 127.0.0.1:8848
+
+management:
+  endpoints:
+    web:
+      exposure:
+        include: '*'