← 返回学习路线

SYSTEM

微服务控流熔断(Sentinel 流量控制 + 熔断降级)笔记

后端实战
src/content/notes/blog-dev/微服务控流熔断.md

微服务控流熔断(Sentinel 流量控制 + 熔断降级)笔记

整理日期:2026-08-15 | 场景:2 个月计划 Day 1(微服务收尾 + Sentinel 集成)


一、今日目标

在微服务项目(blog-cloud)中完成 Sentinel 流量控制 + 熔断降级 集成,作为微服务治理”四件套”(Nacos + Feign + Gateway + Sentinel)的收尾亮点。

前置背景:

  • 微服务只保留 user-service + article-service 两个模块
  • 入口统一走 Gateway(8080)
  • 服务注册 Nacos,配置中心已启用
  • Feign 已有静态降级(UserFeignClientFallback),但没有真正的熔断器

二、步骤记录(含每步细节)

Step 0 · 现状检查

检查微服务项目是否有 Sentinel:

  • grep -ri sentinel blog-cloud/ → 无任何结果
  • 结论:没有引入。已有的防护只是 Feign Fallback(静态降级,无熔断状态机)+ 单体侧的 Redis 令牌桶限流

判断:Sentinel 是 Day 1 下午的核心亮点,必须补上。

Step 1 · 环境准备:Sentinel Dashboard

关键认知:官方没有发布 Dashboard 的 Docker 镜像(与 Redis/Nginx 不同),官方只发源码 + 可执行 jar。

  • 版本:sentinel-core 1.8.9(由父 BOM spring-cloud-alibaba-dependencies-2025.0.0.0 托管,sentinel.version=1.8.9)
  • Dashboard 版本必须与客户端版本对齐(版本差太多会导致:连不上、机器列表不显示、规则下发失败)
  • 因此不拉社区镜像,直接用官方 jar
# jar 放置位置:blog-cloud/docker/sentinel/sentinel-dashboard-1.8.9.jar
java -Dserver.port=8858 -Dproject.name=sentinel-dashboard -jar sentinel-dashboard-1.8.9.jar
  • 访问 http://localhost:8858,默认账号 sentinel / sentinel
  • 端口用 8858 而非默认 8080:避免与 Gateway 的 8080 冲突

Step 2 · 引入依赖(blog-article-service/pom.xml)

<!-- Sentinel 流量控制 + 熔断降级 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>
  • 不写版本号:由父 POM 的 alibaba BOM 托管(1.8.9)
  • 注意:TRAE 沙箱下 Maven 下载可能失败,需用外部终端 mvn dependency:resolve(历史教训)

Step 3 · 配置(blog-article-service/application.yml)

spring:
  cloud:
    sentinel:
      transport:
        dashboard: sentinel-dashboard:8080   # docker 场景:服务名 + 容器内端口
        port: 8719                            # 客户端上报端口,被占用自动 +1,可省略
      eager: true                             # 启动即注册到 Dashboard,方便验证

Step 4 · 流量控制:保护热点接口 GET /api/article/page

@GetMapping("/page")
@SentinelResource(value = "articlePage", blockHandler = "pageBlockHandler")
public Result<PageResult<Article>> page(...) { ... }

// blockHandler 要求:
// 1. static 静态方法
// 2. 参数与原业务方法一致
// 3. 末尾追加 BlockException
public static Result<PageResult<Article>> pageBlockHandler(
        int page, int size, String categoryId, String keyword, BlockException ex) {
    return Result.error("请求过于频繁,请稍后再试");
}

Step 5 · 熔断降级:保护 Feign 调用 user-service

核心:必须抽独立 Bean,不能放在调用方内部方法上(详见”问题与解决”)。

新建 UserRemoteService:

@Service
@RequiredArgsConstructor
public class UserRemoteService {

    private final UserFeignClient userFeignClient;

    @SentinelResource(value = "userServiceRemote", fallback = "fallbackGetUser")
    public Result<Map<String, Object>> getUserInfo(Long userId) {
        return userFeignClient.getUserById(userId);
    }

    // fallback 要求:1. static 2. 参数与原方法一致 3. 末尾追加 Throwable
    public static Result<Map<String, Object>> fallbackGetUser(Long userId, Throwable ex) {
        log.error("调用用户服务熔断降级,用户ID:{},异常信息:{}", userId, ex.getMessage());
        return Result.error("用户服务暂时不可用,请稍后刷新评论");
    }
}

CommentServiceImpl 改造:注入 UserRemoteService,真实调用改为 userRemoteService.getUserInfo(comment.getUserId())。

Step 6 · 容器化(blog-cloud/docker/sentinel/Dockerfile + docker-compose.yml)

FROM eclipse-temurin:17-jre
COPY sentinel-dashboard-1.8.9.jar /app/sentinel-dashboard.jar
EXPOSE 8080
ENTRYPOINT ["java", "-Dserver.port=8080", "-jar", "/app/sentinel-dashboard.jar"]
sentinel-dashboard:
  build: ./docker/sentinel
  ports:
    - "8858:8080"
  container_name: sentinel-dashboard
  restart: always
  networks:
    - blog-network

Step 7 · 清理与提交准备

  • 清理死代码 addView():方法 + 无用的 RedisUtil 字段 + import(保留 RedisUtil 类,CommentServiceImpl 还在用)
  • 补用户文章接口 GET /api/article/user/{userId} controller 入口
  • git 提交前:根目录 .gitignore 排除 sentinel-dashboard*.jar(二进制 ~50-100MB,避免被 git add -A 扫进)

三、遇到的问题与解决方案

问题 1:官方没有 Sentinel Dashboard 的 Docker 镜像

  • 现象:想跟 Redis/Nginx 一样直接 docker pull 一个镜像用
  • 原因:Sentinel 官方(Alibaba)只发布 jar,从未发布官方镜像;社区镜像(如 bladex/sentinel-dashboard)是个人维护,版本停在 1.8.0~1.8.6,与客户端 1.8.9 不对齐
  • 风险:版本不一致 → 连不上 / 机器列表不显示 / 规则下发失败,且难排查
  • 解决:用官方 jar,本地 java -jar 或自建 Dockerfile 进容器,保证版本可控

问题 2(关键):熔断降级写了注解但不生效

  • 现象:把 @SentinelResource 直接标在 CommentServiceImpl 的 getUser() 上,实际请求返回的仍是 Feign 静态降级(匿名用户),Sentinel 资源在 Dashboard 里根本不出现
  • 根因(两层):
    1. getUser() 从未被调用——真实调用链是 userFeignClient.getUserById(...),直接绕过了注解方法
    2. 即使改成 this.getUser(id) 也没用——同类内自调用不经过 Spring 代理,Sentinel 切面不触发(AOP 机制)
  • 解决:抽独立 Bean UserRemoteService,让 CommentServiceImpl 通过注入的代理调用 → 切面生效

问题 3:dashboard 地址写错

  • 现象:写 localhost:8080,且与注释(“不要写 localhost/8858”)自相矛盾
  • 原因:localhost 在 docker 容器内指向容器自己,连不到宿主机上的 Dashboard
  • 解决:分场景
    • docker 场景 → sentinel-dashboard:8080(服务名 + 容器内端口)
    • 本地 IDEA 场景 → localhost:8858(docker 把 dashboard 映射到宿主机 8858)
    • 二选一,与 docker-compose 的 8858:8080 保持一致

问题 4:jar 放根目录会被 git add 扫进提交

  • 现象:sentinel-dashboard-1.8.9.jar ~50-100MB,放项目根目录后 git add -A 会一并提交
  • 原因:根目录无 .gitignore(只有 blog/、blog-cloud/ 子目录各自的 .gitignore,仅作用于自身目录)
  • 解决:根目录新建 .gitignore,加 sentinel-dashboard*.jar

问题 5:nginx.conf 位置疑虑

  • 现象:以为新增 docker/sentinel/ 目录要连带搬走 nginx.conf
  • 澄清:纯新增目录不影响已有挂载引用;且仓库里有两套 nginx.conf(根 docker-compose 用 docker/nginx/nginx.conf、微服务用 blog-cloud/nginx.conf),都无需改动

四、当前状态(复查结论)

项 状态
依赖 spring-cloud-starter-alibaba-sentinel ✅ 已加(BOM 托管 1.8.9)
流量控制 /page ✅ @SentinelResource + blockHandler,签名正确
熔断降级 userServiceRemote ✅ 独立 Bean 接入真实调用链,fallback 签名正确
application.yml 地址 ✅ sentinel-dashboard:8080(docker 场景)
docker-compose + Dockerfile + jar ✅ 就位,端口 8858:8080

尚未验证:未实际跑起来(编译、起服务、Dashboard 看资源、触发规则)。


五、验证清单(下一步)

  1. mvn -pl blog-article-service -am compile 确认依赖可解析
  2. 起 docker-compose → Dashboard http://localhost:8858 → 机器列表出现 blog-article-service
  3. 流量控制:控制台给 articlePage 配 QPS=1 → 连续刷新 /api/article/page 看降级
  4. 熔断:控制台给 userServiceRemote 配异常比例规则(阈值 0.5、最小请求数 5、统计时长 10s)→ 停 user-service → 返回”用户服务暂时不可用”
  5. 重启 user-service → 半开探测自动恢复

六、面试话术点

  • 为什么用 Sentinel 而非只靠 Feign fallback:Feign fallback 是”服务不可达”的静态降级,无状态机;Sentinel 有 Closed/Open/Half-Open 状态机、可配异常比例/慢调用比例阈值、控制台可视化
  • 限流算法:QPS 阈值基于令牌桶/漏桶思想,还有热点参数限流、系统自适应限流
  • 规则持久化:生产用 Nacos 数据源持久化规则(当前规则在 Dashboard 内存,重启即丢)
  • 踩过的坑:自调用绕过代理 → Sentinel 不生效,必须抽独立 Bean(可讲出 AOP 代理原理)

七、总结

  1. Sentinel 是 C/S 联动模型,版本必须对齐(1.8.9),官方无镜像 → 用官方 jar
  2. 流量控制:注解 + static blockHandler,简单直接
  3. 熔断降级:抽独立 Bean 是关键,避免同类自调用绕过 AOP 代理
  4. dashboard 地址要按运行场景(docker 服务名 / 本地 localhost:8858)区分
  5. 二进制 jar 注意 .gitignore,避免污染仓库
  6. 代码已就位,剩余工作是真实验证(编译 → 起服务 → 配规则 → 触发降级)