From 92a863dee82e2cba6e222f1eba05c76cdcc025ef Mon Sep 17 00:00:00 2001 From: fangjian0423 Date: Thu, 22 Nov 2018 14:36:46 +0800 Subject: [PATCH] update sentinel docs --- .../src/main/asciidoc-zh/sentinel.adoc | 9 +- .../sentinel-core-example/readme-zh.md | 98 +++++-------------- .../sentinel-core-example/readme.md | 81 ++++----------- .../src/main/resources/application.properties | 3 +- 4 files changed, 55 insertions(+), 136 deletions(-) diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sentinel.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sentinel.adoc index 260c3df3c..e4c9817fc 100644 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sentinel.adoc +++ b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sentinel.adoc @@ -167,7 +167,7 @@ private ReadableDataSource dataSource; 如果 `ApplicationContext` 中存在超过1个 `ReadableDataSource` bean，那么不会加载这些 `ReadableDataSource` 中的任意一个。 只有在 `ApplicationContext` 存在一个 `ReadableDataSource` 的情况下才会生效。 -如果数据库生效并且规则成功加载，控制台会打印类似如下信息： +如果数据源生效并且规则成功加载，控制台会打印类似如下信息： ``` [Sentinel Starter] load 3 flow rules @@ -216,6 +216,13 @@ NOTE: d1, ds2, ds3, ds4 是 `ReadableDataSource` 的名字，可随意编写。 用户使用这种配置的时候只需要填写正确的json或xml就行，有任何不合理的信息都会在日志里打印出来。 +如果数据源生效并且规则成功加载，控制台会打印类似如下信息： + +``` +[Sentinel Starter] DataSource ds1-sentinel-file-datasource load 3 DegradeRule +[Sentinel Starter] DataSource ds2-sentinel-nacos-datasource load 2 FlowRule +``` + NOTE: 默认情况下，xml格式是不支持的。需要添加 `jackson-dataformat-xml` 依赖后才会自动生效。 关于Sentinel动态数据源的实现原理，参考： https://github.com/alibaba/Sentinel/wiki/%E5%8A%A8%E6%80%81%E8%A7%84%E5%88%99%E6%89%A9%E5%B1%95[动态规则扩展] diff --git a/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/readme-zh.md b/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/readme-zh.md index c07c20e37..af535e6da 100644 --- a/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/readme-zh.md +++ b/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/readme-zh.md @@ -196,77 +196,33 @@ Sentinel 控制台支持实时监控查看，您可以通过 Sentinel 控制台 Sentinel 内部提供了[动态规则的扩展实现 ReadableDataSource](https://github.com/alibaba/Sentinel/wiki/%E5%8A%A8%E6%80%81%E8%A7%84%E5%88%99%E6%89%A9%E5%B1%95#datasource-%E6%89%A9%E5%B1%95)。 -Sentinel starter 整合了目前存在的几类 DataSource。只需要在配置文件中进行相关配置，即可在 Spring 容器中自动注册 DataSource。 - -比如要定义一个 `FileRefreshableDataSource`，配置如下： - - spring.cloud.sentinel.datasource.type=file - spring.cloud.sentinel.datasource.recommendRefreshMs=2000 - spring.cloud.sentinel.datasource.bufSize=2048 - spring.cloud.sentinel.datasource.charset=utf-8 - spring.cloud.sentinel.datasource.converter=myParser - spring.cloud.sentinel.datasource.file=/Users/you/rule.json - -然后使用`@SentinelDataSource` 注解修饰 DataSource 即可注入： - - @SentinelDataSource("spring.cloud.sentinel.datasource") - private ReadableDataSource dataSource; - -`@SentinelDataSource` 注解的 value 属性可以不填。默认值就是 `spring.cloud.sentinel.datasource`。 - -`value` 属性代表配置前缀。示例中会去找 `spring.cloud.sentinel.datasource.xxx` 相关的配置。 - -`spring.cloud.sentinel.datasource.type` 就是对应的 DataSource 类型。 - -`spring.cloud.sentinel.datasource.recommendRefreshMs` 里的 `recommendRefreshMs` 对应相关 DataSource 的属性。 - -`spring.cloud.sentinel.datasource.converter`代表 `Converter` 在 Spring 容器里的 name。如果没找到，会抛出异常。 - -type目前支持file, nacos, zk, apollo。其中nacos，zk，apollo的使用需要加上对应的依赖`sentinel-datasource-nacos`, `sentinel-datasource-zookeeper`, `sentinel-datasource-apollo` - -### 自定义DataSource - -自定义DataSource只需要两步。 - -1. 定义DataSource - - public class CustomDataSource implements ReadableDataSource { - private String fieldA; - private String fieldB; - ... - } - -2. 装配DataSource。有两种方式处理。 - - * 直接构造DataSource - - @Bean - public CustomDataSource customDataSource() { - CustomDataSource customDataSource = - new CustomDataSource(); - customDataSource.setFieldA("valueA"); - customDataSource.setFieldB("valueB"); - ... - return customDataSource; - } - - * 在classpath:/META-INF/sentinel-datasource.properties中管理DataSource信息 - - custom = yourpackage.CustomDataSource - - 在application.properties中定义DataSource - - spring.cloud.sentinel.datasource.type = custom - spring.cloud.sentinel.datasource.fieldA = valueA - spring.cloud.sentinel.datasource.fieldB = valueB - - 注意：由于目前Sentinel的AbstractDataSource需要有个Converter作为构造函数中的参数，并且它的子类的构造都是通过多个参数的构造函数构造的。 - 所以目前所有的Sentinel starter中的DataSource都是基于FactoryBean并且通过设置属性构造的。如果有这方面的需求，需要再多加一个registerFactoryBean过程。 - - SentinelDataSourceRegistry.registerFactoryBean("custeom", CustomDataSourceFactoryBean.class); - - 如果自定义DataSource可以注入属性，那么没有必要使用SentinelDataSourceRegistry注册FactoryBean。 - +Sentinel starter 整合了目前存在的几类 ReadableDataSource。只需要在配置文件中进行相关配置，即可在 Spring 容器中自动注册 DataSource。 + +比如要定义两个ReadableDataSource，分别是 `FileRefreshableDataSource` 和 `NacosDataSource`，配置如下： + +```properties +spring.cloud.sentinel.datasource.ds1.file.file=classpath: degraderule.json +spring.cloud.sentinel.datasource.ds1.file.data-type=json + +spring.cloud.sentinel.datasource.ds2.nacos.server-addr=localhost:8848 +spring.cloud.sentinel.datasource.ds2.nacos.dataId=sentinel +spring.cloud.sentinel.datasource.ds2.nacos.groupId=DEFAULT_GROUP +spring.cloud.sentinel.datasource.ds2.nacos.data-type=json +``` + +`ds1` 和 `ds2` 表示ReadableDataSource的名称，可随意编写。`ds1` 和 `ds2` 后面的 `file` 和 `nacos` 表示ReadableDataSource的类型。 + +目前支持`file`, `nacos`, `zk`, `apollo` 这4种类型。 + +其中`nacos`，`zk`，`apollo`这3种类型的使用需要加上对应的依赖`sentinel-datasource-nacos`, `sentinel-datasource-zookeeper`, `sentinel-datasource-apollo`。 + +当ReadableDataSource加载规则数据成功的时候，控制台会打印出相应的日志信息： + +``` +[Sentinel Starter] DataSource ds1-sentinel-file-datasource load 3 DegradeRule +[Sentinel Starter] DataSource ds2-sentinel-nacos-datasource load 2 FlowRule +``` + ## More Sentinel 是一款功能强大的中间件，从流量控制，熔断降级，系统负载保护等多个维度保护服务的稳定性。此 Demo 仅演示了 使用 Sentinel 作为限流工具的使用，更多 Sentinel 相关的信息，请参考 [Sentinel 项目](https://github.com/alibaba/Sentinel)。 diff --git a/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/readme.md b/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/readme.md index dcdd77fc3..e31357295 100644 --- a/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/readme.md +++ b/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/readme.md @@ -71,7 +71,7 @@ Before we start the demo, let's learn how to connect Sentinel to a Spring Cloud 2. Start the application in IDE or by building a fatjar. 1. Start in IDE: Find main class `ServiceApplication`, and execute the main method. - 2. Build a fatjar：Execute command `mvn clean package` to build a fatjar，and run command `java -jar sentinel-core-example.jar` to start the application. + 2. Build a fatjar：Execute command `mvn clean package` to build a fatjar, and run command `java -jar sentinel-core-example.jar` to start the application. ### Invoke Service @@ -86,7 +86,7 @@ The screenshot belows shows invoke success: 1. Open http://localhost:8080 in browser, and you can find a Sentinel-Example Application has been registered to the dashboard. - **Note: If you can't find your application in the dashboard, invoke a method that has been defined as a Sentinel Resource，for Sentinel uses lazy load strategy.** + **Note: If you can't find your application in the dashboard, invoke a method that has been defined as a Sentinel Resource, for Sentinel uses lazy load strategy.**

@@ -171,73 +171,30 @@ Sentinel provide [ReadableDataSource](https://github.com/alibaba/Sentinel/blob/m Sentinel starter integrated 4 DataSources provided by Sentinel. It will be register into Spring Context if you write some configs in `application.properties`. -If you want to define FileRefreshableDataSource: +If you want to define `FileRefreshableDataSource` and `NacosDataSource`, see the code below: - spring.cloud.sentinel.datasource.type=file - spring.cloud.sentinel.datasource.recommendRefreshMs=2000 - spring.cloud.sentinel.datasource.bufSize=2048 - spring.cloud.sentinel.datasource.charset=utf-8 - spring.cloud.sentinel.datasource.converter=myParser - spring.cloud.sentinel.datasource.file=/Users/you/rule.json - -then use `@SentinelDataSource` to annotate DataSource: - - @SentinelDataSource("spring.cloud.sentinel.datasource") - private ReadableDataSource dataSource; - -The value() of `@SentinelDataSource` is not required, it means the prefix of configuration. Default value is `spring.cloud.sentinel.datasource`. - -spring.cloud.sentinel.datasource.type means the type of DataSource. +```properties +spring.cloud.sentinel.datasource.ds1.file.file=classpath: degraderule.json +spring.cloud.sentinel.datasource.ds1.file.data-type=json -spring.cloud.sentinel.datasource.recommendRefreshMs means the recommendRefreshMs property of specified DataSource. +spring.cloud.sentinel.datasource.ds2.nacos.server-addr=localhost:8848 +spring.cloud.sentinel.datasource.ds2.nacos.dataId=sentinel +spring.cloud.sentinel.datasource.ds2.nacos.groupId=DEFAULT_GROUP +spring.cloud.sentinel.datasource.ds2.nacos.data-type=json +``` -spring.cloud.sentinel.datasource.converter means the name of spring bean that type is Converter. If the bean is not exists, will throw exception. - -Now datasource type support 4 categories: file, nacos, zk, apollo. If you want to using nacos, zk or apollo, you should add `sentinel-datasource-nacos`, `sentinel-datasource-zookeeper` or `sentinel-datasource-apollo` dependency. +`ds1` and `ds2` means the name of ReadableDataSource, you can write whatever you want. The `file` and `nacos` after name `ds1` and `ds2` means the type of ReadableDataSource. +Now ReadableDataSource type support 4 categories: `file`, `nacos`, `zk` and `apollo`. -### User-defined DataSource +If you want to use `nacos`, `zk` or `apollo` ReadableDataSource, you could add `sentinel-datasource-nacos`, `sentinel-datasource-zookeeper` or `sentinel-datasource-apollo` dependency. -User-defined DataSource need 2 steps. +When ReadableDataSource load rule data successfully, console will print some logs: -1. Define DataSource - - public class CustomDataSource implements ReadableDataSource { - private String fieldA; - private String fieldB; - ... - } - -2. Assemble DataSource. There are 2 ways to do this. - - * Construct DataSource directly - - @Bean - public CustomDataSource customDataSource() { - CustomDataSource customDataSource = new CustomDataSource(); - customDataSource.setFieldA("valueA"); - customDataSource.setFieldB("valueB"); - ... - return customDataSource; - } - - * define DataSource metadata in `classpath:/META-INF/sentinel-datasource.properties` - - custom = yourpackage.CustomDataSource - - define configuration in `application.properties` - - spring.cloud.sentinel.datasource.type = custom - spring.cloud.sentinel.datasource.fieldA = valueA - spring.cloud.sentinel.datasource.fieldB = valueB - -Note: The AbstractDataSource of Sentinel need a Converter as a constructor param and the subclass of AbstractDataSource was construct by multi-param constructor. -Now All DataSources in starter was construct by FactoryBean. If you want to do it in this way, you should register FactoryBean by SentinelDataSourceRegistry. - - SentinelDataSourceRegistry.registerFactoryBean("custeom", CustomDataSourceFactoryBean.class); - -It is no need to using SentinelDataSourceRegistry to register FactoryBean if your User-defined DataSource can inject fields. - +``` +[Sentinel Starter] DataSource ds1-sentinel-file-datasource load 3 DegradeRule +[Sentinel Starter] DataSource ds2-sentinel-nacos-datasource load 2 FlowRule +``` ## More For more information about Sentinel, see [Sentinel Project](https://github.com/alibaba/Sentinel). diff --git a/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/src/main/resources/application.properties b/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/src/main/resources/application.properties index 100b40102..9f9a734e9 100644 --- a/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/src/main/resources/application.properties +++ b/spring-cloud-alibaba-examples/sentinel-example/sentinel-core-example/src/main/resources/application.properties @@ -1,8 +1,7 @@ spring.application.name=sentinel-example server.port=18083 management.endpoints.web.exposure.include=* -spring.cloud.sentinel.transport.port=8721 -spring.cloud.sentinel.transport.dashboard=localhost:9999 +spring.cloud.sentinel.transport.dashboard=localhost:8080 spring.cloud.sentinel.eager=true spring.cloud.sentinel.datasource.ds1.file.file=classpath: flowrule.json