Polish #186. Optimize usage of Sentinel RestTemplate

spring-cloud-alibaba-docs/src/main/asciidoc-zh/sentinel.adoc

@@ -160,9 +160,25 @@ public RestTemplate restTemplate() {
 }
 ```
 
-`@SentinelRestTemplate` 注解的参数跟 `@SentinelResource` 一致，使用方式也一致。
+`@SentinelRestTemplate` 注解的参数支持限流(`blockHandler`, `blockHandlerClass`)和降级(`fallback`, `fallbackClass`)的处理。
 
-限流的资源规则提供两种粒度：
+其中 `blockHandler` 或 `fallback` 对应的方法必须是对应 `blockHandlerClass` 或 `fallbackClass` 中的静态方法。
+
+该注解对应的方法参数跟 `ClientHttpRequestInterceptor` 接口中的参数一致，并多出了一个 `BlockException` 参数，且返回值是 `ClientHttpResponse`。
+
+比如上述 `ExceptionUtil` 的 `handleException` 方法对应的声明如下：
+
+```java
+public class ExceptionUtil {
+    public static ClientHttpResponse handleException(HttpRequest request, byte[] body, ClientHttpRequestExecution execution, BlockException exception) {
+        ...
+    }
+}
+```
+
+`@SentinelRestTemplate` 注解的限流(`blockHandler`, `blockHandlerClass`)和降级(`fallback`, `fallbackClass`)不强制填写，当被 Sentinel 熔断后，会返回 `RestTemplate request block by sentinel` 信息，或者也可以填写对应的方法自行处理。
+
+Sentinel RestTemplate 限流的资源规则提供两种粒度：
 
 * `schema://host:port/path`：协议、主机、端口和路径
 
@@ -172,7 +188,7 @@ NOTE: 以 `https://www.taobao.com/test` 这个 url 为例。对应的资源名
 
 ### 动态数据源支持
 
-#### 在版本 0.2.0.RELEASE 或 0.1.0.RELEASE 之前
+#### 在我们的第一个版本 0.2.0.RELEASE 或 0.1.0.RELEASE 中的使用方式
 
 需要3个步骤才可完成数据源的配置：
 
@@ -220,7 +236,7 @@ private ReadableDataSource dataSource;
 [Sentinel Starter] load 3 flow rules
 ```
 
-#### 在版本 0.2.0.RELEASE 或 0.1.0.RELEASE 之后
+#### 后续版本的使用方式
 
 只需要1个步骤就可完成数据源的配置：
 
@@ -253,7 +269,7 @@ NOTE: d1, ds2, ds3, ds4 是 `ReadableDataSource` 的名字，可随意编写。
 
 `data-type` 配置项表示 `Converter`，Spring Cloud Alibaba Sentinel 默认提供两种内置的值，分别是 `json` 和 `xml` (不填默认是json)。 如果不想使用内置的 `json` 或 `xml` 这两种 `Converter`，可以填写 `custom` 表示自定义 `Converter`，然后再配置 `converter-class` 配置项，该配置项需要写类的全路径名。
 
-这两种内置的 `Converter` 只支持解析 json 数组 或 xml 数组。内部解析的时候会自动判断每个 json 对象或xml对象属于哪4种 Sentinel 规则(`FlowRule`，`DegradeRule`，`SystemRule`，`AuthorityRule`)。
+这两种内置的 `Converter` 只支持解析 json 数组 或 xml 数组。内部解析的时候会自动判断每个 json 对象或xml对象属于哪4种 Sentinel 规则(`FlowRule`，`DegradeRule`，`SystemRule`，`AuthorityRule`, `ParamFlowRule`)。
 
 比如10个规则数组里解析出5个限流规则和5个降级规则。 这种情况下该数据源不会注册，日志里页会进行警告。
 

spring-cloud-alibaba-docs/src/main/asciidoc/sentinel.adoc

@@ -160,9 +160,27 @@ public RestTemplate restTemplate() {
 }
 ```
 
-The parameter of the `@SentinelRestTemplate` annotation and its usage is the same with `@SentinelResource`.
+The parameter of the `@SentinelRestTemplate` annotation support flow control(`blockHandler`, `blockHandlerClass`) and circuit breaking(`fallback`, `fallbackClass`).
 
-Sentinel provides two granularities for resource rate limiting:
+==
+
+The `blockHandler` or `fallback` is the static method of `blockHandlerClass` or `fallbackClass`.
+
+The parameter of method in `@SentinelRestTemplate` is same as `ClientHttpRequestInterceptor`, but it has one more parameter `BlockException` and its value of return type should be `ClientHttpResponse`.
+
+The method signature of `handleException` in `ExceptionUtil` above should be like this:
+
+```java
+public class ExceptionUtil {
+    public static ClientHttpResponse handleException(HttpRequest request, byte[] body, ClientHttpRequestExecution execution, BlockException exception) {
+        ...
+    }
+}
+```
+
+It will return `RestTemplate request block by sentinel` when you do not write any flow control(`blockHandler`, `blockHandlerClass`) configuration or circuit breaking configuration(`fallback`, `fallbackClass`), you can override it by using your own method.
+
+Sentinel RestTemplate provides two granularities for resource rate limiting:
 
 * `schema://host:port/path`： Protocol, host, port and path
 
@@ -172,7 +190,7 @@ NOTE: Take `https://www.taobao.com/test` as an example. The corresponding resour
 
 ### Dynamic Data Source Support
 
-#### For 0.2.0.RELEASE or 0.1.0.RELEASE and ealier versions,
+#### The usage of our first version 0.2.0.RELEASE or 0.1.0.RELEASE
 
 you need to complete the following 3 steps to configure your data source.
 
@@ -220,7 +238,7 @@ If the data source takes effect and is loaded successfully, the dashboard will p
 [Sentinel Starter] load 3 flow rules
 ```
 
-#### In  0.2.0.RELEASE and 0.1.0.RELEASE or later
+#### The usage after first version
 
 You only need to complete 1 step to configure your data source:
 
@@ -247,13 +265,13 @@ spring.cloud.sentinel.datasource.ds4.apollo.default-flow-rule-value = test
 
 This method follows the configuration of Spring Cloud Stream Binder. `TreeMap` is used for storage internally, and comparator is `String.CASE_INSENSITIVE_ORDER`.
 
-NOTE: d1, ds2, ds3, ds4 are the names of `ReadableDataSource`, and can be coded as you like. The `file` ，`zk` ，`nacos` , `apollo` refer to the specific data sources. The configurations following them are the specific configurations of these data sources respecitively.
+NOTE: d1, ds2, ds3, ds4 are the names of `ReadableDataSource`, and can be coded as you like. The `file`, `zk`, `nacos` , `apollo` refer to the specific data sources. The configurations following them are the specific configurations of these data sources respecitively.
 
 Every data source has two common configuration items: `data-type` and `converter-class`.
 
 `data-type` refers to `Converter`. Spring Cloud Alibaba Sentinel provides two embedded values by defaul: `json` and `xml` (the default is json if not specified). If you do not want to use the embedded `json` or `xml` `Converter`, you can also fill in `custom` to indicate that you will define your own `Converter`, and then configure the `converter-class`. You need to specify the full path of the class for this configuration.
 
-The two embedded `Converter` only supports parsing the Json array or XML array. Sentinel will determine automatically which of the 4 Sentinel rules that the Json or XML objext belongs to(`FlowRule`，`DegradeRule`，`SystemRule`，`AuthorityRule`).
+The two embedded `Converter` only supports parsing the Json array or XML array. Sentinel will determine automatically which of the 4 Sentinel rules that the Json or XML objext belongs to(`FlowRule`, `DegradeRule`, `SystemRule`, `AuthorityRule`, `ParamFlowRule`).
 
 For example, if 5 rate limiting rules and 5 degradation rules in the 10 rule arrays,  then the data source will not be registered, and there will be warnings in the logs.