阿里开源流量防护组件——Sentinel
一、前提:微服务为什么会雪崩
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)
- 授权控制(来源白 / 黑名单)
它承接了阿里近十年双十一大促的核心场景:秒杀削峰、消息削峰填谷、集群流控、实时熔断下游不可用应用。
源码:https://github.com/alibaba/Sentinel
2.2 三个核心概念
理解 Sentinel 只需要抓住三个词:
| 概念 | 说明 | 例子 |
| 资源 (Resource) | 被保护的对象,任何一段逻辑都可以是资源 | 一个 Controller 接口 |
| 规则 (Rule) | 定义在资源上的约束 | FlowRule、DegradeRule、ParamFlowRule、SystemRule、AuthorityRule |
| Entry | 一次请求进入资源的凭证, |
|
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 |
| 每秒请求数 | 绝大多数场景,保护"吞吐量" |
| 线程数 |
| 该资源能同时使用的业务线程数最大值 | 保护"并发",即舱壁模式(信号量隔离) |
线程数阈值的含义:限制同一时刻有多少个线程在处理这个资源。注意它限制的是同时在处理的线程数,不是累计通过数——线程释放后新请求立即可以进,所以压测报告里累计通过数会远大于阈值,这是正常现象。
5.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 三种流控效果
| 效果 | 常量 | 行为 | 适用 |
| 快速失败 |
(默认) | 超阈值立即抛 | 绝大多数在线接口 |
| Warm Up(预热) |
| 阈值从 动态爬升到 | 冷启动、缓存未预热、秒杀开场 |
| 排队等待 |
| 请求排队匀速通过,等待超时则拒绝 | 削峰填谷、异步任务、下游扛不住瞬时并发 |
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();
}
}
}
注意:
entry.exit()必须执行,否则统计窗口里的"占用"永远不释放;- 业务异常必须
Tracer.trace(t),否则熔断的"异常比例 / 异常数"策略永远触发不了; - 需要按参数维度限流时,用
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)实现,三种策略:
| 策略 | 常量 | 判断依据 | 典型配置 |
| 慢调用比例 |
| RT 超过阈值的请求占比 | RT > 500ms 记为慢调用,1s 内请求 ≥ 10 且慢调用比例 ≥ 0.5 → 熔断 5s |
| 异常比例 |
| 异常数 / 总请求数 | 1s 内请求 ≥ 10 且异常比例 ≥ 0.5 → 熔断 5s |
| 异常数 |
| 统计窗口内异常绝对数 | 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 的子类
| 异常 | 触发场景 |
|
| 限流(含预热、排队等待超时) |
|
| 热点参数限流 |
|
| 熔断降级 |
|
| 授权规则拦截(黑白名单) |
|
| 系统自适应保护 |
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 调用配额)才上集群流控。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐
所有评论(0)