前言

我们访问接口进行限流或者降级后，直接返回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：

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：

package cn.chendapeng.springcloud.common.response;

import lombok.Data;

/**
 * 统一返回结果
 *
 * 
 *
 * @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);
    }
}

父工程定义子模块：

<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;

/**
 *
 * @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 测试：

这样接口就有了统一返回的格式了。

另外，我们可以注意到，资源被限流后返回的信息也被如下方法截获：

@ExceptionHandler(Exception.class)
public ResponseResult<String> exception(Exception e) {
    LOGGER.error("未知异常", e);
    return ResponseResult.fail(ResponseCode.INTERNAL_ERROR.getCode(), ResponseCode.INTERNAL_ERROR.getMessage());
}

这里定义的是所有的异常都返回：

{
    "code": "B0001",
    "message": "系统执行出错",
    "data": null
}

而资源被 Sentinel 限流就是返回一个 BlockException 异常，所以也就被我们定义的通用异常方法统一处理了。

@SentinelResource 注解之 blockHandler 和 fallback

blockHandler 和 blockHandlerClass

使用 blockHandler 处理限流逻辑

前面的返回：

{
    "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 + " 限流！";
}

然后在测试调用资源，结果如下：

可以看到，将 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;
    }
}

然后在资源上这样定义：

@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 的用法是在太像了，这里就不列出代码了。

小结

• 可以通过 @SentinelResource 注解来定义资源，并使用其属性 blockHandler 和 fallback 自定义异常处理逻辑。
• 其中 blockHandler 是针对限流熔断异常而设置的属性，fallback 是针对所有异常的。
• 如果同时配置了 blockHandler 和 fallback 属性，则被限流降级而抛出 BlockException 时只会进入 blockHandler 处理逻辑。