本次旅程您将获得如下知识：
- Sentinel 的热点参数限流
- 将 Sentinel 热点参数限流规则持久化到 Nacos
- Spring Boot 项目接口统一返回与统一异常处理
- 使用 SentinelResource 注解的 blockHandler 和 fallback 进行优雅返回与解耦
本系列文章代码仓库：https://github.com/ChenDapengJava/SpringCloudAlibabaDemo
前言
本篇文章填上次 将 Sentinel 熔断限流规则持久化到 Nacos 配置中心 提到的一个问题：之前我们访问接口进行限流或者降级后，直接返回500错误，或者提示 flow limit 之类的东西：
这样显得很不优雅，透漏着不专业，那么进行限流或者降级后该如何进行优雅的返回呢？
本章从 Sentinel 的 「热点参数限流」 着手，使用注解 @SentinelResource 的 blockHandler 和 fallback 来实现限流后优雅的返回。
Sentinel的热点参数限流
看到限流名字 热点参数 ，顾名思义，就能想到是针对请求资源的参数进行限流的。如果参数是 热点参数 ，并且符合设置的热点参数限流规则，那么 Sentinel 也对其进行限流。
何为 热点参数 呢？联想一下娱乐圈的那些明星，粉丝越多的明星，他的热度就越高。同理，一个系统，访问的数据越频繁，这个数据的热度就越高。这种经常访问的数据就是 「热点」 。
有些时候，需要采取一些措施对 「热点数据」 进行限制，比如：
- 统计一段时间内最常访问的某个商品 ID （参数为商品 ID ），那么对该商品 ID 进行限制；
- 请求资源参数用户 ID ，针对一段时间内频繁访问的用户 ID 进行限制；
- 等等
热点参数限流 「会统计传入参数中的热点参数，并根据配置的限流阈值与模式，对包含热点参数的资源调用进行限流。」
热点参数限流可以看做是一种特殊的流量控制，仅对包含热点参数的资源调用生效。
下面我们就开始创建包含热点参数的接口资源，并配置热点参数限流规则进行验证 Sentinel 的热点参数限流功能。
还是用之前的微服务项目 sentinel-service ，新增一个接口资源如下：
@RestController
@Slf4j
public class UserController {
@GetMapping("/getProduct")
@SentinelResource("getProduct")
public String getProduct(@RequestParam(value = "userId", required = false) Long userId,
@RequestParam(value = "productId", required = false) Long productId,
@RequestParam(value = "categoryId", required = false) Integer categoryId) {
log.info("getProduct param userId={},productId={},categoryId={}", userId, productId, categoryId);
return "getProduct success";
}
}
下面开始通过 Sentinel 控制台和 Nacos 配置中心两种方式进行规则配置。
通过 Sentinel 控制台进行热点参数限流规则配置
在控制台，在簇点链路上找到对应的资源，进行 「热点」 规则配置：
打开 「热点」 操作：
如图所示的就是对资源 getProduct 的第一个参数 userId 进行限流，如果配置单机阈值为1，窗口统计时长1秒，那么其含义就是： 「在1秒内访问 getProduct 资源超过1次，如果传入了热点参数 userId，那么将对该资源进行限流，如果没有传入 userId，那么该资源不被限流。」
现在我们来访问接口验证一下，先传入不是热点的参数 categoryId ：
可以看到，无论QPS是多少，接口都正常返回，没有进行限流，现在我们加上热点参数 userId 试一下：
1秒内快速刷新几下，QPS只要大于1了，接口访问就芭比Q了，说明 Sentinel 的热点参数限流生效了。
Sentinel 热点参数限流规则持久化到 Nacos
在 Nacos 设置 Data ID 及规则内容
在 Sentinel 控制台配置的规则，当服务重启后，规则将消失，这并不是我们想要的结果，上一篇文章中，我们已经完成了 Sentinel 的规则持久化到 Nacos 中，本小节我们配置一下热点参数的限流规则。
热点参数的限流规则主要有以下几个字段：
resource：资源名，必填项；count：限流阈值，必填项；grade：限流模式，只能是 「QPS」 ；paramIdx：热点参数的索引，必填项，索引从 0 开始；durationInSec：统计窗口时间长度（单位为秒），默认为 1 s；controlBehavior：流控效果（支持快速失败和匀速排队模式），默认为快速失败；maxQueueingTimeMs：最大排队等待时长（仅在匀速排队模式生效），默认 0 ms；paramFlowItemList：参数例外项，可以针对指定的参数值单独设置限流阈值，不受前面count阈值的限制。 「仅支持基本类型和字符串类型」 。clusterMode：是否是集群参数流控规则，默认为false；clusterConfig：集群流控相关配置。
下面我们在 Nacos 控制台中对资源 getProduct 添加 「热点参数限流规则」 ：
这里的设置和前文在 Sentinel 控制台设置的含义一致。
配置 application.yml
Nacos 中持久化了限流规则，那么在微服务项目中，可以在 application.yml 配置文件中这样配置：
spring:
application:
name: sentinel-service
cloud:
nacos:
discovery:
# Nacos 集群
server-addr: 192.168.242.112:81
sentinel:
transport:
dashboard: localhost:8080
port: 8719
# https://github.com/alibaba/Sentinel/issues/1213
web-context-unify: false
# Sentinel 规则持久化到 Nacos
datasource:
rule1:
nacos:
serverAddr: 192.168.242.112:81
groupId: DEFAULT_GROUP
dataId: sentinelFlowRule.json
ruleType: flow
rule2:
nacos:
serverAddr: 192.168.242.112:81
groupId: DEFAULT_GROUP
dataId: hotKeyRule.json
ruleType: param-flow
其中 ruleType 为 「param-flow」 的就是热点参数限流的规则，一定要把 dataId 配置正确。
然后启动服务，重新验证限流规则，依然生效：
热点参数限流生效
接口统一返回和统一异常处理
前面接口 getProduct 调用成功返回字符串 getProduct success ,调用失败返回了一个 500 Internal Server Error ，这种返回格式没有一个统一的格式，这在前后端分离项目中并不是很好的实践。前后端应该约定好每个接口的统一返回格式。
本文在 SpringCloudAlibabaDemo 父工程模块下增加一个子模块 internal-common 作为公共模块，其他子模块可以引入该模块使用。
internal-common 子模块中定义了接口返回格式，在包 cn.chendapeng.springcloud.common.response 下定义两个类：
枚举 ResponseCode：
代码语言：javascript复制public enum ResponseCode {
/**
* 操作成功
*/
SUCCESS("00000", "操作成功"),
/**
* 系统内部异常
*/
INTERNAL_ERROR("B0001", "系统执行出错");
/**
* 状态码
*/
private final String code;
/**
* 提示信息
*/
private final String message;
ResponseCode(String code, String message) {
this.code = code;
this.message = message;
}
public String getCode() {
return code;
}
public String getMessage() {
return message;
}
}
该枚举类可以定义很多其他业务上的异常代码和异常信息。
统一返回类 ResponseResult：
代码语言：javascript复制package cn.chendapeng.springcloud.common.response;
import lombok.Data;
/**
* 统一返回结果
*
* 博客：https://chendapeng.cn - 行百里者半九十，做事要善始善终！
* 公众号：行百里er
*
* @author 行百里者
* @date 2022-08-16 16:49
*/
@Data
public class ResponseResult<T> {
/**
* 状态码
*/
private String code;
/**
* 提示信息
*/
private String message;
/**
* 返回数据
*/
private T data;
public ResponseResult() {
}
public ResponseResult(String code, String message) {
this.code = code;
this.message = message;
}
/**
* 操作成功的返回
* @param data 返回结果数据
* @param <T> 数据类型泛型
* @return 相应结果
*/
public static <T> ResponseResult<T> success(T data) {
ResponseResult<T> result = new ResponseResult<>();
result.setCode(ResponseCode.SUCCESS.getCode());
result.setMessage(ResponseCode.SUCCESS.getMessage());
result.setData(data);
return result;
}
/**
* 操作失败的返回
* @param code 状态码
* @param message 提示信息
* @param <T> 数据类型泛型
* @return 失败操作的返回结果
*/
public static <T> ResponseResult<T> fail(String code, String message) {
return new ResponseResult<>(code, message);
}
}
父工程定义子模块：
代码语言：javascript复制<modules>
<module>internal-common</module>
<module>nacos-provider</module>
<module>nacos-consumer</module>
<module>nacos-config</module>
<module>sentinel-service</module>
</modules>
在本篇文章demo的子工程 sentinel-service 中引入 internal-common ：
<!-- 引入二方库 -->
<dependency>
<groupId>cn.chendapeng.springcloud</groupId>
<artifactId>internal-common</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
OK，至此基础信息准备完毕，下面开始设置统一返回结果。
使用 Spring 的 「ResponseBodyAdvice」 类以及 「@RestControllerAdvice」 注解来完成接口的统一返回，在 sentinel-service 中新建一个全局返回的配置类：
package cn.chendapeng.springcloud.sentinelservice.response;
import cn.chendapeng.springcloud.common.response.ResponseResult;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;
/**
* 博客：https://chendapeng.cn - 行百里者半九十，做事要善始善终！
* 公众号：行百里er
*
* @author 行百里者
* @since 2020-01-16 16:55
*/
@RestControllerAdvice
public class ResponseAdvice implements ResponseBodyAdvice<Object> {
private ObjectMapper objectMapper;
/**
* 是否开启功能
* @param methodParameter 方法的参数
* @param aClass 类
* @return true：开启，false：不开启
*/
@Override
public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
return true;
}
/**
* 处理返回结果
* @param o 实例对象
* @param methodParameter 方法参数
* @param mediaType 媒体类别
* @param aClass 类对象
* @param request 请求
* @param response 相应
* @return 处理结果json
*/
@Override
public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest request, ServerHttpResponse response) {
//处理字符串类型数据
if (o instanceof String) {
try {
return objectMapper.writeValueAsString(ResponseResult.success(o));
} catch (JsonProcessingException e) {
e.printStackTrace();
}
}
//如果返回类型o已经封装成ResponseResult了，直接返回
if (o instanceof ResponseResult) {
return o;
}
return ResponseResult.success(o);
}
@Autowired
public void setObjectMapper(ObjectMapper objectMapper) {
this.objectMapper = objectMapper;
}
}
统一异常返回处理类 GlobalExceptionHandler ：
@RestControllerAdvice
public class GlobalExceptionHandler {
private static final Logger LOGGER = LoggerFactory.getLogger(GlobalExceptionHandler.class);
/**
* 未知的异常，统一处理
* @param e 异常对象
* @return ResponseResult全局异常响应
*/
@ExceptionHandler(Exception.class)
public ResponseResult<String> exception(Exception e) {
LOGGER.error("未知异常", e);
return ResponseResult.fail(ResponseCode.INTERNAL_ERROR.getCode(), ResponseCode.INTERNAL_ERROR.getMessage());
}
}
这个类里还可以增加其他自定义的业务异常处理。
此时，我们重启 sentinel-service 服务，调用 getProduct 测试：
限流生效
这样接口就有了统一返回的格式了。
另外，我们可以注意到，资源被限流后返回的信息也被如下方法截获：
代码语言：javascript复制@ExceptionHandler(Exception.class)
public ResponseResult<String> exception(Exception e) {
LOGGER.error("未知异常", e);
return ResponseResult.fail(ResponseCode.INTERNAL_ERROR.getCode(), ResponseCode.INTERNAL_ERROR.getMessage());
}
这里定义的是所有的异常都返回：
代码语言：javascript复制{
"code": "B0001",
"message": "系统执行出错",
"data": null
}
而资源被 Sentinel 限流就是返回一个 BlockException 异常，所以也就被我们定义的通用异常方法统一处理了。
@SentinelResource 注解之 blockHandler 和 fallback
blockHandler 和 blockHandlerClass
使用 blockHandler 处理限流逻辑
前面的返回：
代码语言：javascript复制{
"code": "B0001",
"message": "系统执行出错",
"data": null
}
虽然格式上没有问题，但是返回的结果语义太过笼统，这里我们可以使用注解 @SentinelResource 的 blockHandler 属性来自定义限流后的处理逻辑。
请求资源被 Sentinel 限流后，将会出现BlockException 异常， blockHandler 对应处理 BlockException 的函数名称。
「blockHandler 函数访问范围需要是 public，返回类型需要与原方法相匹配，参数类型需要和原方法相匹配并且最后加一个额外的参数，类型为 BlockException。blockHandler 函数默认需要和原方法在同一个类中。」
下面我们来增加一个 blockHandler 对应的处理方法：
@GetMapping("/getProduct")
@SentinelResource(value = "getProduct", blockHandler = "getProductBlockHandler")
public String getProduct(@RequestParam(value = "userId", required = false) Long userId,
@RequestParam(value = "productId", required = false) Long productId,
@RequestParam(value = "categoryId", required = false) Integer categoryId) {
log.info("getProduct param userId={},productId={},categoryId={}", userId, productId, categoryId);
return "getProduct success";
}
public String getProductBlockHandler(Long userId,
Long productId,
Integer categoryId,
BlockException blockException) {
return "热点参数 userId=" userId " 限流！";
}
然后在测试调用资源，结果如下：
返回BlockHandler结果
可以看到，将 getProductBlockHandler 处理结果返回了。
这样看还是感觉怪怪的，因为资源被限流了其实返回的是异常结果，这里希望最好给我返回个指定的 code 以及 message 。
再升级一下处理逻辑，首先定义限流返回码，在 internal-common 模块的 ResponseCode 枚举类增加：
/**
* 热点参数限流
*/
HOT_KEY_BLOCKED("B0002", "热点参数限流");
然后，自定义一个异常 HotKeyBlockedException ：
public class HotKeyBlockedException extends RuntimeException {
private Object hotKey;
public HotKeyBlockedException(Object hotKey) {
super("热点参数 [" hotKey "]限流！");
this.hotKey = hotKey;
}
public Object getHotKey() {
return hotKey;
}
}
在全局异常处理类 GlobalExceptionHandler 中增加：
/**
* 热点参数限流异常
* @param e 异常对象
* @return ResponseResult 全局异常响应
*/
@ExceptionHandler(HotKeyBlockedException.class)
public ResponseResult<String> hotKeyBlockedException(Exception e) {
LOGGER.error("热点参数限流", e);
return ResponseResult.fail(ResponseCode.HOT_KEY_BLOCKED.getCode(), ResponseCode.HOT_KEY_BLOCKED.getMessage());
}
最后，修改一下 getProductBlockHandler 方法：
public String getProductBlockHandler(Long userId,
Long productId,
Integer categoryId,
BlockException blockException) {
throw new HotKeyBlockedException(userId);
}
这样就可以返回想要的结果：
统一返回结果
使用 blockHandlerClass 将业务和限流处理方法解耦
通过前面的处理，其实我们可以发现，限流处理的方法和业务逻辑耦合在一起了，即处理方法就在业务逻辑本类中。
如果每个业务都增加一个自己的限流处理逻辑，那么类将会膨胀的难以维护，因此 @SentinelResource 除了 blockHandler 可以设置自定义限流处理逻辑方法以外，还提供另外一个属性来设置限流处理逻辑类型 blockHandlerClass 属性。
也就是说，如果我们希望使用其他类的函数来自定义限流处理，则可以指定 blockHandlerClass 为对应的类的 Class 对象。 Sentinel 规定对应的函数必需为 static 函数，否则无法解析。
继续上代码，只需将 getProductBlockHandler 移动到 HotKeyBlockedException 类中，并将其设为 static 的即可：
public class HotKeyBlockedException extends RuntimeException {
private Object hotKey;
public HotKeyBlockedException(Object hotKey) {
super("热点参数 [" hotKey "]限流！");
this.hotKey = hotKey;
}
public static String getProductBlockHandler(Long userId,
Long productId,
Integer categoryId,
BlockException blockException) {
throw new HotKeyBlockedException(userId);
}
public Object getHotKey() {
return hotKey;
}
}
然后在资源上这样定义：
代码语言：javascript复制@SentinelResource(value = "getProduct",
blockHandlerClass = HotKeyBlockedException.class,
blockHandler = "getProductBlockHandler")
这样就完成了限流处理逻辑与业务逻辑的解耦。
fallback
fallback 同 blockHandler 的使用方法及其相似，只是他们的本质不同：
- blockHandler：针对 Sentinel 配置的规则生效而产生 BlockException 异常时的对应处理；
- fallback：可以针对所有类型的异常（除了
exceptionsToIgnore里面排除掉的异常类型）进行处理。
若 blockHandler 和 fallback 都进行了配置，则被限流降级而抛出 BlockException 时只会进入 blockHandler 处理逻辑。若未配置 blockHandler、fallback ，则被限流降级时会将 BlockException 「直接抛出」。
由于 fallback 和 blockHandler 的用法是在太像了，这里就不列出代码了。完整代码见：https://github.com/ChenDapengJava/SpringCloudAlibabaDemo
小结
- 可以通过
@SentinelResource注解来定义资源，并使用其属性blockHandler和fallback自定义异常处理逻辑。 - 其中
blockHandler是针对限流熔断异常而设置的属性，fallback是针对所有异常的。 - 如果同时配置了
blockHandler和fallback属性，则被限流降级而抛出BlockException时只会进入blockHandler处理逻辑。 - 本文还提供了 Spring Boot 统一返回结果和全局异常处理的一种方法。
以上，本次导航结束。
