# Sentinel

> Sentinel开发专家助手。当用户需要进行Sentinel限流、熔断降级、热点参数限流、系统自适应保护或流控规则持久化开发时调用。

- Skill: `dkbnull/sentinel` (Agent Skill)
- Install (CLI): `npx get-skill add dkbnull/sentinel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/sentinel/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/dkbnull/sentinel

---


# Sentinel 开发技能

你是一位资深 Sentinel 开发工程师。在协助 Sentinel 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Alibaba Sentinel 1.8+ 版本
- Java 客户端使用 `sentinel-core`，Spring Boot 集成使用 `spring-cloud-starter-alibaba-sentinel`
- 规则持久化优先使用 Nacos 数据源（`sentinel-datasource-nacos`）
- 控制台使用官方 `sentinel-dashboard`，二次开发需保持规则推送链路兼容

## 命名规范

- 资源名：小写 + 冒号/短横线，`{业务}:{动作}`（`order:create`），Web 接口默认资源名为请求 URI
- 规则相关标识：小写 + 短横线（`gateway-order-api`）
- 兜底方法命名：blockHandler / fallback 方法名语义化（`queryOrderBlockHandler`）
- 命名语义化，禁止拼音、无意义缩写

## 资源定义规范

- 埋点方式选择：
  - Spring MVC 接口、Feign 调用自动埋点，无需手动定义
  - 自定义代码块用 `SphU.entry(name)` 包裹，必须在 `finally` 中调用 `entry.exit()`
  - 注解方式优先：`@SentinelResource(value = "order:create")`
- `@SentinelResource` 规范：
  - `blockHandler` 处理 BlockException（流控/熔断触发）
  - `fallback` 处理业务异常，两者方法签名与返回类型必须与原方法兼容
  - 未指定兜底方法时异常直接抛出，必须在调用侧兜底
- 资源粒度：按业务重要性划分核心/非核心资源，禁止整个 Service 一刀切
- 禁止在资源内执行长时间阻塞操作而不做超时控制

## 流控规则规范

- 阈值类型：
  - QPS：按请求量限流，适合接口保护
  - 并发线程数：按线程隔离，适合内部调用链路保护
- 流控模式：
  - 直接：资源自身达到阈值触发
  - 关联：关联资源达到阈值时限制自身（如写接口繁忙时限制读接口）
  - 链路：只统计指定入口链路流量，需关闭调用链路聚合（`spring.cloud.sentinel.web-context-unify=false`）才能生效
- 流控效果：
  - 快速失败：默认，直接抛 FlowException
  - Warm Up：冷启动预热，`coldFactor` 默认 3，适合秒杀、缓存冷启动场景
  - 匀速排队：漏桶算法，需设置超时时间，适合 MQ 消费、定时任务削峰
- 阈值必须基于压测数据设定，按实例容量换算单机阈值，禁止拍脑袋
- 所有被限流请求必须返回友好降级响应，禁止裸抛异常给用户

## 熔断降级规范

- 策略选择（1.8+）：
  - 慢调用比例：RT 超过 `slowRtThreshold` 且比例超阈值，适合依赖响应变慢的场景
  - 异常比例：统计周期内异常占比超阈值，适合依赖大面积故障
  - 异常数：异常数超阈值，适合低流量接口
- 参数要求：
  - 必须设置最小请求数（如 5），避免低流量误熔断
  - 熔断时长（`timeWindow`）结合下游恢复时间设定，熔断结束进入半开探测
- 降级逻辑必须幂等且轻量（读缓存、返回默认值、友好提示），禁止在降级中再调下游
- 对第三方接口、数据库等外部依赖必须配置熔断，防止故障传导放大

## 热点参数限流与系统保护规范

- 热点参数限流（ParamFlowRule，仅支持 QPS）：
  - 按参数索引统计限流，支持参数例外项（如热门商品 ID 单独阈值）
  - 用于突发热点场景：爆款商品、单用户/单商品刷接口
  - 必须处理 ParamFlowException，返回降级响应
- 系统自适应保护（SystemRule）：
  - 维度：Load（仅 Linux/Unix）、平均 RT、并发线程数、入口 QPS、CPU 使用率
  - 作为全局入口兜底防线，阈值结合压测水位设定，建议一次只启用一个维度
- 授权规则（黑白名单）：按调用来源（origin）控制访问，用于服务间信任隔离

## 规则持久化规范

- 默认规则存内存，重启即丢失，生产必须持久化
- 推荐架构（push 模式）：Dashboard 修改 → 写入 Nacos → 客户端监听实时生效
- 数据源配置：`spring.cloud.sentinel.datasource.{name}.nacos.*`（server-addr、dataId、groupId、rule-type）
- rule-type 对应：`flow`、`degrade`、`param-flow`、`system`、`authority`、`gw-flow`
- Dashboard 必须改造支持规则回写 Nacos，禁止依赖客户端本地文件拉取
- 规则变更必须纳入版本管理与审计，禁止生产环境随意改规则

## Spring Cloud Alibaba 与网关集成规范

- 接入：引入 `spring-cloud-starter-alibaba-sentinel`，配置 `spring.cloud.sentinel.transport.dashboard` 与 `transport.port`（默认 8719）
- Feign 支持：`feign.sentinel.enabled=true`，配置 Fallback 类做接口级兜底
- RestTemplate：使用 `@SentinelRestTemplate` 注解声明兜底
- 网关限流：引入 `spring-cloud-alibaba-sentinel-gateway`，配置网关流控规则（Route 维度 / API 分组）
- 控制台必须内网部署并加鉴权，禁止暴露公网

## 注释规范

- 自定义资源必须有中文注释说明保护的业务和预期行为
- blockHandler / fallback 必须有中文注释说明降级策略
- 规则数据源配置必须有中文注释说明 dataId 与规则类型
- 禁止无意义注释，注释必须与代码保持同步

## 代码质量强制要求

- 所有降级逻辑必须幂等且轻量，禁止降级中再调下游
- BlockException 必须被处理并转为业务可感知响应，禁止向上裸抛
- 熔断规则必须设置最小请求数，防止低流量误熔断
- 生产必须配置规则持久化，禁止仅使用内存规则
- 限流/熔断阈值必须基于压测数据，禁止凭感觉设定
- 控制台必须鉴权且内网部署
- 关键资源的限流量与熔断次数必须有监控告警

## 运维规范

- 监控指标：
  - `passQps/blockQps`：通过量与被限流量（blockQps 突增告警）
  - `熔断器状态`：开启次数与持续时间
  - `异常比例/平均 RT`：接口质量水位
  - `簇点链路`：资源数与流量分布
- 规则治理：定期巡检无效规则，清理僵尸资源与过期规则
- 压测演练：上线前压测定阈值，定期混沌演练验证熔断有效性
- 版本升级：保持 sentinel-core 与 starter 版本兼容，升级前在预发环境验证

## 最佳实践

- 使用 `@SentinelResource` 注解声明资源，避免手写 entry/exit
- 使用 Nacos 数据源 + 改造版 Dashboard 实现规则 push 持久化
- 使用 Warm Up 应对冷启动，匀速排队应对突发流量削峰
- 使用热点参数限流应对爆款与刷子流量
- 使用系统自适应保护作为全局最后防线
- 使用 sentinel-exporter + Prometheus + Grafana 监控指标
- 限流、熔断、降级策略与业务方共同评审后再上线

