一、前提:微服务为什么会雪崩

1.1 从单体到微服务,我们换来了什么

单体应用把所有业务模块、数据访问逻辑打包进一个进程(一个 Jar 包、一个 Node 进程),共享同一套数据库和服务器。它的优缺点非常直白:

单体架构

微服务架构

开发

简单,本地一把梭

需要注册中心、配置中心、网关等基础设施

部署

一次打包一次发布

每个服务独立发布,需要编排与灰度

扩展

整体扩容,粒度粗

按服务扩容,粒度细

技术栈

锁定

异构(Java / Go / Rust 共存)

故障域

一个进程挂了全站挂

服务间依赖复杂,故障易扩散

通信开销

无

网络延迟、序列化、超时、一致性

微服务把"一个问题"换成了"一类问题":依赖变多之后,任何一个下游抖动,都会沿着调用链向上传播。

1.2 雪崩是怎么发生的

微服务调用链路中的某个服务故障,引起整个链路中的所有微服务都不可用,这就是雪崩。

典型链路:用户请求 → 订单服务(order-service) → 用户服务(user-service) → 数据库

      ┌──────────┐        ┌──────────┐        ┌──────────┐
      │  Gateway │───────▶│  order   │───────▶│   user   │──▶ DB
      └──────────┘        └──────────┘        └──────────┘
                                 ▲                     │
                                 └──── 线程全在等待 ────┘

user-service 因为慢 SQL 导致 RT 从 20ms 涨到 3s,order-service 的 Tomcat 线程池(默认 200)里的线程全部阻塞在等待响应上,很快就没有线程能处理新请求,order-service 随之不可用;上游网关、前端继续重试,整条链路彻底瘫痪。一个慢查询,打挂一整片。

1.3 四种服务保护手段

手段

思路

解决什么

Sentinel 是否支持

超时处理

超过设定时间没响应就返回错误,不再无休止等待

释放线程资源

✅(需配合 HTTP 客户端超时)

线程隔离(舱壁模式)

模拟船舱隔板,限定每个业务能使用的线程数

故障业务不耗尽整个容器的线程

✅(信号量隔离机制)

服务熔断

断路器统计异常比例 / 慢调用比例,超阈值则熔断,拦截一切请求

下游已死时快速失败,不再拖累调用方

✅

流量控制

限制业务访问的 QPS,避免流量激增打垮服务

突发流量(秒杀、爬虫、压测)

✅

一句话总结四者的关系:限流是预防(别让这么多请求进来),隔离是止损(故障别扩散),熔断是快速失败(下游都死了就别调了),超时是底线(无论如何别一直等)。

二、初识 Sentinel

2.1 定位与特性

Sentinel 是阿里巴巴开源的分布式系统流量治理组件,核心定位是流量防卫兵。它以流量为切入点,覆盖:

  • 流量控制(QPS / 并发线程数)
  • 流量整形(预热、匀速排队)
  • 熔断降级(慢调用比例、异常比例、异常数)
  • 热点参数防护(按参数值维度限流)
  • 系统自适应保护(LOAD、CPU、RT、总 QPS)
  • 授权控制(来源白 / 黑名单)

它承接了阿里近十年双十一大促的核心场景:秒杀削峰、消息削峰填谷、集群流控、实时熔断下游不可用应用。

官网:home | Sentinel

源码:https://github.com/alibaba/Sentinel

2.2 三个核心概念

理解 Sentinel 只需要抓住三个词:

概念

说明

例子

资源

(Resource)

被保护的对象,任何一段逻辑都可以是资源

一个 Controller 接口 /order/{orderId}、一个 @SentinelResource("queryGoods")方法、一段 SphU.entry()包裹的代码

规则 (Rule)

定义在资源上的约束

FlowRule、DegradeRule、ParamFlowRule、SystemRule、AuthorityRule

Entry

一次请求进入资源的凭证, entry.exit()时统计

SphU.entry("resourceName")

2.3 一次请求内部的 Slot Chain

Sentinel 的所有判断都在本地 JVM 内完成(控制台(dashboard)不参与请求决策,它只是规则管理端 + 监控展示端),核心是一条责任链:

NodeSelectorSlot      建立调用链路树(区分不同入口)
   ↓
ClusterBuilderSlot    统计集群维度指标
   ↓
LogSlot               记录被拦截日志
   ↓
StatisticSlot         滑动窗口统计(QPS、RT、线程数、异常数)
   ↓
AuthoritySlot         授权规则(来源黑白名单)
   ↓
SystemSlot            系统自适应保护(LOAD / CPU / RT / 总QPS)
   ↓
FlowSlot              流量控制(QPS / 线程数)
   ↓
DegradeSlot           熔断降级(慢调用 / 异常比例 / 异常数)
   ↓
ParamFlowSlot         热点参数限流

统计用的是滑动窗口(LeapArray),不是简单的计数器,这也是 Sentinel 能在一秒内平滑统计而不出现边界突刺的原因。

2.4 与 Hystrix / Resilience4j 的差异

维度

Sentinel

Hystrix

Resilience4j

维护状态

活跃(1.8.10)

停止维护

活跃

隔离策略

信号量(默认),支持并发线程数控制

线程池 / 信号量

信号量

熔断策略

慢调用比例 / 异常比例 / 异常数

异常比例

异常比例 / 慢调用

限流

原生支持 QPS、集群流控、热点参数

无

RateLimiter(简单)

规则配置

控制台 + 动态数据源(Nacos 等)

代码 / 配置

代码 / 配置

实时监控

控制台秒级监控

Dashboard / Turbine

Micrometer

生态

Spring Cloud Alibaba、Dubbo、gRPC、Gateway

Netflix 全家桶

Spring Cloud CircuitBreaker

关于线程池隔离的一个常见误解:很多教程(包括不少课件)会把"线程池隔离"作为 Sentinel 的能力来讲,实际上 Sentinel 主推的是信号量隔离——不创建额外线程,直接用处理请求的线程去调用依赖,通过计数器限制并发数。线程池隔离是 Hystrix 的经典做法,它带来额外线程开销与上下文切换,优势是能主动超时和异步化。Sentinel 里的线程数阈值类型,本质就是信号量隔离。 如果你确实需要线程池隔离,得自己在业务层用线程池包一层。

三、环境与版本选型

3.1 版本对应关系

Spring Cloud Alibaba 各分支与组件版本(摘自官方版本说明):

SCA 版本

Spring Cloud

Spring Boot

Sentinel

2023.0.1.0

2023.0.1

3.2.4

1.8.6

2022.0.0.0

2022.0.0

3.0.2

1.8.6

2021.0.6.0

2021.0.5

2.6.13

1.8.6

2.2.9.RELEASE

Hoxton.SR12

2.3.x

1.8.5

选型建议:新项目直接上 Boot 3.2 + SCA 2023.0.1.0(JDK 17);老项目在 2021.x 分支上继续演进。Sentinel 客户端版本由 SCA 托管,不要单独升级 sentinel-core,否则容易与适配器版本打架。

3.2 启动 Sentinel 控制台

控制台是一个独立 Spring Boot 应用(sentinel-dashboard.jar),只需要 JDK 8+:

# 下载(以 1.8.10 为例,建议与客户端 1.8.x 保持一致)
wget https://github.com/alibaba/Sentinel/releases/download/1.8.10/sentinel-dashboard-1.8.10.jar

# 启动:改端口、改账号密码、把自己也注册进监控
java -Dserver.port=8858 \
     -Dcsp.sentinel.dashboard.server=localhost:8858 \
     -Dproject.name=sentinel-dashboard \
     -Dsentinel.dashboard.auth.username=sentinel \
     -Dsentinel.dashboard.auth.password=sentinel \
     -jar sentinel-dashboard-1.8.10.jar

也可以直接用 Docker:

docker run -d --name sentinel-dashboard \
  -p 8858:8858 \
  bladex/sentinel-dashboard:1.8.9

启动成功后,访问 http://localhost:8858,默认账号密码均为 sentinel。

注意:

  • 控制台不存储任何规则到磁盘(社区版默认走内存,不能实现规则的持久化),重启控制台 → 客户端内存里的规则还在,但控制台页面上看不到历史规则;重启客户端 → 规则全丢。这就是第 10 章要解决的事。
  • 控制台本身也占用一个端口向客户端推送规则,客户端另起一个 8719(可配置)端口与控制台通信,多实例部署时该端口会自动递增,若在容器中运行需要把这段端口范围也映射出来。
  • 控制台与客户端通过 HTTP 心跳维持"机器列表",机器时间不同步会导致监控数据异常。

四、快速接入:依赖、控制台、簇点链路

4.1 依赖

<!-- pom.xml 关键片段 -->
<properties>
    <java.version>17</java.version>
    <spring-boot.version>3.2.4</spring-boot.version>
    <spring-cloud.version>2023.0.1</spring-cloud.version>
    <spring-cloud-alibaba.version>2023.0.1.0</spring-cloud-alibaba.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring-boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>${spring-cloud-alibaba.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- 服务发现(可选,本文示例用它做 Feign 调用) -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    </dependency>

    <!-- Sentinel 核心 starter:含 webmvc 适配器 + 注解支持 + transport -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
    </dependency>

    <!-- 规则持久化到 Nacos(第 10 章用) -->
    <dependency>
        <groupId>com.alibaba.csp</groupId>
        <artifactId>sentinel-datasource-nacos</artifactId>
    </dependency>

    <!-- 热点参数限流能力(1.8.x 中 starter 未默认传递,显式声明更稳) -->
    <dependency>
        <groupId>com.alibaba.csp</groupId>
        <artifactId>sentinel-parameter-flow-control</artifactId>
    </dependency>
</dependencies>

4.2 配置

# application.yml
server:
  port: 8081

spring:
  application:
    name: order-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
    sentinel:
      # 关闭懒加载:启动即向控制台注册,不用等第一次请求
      eager: true
      transport:
        # 控制台地址
        dashboard: 127.0.0.1:8858
        # 本应用与控制台通信的端口(默认 8719,多实例会自动 +1)
        port: 8720
      # 资源名是否带 HTTP 方法前缀:false → /order/{id};true → GET:/order/{id}
      http-method-specify: false
      # 关闭 Web 上下文聚合:使用"链路"流控模式时必须设为 false
      web-context-unify: false
      # 过滤掉管理端点,避免监控噪音
      filter:
        enabled: true

4.3 快速入门示例

@RestController
@RequestMapping("/order")
@RequiredArgsConstructor
@Slf4j
public class OrderController {

    private final OrderService orderService;
    private final UserClient userClient;

    /** 订单详情:会远程调用 user-service 查询下单人 */
    @GetMapping("/{orderId}")
    public OrderVO detail(@PathVariable("orderId") Long orderId) {
        OrderVO vo = new OrderVO();
        vo.setOrderId(orderId);
        vo.setUser(userClient.findById(orderId));
        return vo;
    }

    /** 查询订单(第 5 章"关联模式"用它做低优先级资源) */
    @GetMapping("/query")
    public String query() {
        orderService.queryGoods();
        return "查询订单成功";
    }

    /** 更新订单(第 5 章"关联模式"用它做高优先级资源) */
    @PostMapping("/update")
    public String update() {
        return "更新订单成功";
    }

    /** 创建订单(第 5 章"链路模式"的第二个入口) */
    @PostMapping("/save")
    public String save() {
        orderService.queryGoods();
        return "创建订单成功";
    }
}

4.4 簇点链路与懒加载

簇点链路:

就是项目内的调用链路,链路中被监控的每个接口就是一个资源。默认情况下sentinel 会监控 SpringMVC 的每一个端点(Endpoint),因此 SpringMVC 的每一个端点(Endpoint)就是调用链路中的一个资源。

启动应用后访问一次 http://localhost:8081/order/101,再打开控制台,就能在左侧看到 order-service,点开"簇点链路"能看到所有被监控的资源。

流控、熔断等都是针对簇点链路中的资源来设置的,因此我们可以点击对应资源后面的按钮来设置规则:

注意:控制台看不到我的应用?

Sentinel 客户端默认懒加载——只有第一次访问任意端点后才会初始化并向控制台注册。加上 spring.cloud.sentinel.eager=true 可解决。如果仍看不到,按顺序排查:① 控制台与客户端版本是否同一大版本;② 客户端 8719 端口是否被占用或被容器网络拦住;③ 服务器时间是否同步;④ 应用日志里搜 sentinel 关键字看 transport 是否报错。

五、流量控制:三种模式、三种效果、两种阈值

一条流控规则(FlowRule)由三部分决定:统计什么(阈值类型 + 模式)、阈值多少、超了怎么办(效果)。

5.1 两种阈值类型

阈值类型

常量

含义

适用场景

QPS

FLOW_GRADE_QPS = 1

每秒请求数

绝大多数场景,保护"吞吐量"

线程数

FLOW_GRADE_THREAD = 0

该资源能同时使用的业务线程数最大值

保护"并发",即舱壁模式(信号量隔离)

线程数阈值的含义:限制同一时刻有多少个线程在处理这个资源。注意它限制的是同时在处理的线程数,不是累计通过数——线程释放后新请求立即可以进,所以压测报告里累计通过数会远大于阈值,这是正常现象。

5.2 三种流控模式

模式

常量

说明

直接

STRATEGY_DIRECT = 0

(默认)

统计当前资源自身的请求,超阈值直接限流当前资源

关联

STRATEGY_RELATE = 1

统计关联资源的请求,关联资源超阈值时,限流当前资源

链路

STRATEGY_CHAIN = 2

只统计从指定入口访问到本资源的请求,超阈值时对该入口限流

案例 A:关联模式(读让位于写)

场景:用户支付要修改订单状态(`/order/update`),同时用户在查订单(`/order/query`),两者争抢数据库行锁。业务上支付优先,所以当写接口压力大时,主动把读接口限流掉。

控制台配置:对资源 `/order/query` 新增流控规则 → 流控模式选"关联" → 关联资源填 `/order/update` → 阈值类型 QPS → 阈值 5。

含义是:当 `/order/update` 的 QPS 超过 5 时,对 `/order/query` 限流。

等价的 Java 代码:

@PostConstruct
public void initRelateFlowRule() {
    FlowRule rule = new FlowRule("/order/query")   // 被限流的是 query
            .setGrade(RuleConstant.FLOW_GRADE_QPS)
            .setCount(5)
            .setStrategy(RuleConstant.STRATEGY_RELATE)
            .setRefResource("/order/update");      // 统计的是 update
    FlowRuleManager.loadRules(Collections.singletonList(rule));
}

适用条件小结:① 两个资源存在竞争关系(争抢同一把锁 / 同一个连接池);② 两者优先级不同,需要牺牲低优先级的那个。

案例 B:链路模式(只掐一条调用链)

场景:查询订单和创建订单都要调用 queryGoods(),但我们只想限制"从查询订单进来"的那部分调用,避免影响创建订单。

@Service
public class OrderService {

    // 注意:必须用 @SentinelResource 标记,Sentinel 默认只把 Controller 端点当资源
    @SentinelResource(value = "queryGoods",
                      blockHandler = "queryGoodsBlockHandler",
                      fallback = "queryGoodsFallback")
    public String queryGoods() {
        return "商品列表";
    }

    /** 处理限流/熔断(BlockException),方法签名要求:参数与原方法一致 + BlockException */
    public String queryGoodsBlockHandler(BlockException e) {
        return "商品查询被限流,请稍后再试";
    }
    
       /** 处理业务异常(Throwable),参数与原方法一致 + Throwable */
    public String queryGoodsFallback(Throwable t) {
        return "商品查询失败,已降级";
    }
}

规则配置(入口为 /order/query):

FlowRule rule = new FlowRule("queryGoods")
        .setGrade(RuleConstant.FLOW_GRADE_QPS)
        .setCount(2)
        .setStrategy(RuleConstant.STRATEGY_CHAIN)   // 链路模式
        .setRefResource("/order/query");            // 入口资源
FlowRuleManager.loadRules(Collections.singletonList(rule));

注意:链路模式配了不生效?

两个必要条件:① 被保护的方法必须被 @SentinelResource 标记(否则它不是资源);② 配置文件加 spring.cloud.sentinel.web-context-unify: false。默认情况下 Sentinel 会把所有 Web 请求的 context 统一成同一个(sentinel_spring_web_context),链路入口信息丢失,STRATEGY_CHAIN 就永远匹配不上。

5.3 三种流控效果

效果

常量

行为

适用

快速失败

CONTROL_BEHAVIOR_DEFAULT = 0

(默认)

超阈值立即抛 FlowException

绝大多数在线接口

Warm Up(预热)

CONTROL_BEHAVIOR_WARM_UP = 1

阈值从 count/coldFactor

动态爬升到 count

冷启动、缓存未预热、秒杀开场

排队等待

CONTROL_BEHAVIOR_RATE_LIMITER = 2

请求排队匀速通过,等待超时则拒绝

削峰填谷、异步任务、下游扛不住瞬时并发

Warm Up 原理

coldFactor 冷启动因子默认 3。设最大阈值 count = 10,预热时长 warmUpPeriodSec = 5,则初始阈值为 10 / 3 ≈ 3,在 5 秒内平滑增长到 10。底层是令牌桶 + 冷却因子,防止"刚启动的服务一上来就被打死"(此时连接池、JIT、缓存都还没热)。

这里 初始阈值 = 最大阈值 / 冷启动因子

FlowRule rule = new FlowRule("GET:/seckill/{goodsId}")
        .setGrade(RuleConstant.FLOW_GRADE_QPS)
        .setCount(10)
        .setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_WARM_UP)
        .setWarmUpPeriodSec(5);

排队等待原理

设 QPS = 5,即每 1000 / 5 = 200ms 放行一个请求;maxQueueingTimeMs = 2000 表示预计等待时间超过 2s 的请求直接拒绝。它的本质是漏桶(匀速通过),起到流量整形作用:把一波尖峰拉成一条平线,代价是响应时间变长。

FlowRule rule = new FlowRule("/order/{orderId}")
        .setGrade(RuleConstant.FLOW_GRADE_QPS)
        .setCount(5)
        .setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_RATE_LIMITER)
        .setMaxQueueingTimeMs(2000);

排队等待模式下超时抛的依然是 FlowException,但语义是"排队等不到位置"。注意它只对 QPS 阈值类型生效,线程数阈值类型下用不了。

5.4 用编程式 API 保护任意代码块

除了 Controller 端点和 @SentinelResource,任何一段逻辑都可以显式保护:

public OrderVO createOrder(CreateOrderCmd cmd) {
    Entry entry = null;
    try {
        entry = SphU.entry("createOrder");
        // ===== 业务逻辑 =====
        return doCreate(cmd);
    } catch (BlockException e) {
        // 被限流/熔断/系统保护
        return OrderVO.blocked("当前下单人数过多,请稍后再试");
    } catch (Throwable t) {
        // 关键:业务异常要上报给 Sentinel,否则异常比例/异常数统计不到
        Tracer.trace(t);
        throw t;
    } finally {
        if (entry != null) {
            entry.exit();
        }
    }
}

注意:

  1. entry.exit() 必须执行,否则统计窗口里的"占用"永远不释放;
  2. 业务异常必须 Tracer.trace(t),否则熔断的"异常比例 / 异常数"策略永远触发不了;
  3. 需要按参数维度限流时,用 SphU.entry("resource", EntryType.IN, 1, args) 把参数传进去(热点参数限流的数据来源)。

5.5 系统自适应保护(容易被忽略的一层)

除了按资源限流,Sentinel 还能按整机负载兜底,防止"每个接口都没超阈值,但机器已经跪了":

List<SystemRule> rules = new ArrayList<>();
SystemRule rule = new SystemRule();
rule.setHighestSystemLoad(4.0);      // LOAD 超过 4 触发(仅 Linux 生效)
rule.setAvgRt(200);                  // 所有入口平均 RT 超过 200ms
rule.setMaxThread(500);              // 总并发线程数上限
rule.setQps(3000);                   // 所有入口总 QPS 上限
rule.setHighestCpuUsage(0.85);       // CPU 使用率 85%
rules.add(rule);
SystemRuleManager.loadRules(rules);

触发后抛 SystemBlockException。生产建议至少配置 highestSystemLoad + highestCpuUsage 作为最后一道防线。

六、热点参数限流:把 QPS 精细到参数值

6.1 它解决了什么问题

普通限流统计的是"访问某个资源的所有请求"。热点参数限流统计的是"参数值相同的请求":

  • 普通限流:/product/{productId} 整体 QPS ≤ 100
  • 热点限流:productId = 8888(爆款商品)单独 QPS ≤ 10,其他商品仍走通用阈值

这在商品详情、热门帖子、大 V 主页这类访问极度倾斜的场景非常关键——你不能因为一个爆款把全站商品都限了,也不能为了保爆款把阈值调到所有商品都失控。

6.2 配置与例外项

控制台:簇点链路 → 资源 hotProduct → 热点规则 → 参数索引 0(第一个参数)→ 单机阈值 5 → 统计窗口 1s。

高级选项里可以加例外项:

参数值

类型

限流阈值

100

long

10

101

long

15

含义:0 号参数默认每 1 秒相同值不超过 5 次;但参数值为 100 时放宽到 10,为 101 时放宽到 15。

6.3 代码案例

@RestController
@RequestMapping("/product")
@RequiredArgsConstructor
public class ProductController {

    private final ProductService productService;

    /**
     * 注意:热点参数限流对 Spring MVC 默认的端点资源(/product/{productId})无效,
     * 必须自己用 @SentinelResource 定义资源名并让参数进入 Sentinel 上下文。
     */
    @GetMapping("/{productId}")
    @SentinelResource(value = "hotProduct",
                      blockHandler = "hotProductBlockHandler",
                      fallback = "hotProductFallback")
    public ProductVO detail(@PathVariable("productId") Long productId) {
        return productService.detail(productId);
    }

    public ProductVO hotProductBlockHandler(Long productId, BlockException e) {
        return ProductVO.blocked(productId, "该商品访问过热,请稍后再试");
    }

    public ProductVO hotProductFallback(Long productId, Throwable t) {
        return ProductVO.blocked(productId, "商品信息暂时不可用");
    }
}

对应的硬编码规则(默认阈值 2,id=2 放宽到 4,id=3 放宽到 10):

@PostConstruct
public void initParamFlowRule() {
    ParamFlowRule rule = new ParamFlowRule("hotProduct")
            .setParamIdx(0)        // 第 1 个参数,即 productId
            .setGrade(RuleConstant.FLOW_GRADE_QPS)
            .setCount(2)           // 默认:相同参数值每秒最多 2 次
            .setDurationInSec(1);  // 统计窗口 1 秒

    // 例外项:热点商品单独放宽
    ParamFlowItem item2 = new ParamFlowItem()
            .setObject(String.valueOf(2))
            .setClassType(Long.class.getName())
            .setCount(4);
    ParamFlowItem item3 = new ParamFlowItem()
            .setObject(String.valueOf(3))
            .setClassType(Long.class.getName())
            .setCount(10);
    rule.setParamFlowItemList(Arrays.asList(item2, item3));

    ParamFlowRuleManager.loadRules(Collections.singletonList(rule));
}

注意:热点规则配了没反应?

① 热点参数限流对默认的 Spring MVC 资源无效——Web 适配器不会把方法参数传进 SphU.entry,ParamFlowSlot 取不到参数值,规则自然不触发。必须用 @SentinelResource 或编程式 SphU.entry(name, type, count, args)。

② setClassType 必须是参数值的包装类型全限定名(java.lang.Long),写 long 或写错类型,例外项不会匹配。

③ 参数值在例外项里是以 String 形式比较的,setObject("2") 而不是 setObject(2L)。

6.4 关于 @SentinelResource 的两个补充

  • blockHandler 处理 BlockException(限流、熔断、系统保护、授权),fallback 处理业务异常。两者可以同时配,优先级:block 走 blockHandler,业务异常走 fallback。
  • blockHandler / fallback 方法必须与原方法在同一个类中(或用 blockHandlerClass 指定外部类,且方法必须是 public static),参数列表要包含原方法的全部参数,返回值一致。
  • 在 Controller 方法上同时加 @SentinelResource 时,一次请求会经过两层保护:先过 Web 拦截器(资源名是 URL 路径),再过注解切面(资源名是注解值)。两者都会累加统计,别被控制台上两个资源名搞混。

七、隔离与降级:舱壁模式与熔断

7.1 先厘清保护对象

限流解决"外部流量太大",隔离与降级解决"下游已经出问题"。无论是线程隔离还是熔断降级,都是对客户端(调用方)的保护——是在 order-service 侧做,不是在 user-service 侧做。

7.2 信号量隔离 vs 线程池隔离

维度

信号量隔离(Sentinel 默认)

线程池隔离(Hystrix 经典做法)

实现

计数器,超并发直接拒绝

每个依赖一个线程池,任务提交到池里跑

线程开销

无额外线程

每个依赖 N 个线程 + 队列,开销大

主动超时

不支持,依赖 HTTP 客户端超时

支持,超时后线程可中断

异步调用

不支持

支持(请求线程与执行线程分离)

适用

高扇出(一个服务调很多下游)、常规 RPC

低扇出、需要超时中断或异步编排的场景

扇出(fan-out)指一个服务直接调用的下游服务数量。扇出很高时,线程池方案会因为线程总数爆炸而不可行,这也是 Sentinel 选择信号量的核心原因。

结论:Sentinel 的“线程数"阈值 = 信号量隔离。控制台上给 Feign 调用资源配一个"线程数 = 10"的流控规则,就是标准的舱壁模式。

7.3 Feign 整合 Sentinel

Spring Cloud 里微服务调用基本走 OpenFeign,所以客户端保护必须整合 Feign + Sentinel。

第一步:开启开关(注意版本差异)

# Spring Cloud Alibaba 2021.x / Spring Boot 2.x 分支
feign:
  sentinel:
    enabled: true
# Spring Cloud Alibaba 2022.x / 2023.x / Spring Boot 3.x 分支
# 该分支 OpenFeign 已统一到 Spring Cloud CircuitBreaker 抽象
spring:
  cloud:
    openfeign:
      circuitbreaker:
        enabled: true
feign:
  circuitbreaker:
    enabled: true

注意:Feign 降级不生效?

① 两套熔断机制不要同时开——Sentinel 适配挂在 InvocationHandler 层,CircuitBreaker 挂在 Targeter 层,同时开会互相干扰;

② fallback 类必须被 Spring 管理(@Component 或 @Bean),且包路径在扫描范围内;

③ 不同 SCA 分支的开关项名称不一样,升级到 Boot 3 后 feign.sentinel.enabled 不再有效。

第二步:编写 FallbackFactory(推荐,能拿到异常)

fallback(FallbackClass)只能返回兜底数据,拿不到异常;fallbackFactory 可以拿到 Throwable,便于记录日志和区分处理。

@FeignClient(name = "user-service", fallbackFactory = UserClientFallbackFactory.class)
public interface UserClient {

    @GetMapping("/user/{id}")
    UserDTO findById(@PathVariable("id") Long id);
}
@Slf4j
@Component
public class UserClientFallbackFactory implements FallbackFactory<UserClient> {

    @Override
    public UserClient create(Throwable cause) {
        return new UserClient() {
            @Override
            public UserDTO findById(Long id) {
                // 关键:把异常打出来,否则线上"静默降级"最难排查
                log.error("查询用户失败, userId={}, cause={}", id, cause.toString(), cause);

                // 根据异常类型区分处理
                if (cause instanceof DegradeException) {
                    log.warn("user-service 已熔断,走本地兜底, userId={}", id);
                }

                // 返回业务可接受的默认值,而不是 null
                UserDTO fallback = new UserDTO();
                fallback.setId(id);
                fallback.setNickname("默认用户");
                return fallback;
            }
        };
    }
}

第三步:确认资源名

Feign 调用在 Sentinel 里的默认资源名格式为 GET:http://user-service/user/{id}(HTTP方法:服务名+路径)。给这个资源配"线程数"阈值就是舱壁隔离,配熔断规则就是熔断降级。

7.4 熔断降级:三种策略 + 状态机

Sentinel 的熔断由断路器(CircuitBreaker)实现,三种策略:

策略

常量

判断依据

典型配置

慢调用比例

DEGRADE_GRADE_RT = 0

CircuitBreakerStrategy.SLOW_REQUEST_RATIO

RT 超过阈值的请求占比

RT > 500ms 记为慢调用,1s 内请求 ≥ 10 且慢调用比例 ≥ 0.5 → 熔断 5s

异常比例

DEGRADE_GRADE_EXCEPTION_RATIO = 1

ERROR_RATIO

异常数 / 总请求数

1s 内请求 ≥ 10 且异常比例 ≥ 0.5 → 熔断 5s

异常数

DEGRADE_GRADE_EXCEPTION_COUNT = 2

ERROR_COUNT

统计窗口内异常绝对数

1min 内异常数 ≥ 5 → 熔断 5s

状态机:

        ┌──────────── 探测成功 ────────────┐
        │                                 ▼
   [CLOSED] ── 达到熔断条件 ──▶ [OPEN] ── 熔断时长到 ──▶ [HALF_OPEN]
        ▲                                                   │
        └────────────────── 探测失败(再次 OPEN)─────────────┘
  • CLOSED:正常放行,持续统计;
  • OPEN:timeWindow 秒内拦截一切请求,直接抛 DegradeException;
  • HALF_OPEN:熔断时长结束后放行一次探测请求,成功则回到 CLOSED,失败则立刻回到 OPEN 再等一个 timeWindow。

案例 A:慢调用熔断

需求:查询用户接口,RT 阈值 50ms,统计时长 1s,最小请求数 5,慢调用比例阈值 0.4,熔断时长 5s。

@PostConstruct
public void initSlowRequestDegradeRule() {
    DegradeRule rule = new DegradeRule("GET:http://user-service/user/{id}")
            // 慢调用比例策略
            .setGrade(CircuitBreakerStrategy.SLOW_REQUEST_RATIO.getType())
            .setCount(50)                 // RT 阈值:50ms,超过即记为慢调用
            .setSlowRatioThreshold(0.4)   // 慢调用比例阈值 0.4
            .setStatIntervalMs(1000)      // 统计时长 1s
            .setMinRequestAmount(5)       // 最小请求数 5(低于此值不熔断)
            .setTimeWindow(5);            // 熔断时长 5s
    DegradeRuleManager.loadRules(Collections.singletonList(rule));
}

为了本地验证,给下游人为注入延迟:

@GetMapping("/user/{id}")
public UserDTO findById(@PathVariable("id") Long id) {
    if (id == 1) {
        try { TimeUnit.MILLISECONDS.sleep(60); }   // 制造慢调用
        catch (InterruptedException ignored) {}
    }
    return userService.findById(id);
}

验证效果:连续请求 id=1 触发熔断后,后续请求 RT 骤降(不再查库、不再发起调用),直接返回降级结果。

案例 B:异常比例熔断

DegradeRule rule = new DegradeRule("GET:http://user-service/user/{id}")
        .setGrade(CircuitBreakerStrategy.ERROR_RATIO.getType())
        .setCount(0.4)                // 异常比例阈值 0.4(注意是比例,取值 0~1)
        .setStatIntervalMs(1000)
        .setMinRequestAmount(5)
        .setTimeWindow(5);
@GetMapping("/user/{id}")
public UserDTO findById(@PathVariable("id") Long id) {
    if (id == 2) {
        throw new RuntimeException("模拟异常");  // 会被 Tracer 统计为异常
    }
    return userService.findById(id);
}

注意:异常比例策略一直不触发?

Sentinel 只统计被 Tracer.trace() 记录的异常。用 @SentinelResource 或 Feign 适配时框架会自动 trace;如果是自己写的 SphU.entry(),必须在 catch 里手动 Tracer.trace(t)。另外,被全局 @ControllerAdvice 吞掉的异常,如果没经过 Sentinel 的资源边界,也统计不到。

7.5 线程隔离(舱壁模式)实操

给 Feign 资源配"线程数"阈值:簇点链路 → GET:http://user-service/user/{id} → 流控 → 阈值类型选线程数 → 阈值 2。

FlowRule rule = new FlowRule("GET:http://user-service/user/{id}")
        .setGrade(RuleConstant.FLOW_GRADE_THREAD)  // 0 = 线程数
        .setCount(2);                              // 最多 2 个线程并发调用
FlowRuleManager.loadRules(Collections.singletonList(rule));

压测时会看到一个"反直觉"的现象:累计通过数远超 2。这是正常的——线程数限制的是"同时占用",线程一释放新请求就能进;它保证的是"调用 user-service 的并发永远不超过 2",从而不会把整个 order-service 的线程池拖垮。

八、授权规则:只让网关进来的请求访问

8.1 白名单 / 黑名单

授权规则按调用方来源(origin)做控制:

  • 白名单:origin 在名单内才允许访问(AUTHORITY_WHITE = 0)
  • 黑名单:origin 在名单内的拒绝访问(AUTHORITY_BLACK = 1)

典型场景:订单服务只允许从网关进来的请求访问,内部直接调用或被绕过的请求一律拒绝。

8.2 定义来源解析

Sentinel 通过 RequestOriginParser 的 parseOrigin() 获取来源:

@Component
public class HeaderOriginParser implements RequestOriginParser {

    private static final String ORIGIN_HEADER = "origin";

    @Override
    public String parseOrigin(HttpServletRequest request) {
        String origin = request.getHeader(ORIGIN_HEADER);
        // 不要返回 null,否则授权规则无法匹配,统一给个名字
        return StringUtils.hasText(origin) ? origin : "blank";
    }
}

Spring Boot 3 用户注意包路径:

Boot 3(jakarta)项目请用com.alibaba.csp.sentinel.adapter.spring.webmvc_v6x.callback.RequestOriginParser;

Boot 2(javax)项目用com.alibaba.csp.sentinel.adapter.spring.webmvc.callback.RequestOriginParser。

8.3 网关侧添加来源头

spring:
  cloud:
    gateway:
      routes:
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/order/**
          filters:
            - AddRequestHeader=origin,gateway    # 关键:打上来源标识
      default-filters:
        - AddRequestHeader=origin,gateway        # 或全局统一加

硬编码等价写法:

AuthorityRule rule = new AuthorityRule();
rule.setResource("/order/{orderId}");
rule.setStrategy(RuleConstant.AUTHORITY_WHITE);   // 白名单
rule.setLimitApp("gateway");                      // 多个来源用逗号分隔
AuthorityRuleManager.loadRules(Collections.singletonList(rule));

安全提醒:origin 头是明文 HTTP 头,只能防君子(防误调用、防内部绕行),不能当鉴权用。外部攻击者可以自己伪造该头。真正的鉴权要放在网关的认证过滤器 + JWT/OAuth2 上,授权规则只是"来源治理"的补充。

九、自定义异常返回:统一限流后的响应体

默认情况下,限流、降级、授权拦截都会把 BlockException 抛给调用方,页面看到的是一句 Blocked by Sentinel (flow limiting) 和 HTTP 429。前端显然没法用,需要统一成项目约定的 JSON。

9.1 BlockException 的子类

异常

触发场景

FlowException

限流(含预热、排队等待超时)

ParamFlowException

热点参数限流

DegradeException

熔断降级

AuthorityException

授权规则拦截(黑白名单)

SystemBlockException

系统自适应保护

9.2 实现 BlockExceptionHandler

@Component
public class GlobalBlockExceptionHandler implements BlockExceptionHandler {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public void handle(HttpServletRequest request,
                       HttpServletResponse response,
                       String resourceName,
                       BlockException e) throws Exception {

        String msg;
        int code;
        if (e instanceof FlowException) {
            msg = "请求过于频繁,请稍后再试";
            code = 429;
        } else if (e instanceof ParamFlowException) {
            msg = "热点数据访问过于频繁,请稍后再试";
            code = 429;
        } else if (e instanceof DegradeException) {
            msg = "服务已降级,正在恢复中";
            code = 503;
        } else if (e instanceof AuthorityException) {
            msg = "无访问权限";
            code = 403;
        } else if (e instanceof SystemBlockException) {
            msg = "系统负载过高,请稍后再试";
            code = 503;
        } else {
            msg = "访问被拒绝";
            code = 429;
        }

        response.setStatus(code);
        response.setCharacterEncoding(StandardCharsets.UTF_8.name());
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);

        Map<String, Object> body = new LinkedHashMap<>();
        body.put("code", code);
        body.put("msg", msg);
        body.put("resource", resourceName);
        body.put("rule", String.valueOf(e.getRule()));
        body.put("timestamp", System.currentTimeMillis());

        objectMapper.writeValue(response.getWriter(), body);
    }
}

注意:自定义 handler 不生效?

① 包路径:Boot 3 用 ...adapter.spring.webmvc_v6x.callback.BlockExceptionHandler(方法签名是 4 个参数,第三个是 String resourceName);Boot 2 用 ...adapter.spring.webmvc.callback.BlockExceptionHandler(3 个参数)。导错包 → 类实现了另一个接口 → 永远不会回调。

② 类要被 Spring 扫描到(@Component)。

③ 它只管 Web 请求被拦截的情况。@SentinelResource 标记的注解资源被限流时,走的是 blockHandler;Feign 调用被限流时,走的是 fallback/fallbackFactory。三条链路互不相通,需要分别兜底。

④ 全局 @ControllerAdvice 抓不到 BlockException——它在进入 MVC 处理流程之前就被拦截器处理掉了。

9.3 一个统一的响应约定(建议)

{
  "code": 429,
  "msg": "请求过于频繁,请稍后再试",
  "resource": "/order/{orderId}",
  "rule": "FlowRule{resource=/order/{orderId}, limitApp=default, grade=1, count=5, strategy=0}",
  "timestamp": 1762000000000
}

前端约定:code == 429 / 503 时展示"稍后重试"的友好提示,403 时跳转登录或提示无权限。不要把 rule 原文直接暴露给公网,生产环境建议只在内网或按需输出。

十、规则持久化:原始、pull、push 三种模式

这一章是 Sentinel 生产落地的分水岭。

10.1 三种模式对比

模式

数据流向

规则存储

重启后

一致性

生产可用

原始模式

控制台 → 客户端内存

内存

丢失

强(推送即生效)

❌ 仅适合学习

pull 模式

控制台 → 客户端 → 本地文件/DB,客户端定时轮询拉取

本地文件 / DB

不丢

弱(有秒级延迟)

⚠️ 小规模可用

push 模式

控制台 → 配置中心(Nacos)→ 客户端监听变更

Nacos / Apollo / etcd

不丢

强(监听推送,秒级生效)

✅ 推荐

10.2 push 模式落地(推荐)

架构:

  ┌────────────┐   写规则    ┌─────────────┐   监听/推送   ┌──────────────┐
  │  Sentinel  │───────────▶│    Nacos    │─────────────▶│ order-service│
  │  Dashboard │             │ 配置中心     │               │  (Sentinel)  │
  └────────────┘             └─────────────┘               └──────────────┘

方案一(最省事,推荐大多数团队):不用控制台改规则,规则直接维护在 Nacos 配置里,客户端通过 sentinel-datasource-nacos 监听。控制台仅作为监控面板和临时调试。

spring:
  cloud:
    sentinel:
      datasource:
        # 流控规则
        flow:
          nacos:
            server-addr: 127.0.0.1:8848
            dataId: order-service-flow-rules
            groupId: SENTINEL_GROUP
            data-type: json
            rule-type: flow
        # 熔断规则
        degrade:
          nacos:
            server-addr: 127.0.0.1:8848
            dataId: order-service-degrade-rules
            groupId: SENTINEL_GROUP
            data-type: json
            rule-type: degrade
        # 热点参数规则
        param-flow:
          nacos:
            server-addr: 127.0.0.1:8848
            dataId: order-service-param-rules
            groupId: SENTINEL_GROUP
            data-type: json
            rule-type: param-flow
        # 授权规则
        authority:
          nacos:
            server-addr: 127.0.0.1:8848
            dataId: order-service-authority-rules
            groupId: SENTINEL_GROUP
            data-type: json
            rule-type: authority
        # 系统规则
        system:
          nacos:
            server-addr: 127.0.0.1:8848
            dataId: order-service-system-rules
            groupId: SENTINEL_GROUP
            data-type: json
            rule-type: system

Nacos 中 order-service-flow-rules 的内容(Data ID 后缀不带 .json,Group 用 SENTINEL_GROUP):

[
  {
    "resource": "/order/{orderId}",
    "limitApp": "default",
    "grade": 1,
    "count": 5,
    "strategy": 0,
    "controlBehavior": 0,
    "clusterMode": false
  },
  {
    "resource": "/order/query",
    "limitApp": "default",
    "grade": 1,
    "count": 5,
    "strategy": 1,
    "refResource": "/order/update",
    "controlBehavior": 0,
    "clusterMode": false
  },
  {
    "resource": "GET:/seckill/{goodsId}",
    "limitApp": "default",
    "grade": 1,
    "count": 10,
    "strategy": 0,
    "controlBehavior": 1,
    "warmUpPeriodSec": 5,
    "clusterMode": false
  }
]

熔断规则 JSON:

[
  {
    "resource": "GET:http://user-service/user/{id}",
    "grade": 0,
    "count": 50,
    "slowRatioThreshold": 0.4,
    "statIntervalMs": 1000,
    "minRequestAmount": 5,
    "timeWindow": 5
  }
]

热点参数规则 JSON:

[
  {
    "resource": "hotProduct",
    "paramIdx": 0,
    "grade": 1,
    "count": 2,
    "durationInSec": 1,
    "clusterMode": false,
    "paramFlowItemList": [
      { "object": "2", "classType": "java.lang.Long", "count": 4 },
      { "object": "3", "classType": "java.lang.Long", "count": 10 }
    ]
  }
]

授权规则 JSON:

[
  {
    "resource": "/order/{orderId}",
    "limitApp": "gateway",
    "strategy": 0
  }
]

方案二(控制台 + Nacos 双向打通):改造 sentinel-dashboard 源码,实现规则的 Nacos 读写,让控制台上的改动直接落到 Nacos。核心是实现两个接口并替换 Controller 依赖:

@Component("flowRuleNacosProvider")
public class FlowRuleNacosProvider implements DynamicRuleProvider<List<FlowRuleEntity>> {

    @Autowired
    private ConfigService configService;

    @Override
    public List<FlowRuleEntity> getRules(String appName) throws Exception {
        String dataId = appName + NacosConfigUtil.FLOW_DATA_ID_POSTFIX;   // -flow-rules
        String rules = configService.getConfig(dataId, NacosConfigUtil.GROUP_ID, 3000);
        if (StringUtils.isEmpty(rules)) {
            return new ArrayList<>();
        }
        List<FlowRule> list = JSON.parseArray(rules, FlowRule.class);
        return list.stream()
        .map(r -> FlowRuleEntity.fromFlowRule(appName, null, null, r))
        .collect(Collectors.toList());
    }
}

@Component("flowRuleNacosPublisher")
public class FlowRuleNacosPublisher implements DynamicRulePublisher<List<FlowRuleEntity>> {

    @Autowired
    private ConfigService configService;

    @Override
    public void publish(String app, List<FlowRuleEntity> rules) throws Exception {
        String dataId = app + NacosConfigUtil.FLOW_DATA_ID_POSTFIX;
        configService.publishConfig(dataId, NacosConfigUtil.GROUP_ID,
                                    JSON.toJSONString(rules.stream().map(FlowRuleEntity::toRule).collect(Collectors.toList())),
                                    ConfigType.JSON.getType());
    }
}

然后把 FlowControllerV1 的 ruleProvider / rulePublisher 换成上面两个 Bean(或直接使用官方提供的 FlowControllerV2)。改造细节较多,且控制台与 Nacos 耦合,团队要有维护能力才建议走这条路。

10.3 用 SPI 初始化规则(不用控制台也能有默认规则)

生产上常见诉求:"应用启动就有一批兜底规则,Nacos 挂了也不至于裸奔"。Sentinel 提供 InitFunc SPI:

public class SentinelRuleInitFunc implements InitFunc {

    @Override
    public void init() throws Exception {
        // 流控
        List<FlowRule> flowRules = new ArrayList<>();
        FlowRule flow = new FlowRule("/order/{orderId}")
                .setGrade(RuleConstant.FLOW_GRADE_QPS)
                .setCount(100);
        flowRules.add(flow);
        FlowRuleManager.loadRules(flowRules);

        // 系统保护兜底
        List<SystemRule> systemRules = new ArrayList<>();
        SystemRule sys = new SystemRule();
        sys.setHighestSystemLoad(4.0);
        sys.setHighestCpuUsage(0.85);
        systemRules.add(sys);
        SystemRuleManager.loadRules(systemRules);
    }
}

在 src/main/resources/META-INF/services/ 下建文件com.alibaba.csp.sentinel.init.InitFunc,内容写:

com.example.order.config.SentinelRuleInitFunc

注意:SPI 规则会被 Nacos 数据源的规则覆盖(后加载者生效),所以它只作为"启动兜底",不要在里面写业务强相关的阈值,避免和 Nacos 配置打架。

10.4 集群流控(一句话补充)

上面的规则都是单机阈值。如果要限制"整个集群总共 100 QPS",需要部署 Sentinel Token Server(sentinel-cluster 模块),客户端作为 Token Client 向它申请令牌。引入成本和运维复杂度都不低,一般业务用单机阈值 × 实例数估算即可,只有严格配额场景(如第三方 API 调用配额)才上集群流控。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐