🏆本文收录于《滚雪球学SpringBoot 3》:https://blog.csdn.net/weixin_43970743/category_12795608.html，专门攻坚指数提升，本年度国内最系统+最专业+最详细（永久更新）。
  
本专栏致力打造最硬核 SpringBoot3 从零基础到进阶系列学习内容，🚀均为全网独家首发，打造精品专栏，专栏持续更新中…欢迎大家订阅持续学习。 如果想快速定位学习，可以看这篇【SpringBoot3教程导航帖】https://blog.csdn.net/weixin_43970743/article/details/151115907，你想学习的都被收集在内，快速投入学习！！两不误。
  
若还想学习更多，可直接前往《滚雪球学SpringBoot(全版本合集)》:https://blog.csdn.net/weixin_43970743/category_11599389.html，涵盖SpringBoot所有版本教学文章。

演示环境说明：

• 开发工具：IDEA 2021.3
• JDK版本： JDK 17（推荐使用 JDK 17 或更高版本，因为 Spring Boot 3.x 系列要求 Java 17，Spring Boot 3.5.4 基于 Spring Framework 6.x 和 Jakarta EE 9，它们都要求至少 JDK 17。）
• Spring Boot版本：3.5.4（于25年7月24日发布）
• Maven版本：3.8.2 （或更高）
• Gradle：（如果使用 Gradle 构建工具的话）：推荐使用 Gradle 7.5 或更高版本，确保与 JDK 17 兼容。
• 操作系统：Windows 11

前言：容错不是“加个注解就完事”，而是“故障别扩散、系统别陪葬”

微服务调用链一长，最怕的不是“某个服务挂了”，而是挂的那一瞬间把上游也拖下水：线程占满、连接排队、超时堆积，最后雪崩像多米诺骨牌一样哗啦啦倒一片。
  Resilience4j 的定位很明确：提供一套轻量、模块化的容错组件（熔断、限流、隔离、重试、超时……），能按需组合装饰你的调用。
  而且它对 Spring Boot 3 提供了官方 starter，可以用注解 + 配置文件把策略挂到任意 Bean 上。

1. Hystrix 已死，Resilience4j 当立（原因别太感性，要讲证据）

Hystrix 的“死”，不是说它不能跑，而是它不再积极演进：Netflix 在官方仓库明确宣布 Hystrix 进入 maintenance mode，并表示不会再主动 review issue、merge PR、发布新版本，同时推荐新项目转向 Resilience4j 这类活跃项目。

而 Resilience4j 这边，官方给的卖点很务实：

• 轻量、模块化（你只引你需要的模块）
• 以装饰器（decorators）思想组合能力，调用链外面“套一层层保护壳”
• Spring Boot 3 starter：注解 + YAML 直接用

2. Circuit Breaker：熔断器状态转换详解（讲清楚你就赢一半）

Resilience4j CircuitBreaker 的核心就是一个有限状态机，最常用 3 个状态：

• CLOSED（关闭）：正常放行请求，统计成功/失败/慢调用等指标
• OPEN（打开）：直接拒绝请求，抛 CallNotPermittedException（等于“别来烦我”）
• HALF_OPEN（半开）：到达等待时间后，放少量“试探请求”，看后端是否恢复；超出许可数的请求仍会被拒绝

官方文档把关键行为说得很直白：

• OPEN 状态会拒绝调用并抛 CallNotPermittedException
• 等待时间到后从 OPEN 进入 HALF_OPEN，允许配置数量的调用试探
• 试探期间未完成前，多余调用继续被拒绝

2.1 状态转换“人话版”流程图

CLOSED  --(失败率/慢调用率超过阈值)-->  OPEN
OPEN    --(waitDurationInOpenState 到期)--> HALF_OPEN
HALF_OPEN --(试探成功/失败率达标)--> CLOSED
HALF_OPEN --(试探失败/失败率超阈值)--> OPEN

你会发现它的哲学很“社会”：

• 平时（CLOSED）你来我往
• 你把我坑惨了（失败率超阈值）我直接拉黑你（OPEN）
• 过一会儿我冷静了（等待期结束）给你几次机会（HALF_OPEN）
• 你争气就复合（回 CLOSED），不争气继续拉黑（回 OPEN）

2.2 Spring Boot 3 下的注解式使用（示例：订单服务调用支付服务）

依赖：Resilience4j Spring Boot 3 starter 支持用注解挂 circuit breaker / rate limiter 等。
另外记得加 AOP（否则注解不生效，别问我为什么知道😭）。

pom.xml（示意）

<dependency>
  <groupId>io.github.resilience4j</groupId>
  <artifactId>resilience4j-spring-boot3</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

Service：熔断 + fallback

@Service
public class PaymentFacade {

    @CircuitBreaker(name = "payment", fallbackMethod = "fallback")
    public PaymentResult pay(String orderId) {
        // 这里假设是调用远程支付服务（HTTP/gRPC 都一样）
        return remotePay(orderId);
    }

    // fallback 方法签名：原参数 + Throwable
    private PaymentResult fallback(String orderId, Throwable ex) {
        // 这里别“假装成功”，最好返回明确的降级语义
        return PaymentResult.degraded("PAYMENT_UNAVAILABLE", "支付服务繁忙，已降级", orderId);
    }
}

2.3 YAML 配置：把“策略”写出来（别让默认值瞎带节奏）

Resilience4j 官方给了 Spring Boot 的 application.yml 配置示例（circuitbreaker/ratelimiter/bulkhead/thread-pool-bulkhead/timelimiter 都支持）。

这里给一份更“能打”的熔断配置：

resilience4j:
  circuitbreaker:
    instances:
      payment:
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 50
        minimumNumberOfCalls: 20
        failureRateThreshold: 50
        slowCallRateThreshold: 50
        slowCallDurationThreshold: 2s
        waitDurationInOpenState: 10s
        permittedNumberOfCallsInHalfOpenState: 5
        recordExceptions:
          - java.io.IOException
          - org.springframework.web.client.HttpServerErrorException

解释一下“这堆参数到底在干嘛”：

• slidingWindowSize/minimumNumberOfCalls：统计窗口大小与最少样本（样本太少就别熔断，容易误伤）
• failureRateThreshold：失败率阈值（超过就进 OPEN）
• slowCall*：慢调用统计（“不失败但慢到要命”也会拖垮系统）
• waitDurationInOpenState：拉黑时长（OPEN 多久后进入 HALF_OPEN）
• permittedNumberOfCallsInHalfOpenState：半开试探请求数

3. Rate Limiter：接口限流实战（别等流量上来才想起“要限”）

Resilience4j RateLimiter 是“按时间窗口发放许可”的模型，典型配置三件套：

• limitForPeriod：每个刷新周期允许多少次
• limitRefreshPeriod：刷新周期
• timeoutDuration：拿不到许可愿意等多久（0 表示不等，直接拒绝）

3.1 场景：登录接口限流（不然会被爆破到怀疑人生）

Controller：@RateLimiter + fallback

@RestController
@RequestMapping("/auth")
public class AuthController {

    @PostMapping("/login")
    @RateLimiter(name = "loginLimiter", fallbackMethod = "loginBlocked")
    public LoginResp login(@RequestBody LoginReq req) {
        return doLogin(req);
    }

    private LoginResp loginBlocked(LoginReq req, Throwable ex) {
        // 429 更符合语义
        throw new ResponseStatusException(HttpStatus.TOO_MANY_REQUESTS, "慢点兄弟，别把我服务器当沙包🥲");
    }
}

YAML：每秒 5 次，不排队（timeout=0）

resilience4j:
  ratelimiter:
    instances:
      loginLimiter:
        limitForPeriod: 5
        limitRefreshPeriod: 1s
        timeoutDuration: 0

官方文档也提到：你甚至可以在运行时动态调整 timeoutDuration、limitForPeriod，并说明新配置对正在等待的线程/当前周期许可的影响。

小心思（很实用）：

• 对“用户触发型”接口（登录、发短信、下单）一般 timeoutDuration=0，直接拒绝更友好
• 对“内部调用型”接口可以允许短暂等待（例如 50ms～200ms），避免抖动造成大量失败

4. Bulkhead：舱壁模式隔离线程池（别让一个接口拖死全站）

Bulkhead 的目标特别朴素：限制并发，防止某一类调用把资源吃光。Resilience4j 官方明确提供两种实现：

• SemaphoreBulkhead（信号量）：限制并发执行数量（适用于各种线程模型/IO 模型）
• FixedThreadPoolBulkhead（线程池舱壁）：固定线程池 + 有界队列（更像传统“隔离线程池”）

4.1 什么时候用 SemaphoreBulkhead？

• 你用的是同步 MVC（Tomcat 线程模型）
• 或者你不想搞额外线程池，只想限制并发数
• “这类请求最多同时 N 个，多了就别进来”

示例：限制“生成报表”接口并发为 3

@Service
public class ReportService {

    @Bulkhead(name = "reportBulkhead", fallbackMethod = "fallback")
    public Report generate(Long userId) {
        return heavyGenerate(userId);
    }

    private Report fallback(Long userId, Throwable ex) {
        return Report.degraded("REPORT_BUSY", "报表生成排队太长，先给你个简版🙂");
    }
}

resilience4j:
  bulkhead:
    instances:
      reportBulkhead:
        maxConcurrentCalls: 3
        maxWaitDuration: 0

4.2 什么时候用 ThreadPoolBulkhead？

• 你想把某类慢调用放到独立线程池，不要挤占主业务线程
• 你需要线程池大小 + 队列容量双保险
• 比如：第三方风控、图像处理、邮件发送——不隔离你会很痛

Resilience4j 也支持 thread-pool-bulkhead 的 Spring Boot 配置。

resilience4j:
  thread-pool-bulkhead:
    instances:
      riskPool:
        coreThreadPoolSize: 10
        maxThreadPoolSize: 20
        queueCapacity: 100

真实世界的提醒（带点“过来人”的严肃）：

• 线程池舱壁不是越大越好，越大越可能把下游打爆
• 队列不是越长越安全，队列长了只是把超时“推迟发生”，最后更惨
• 最好配合 timeout/timeLimiter（不然请求在队列里排到天荒地老）

5. Spring Boot 3 Starter：注解式配置（以及一个容易踩的顺序坑）

Resilience4j 的 resilience4j-spring-boot3 starter 官方 README 讲得很直接：它让你可以通过注解 + 配置文件把 rate limiter、circuit breaker 等应用到任意 bean。

而且 README 里还专门提醒了一个“阴险的小坑”：在 Spring Boot 3 里默认 Aspect Order 可能导致 @Retry 先于（外层）@CircuitBreaker 执行。

这意味着：你以为“先熔断再重试”，实际可能变成“先重试把下游打爆，再触发熔断”……听起来就很地狱，对吧😅。

所以如果你叠加使用：@Retry + @CircuitBreaker + @RateLimiter + @Bulkhead
一定要明确你希望的顺序（必要时配置 AOP order 或避免过度叠加）。

6.（可选但很建议）监控与指标：你得知道它“什么时候在救你”

光熔断限流不够，你得能看见它在干活。
Spring 生态里集成 metrics 的路径很成熟：Actuator + Resilience4j Micrometer。Spring Cloud CircuitBreaker 的文档也明确：只要类路径里有 actuator 和 resilience4j-micrometer，就会自动配置指标采集。
Resilience4j 官方也提供 Micrometer 绑定方式，支持把所有 CircuitBreaker 实例一次性绑定到 MeterRegistry，并动态绑定新实例。

结语：熔断、限流、舱壁不是“防御性编程”，是“成年人的自我保护”

Hystrix 时代最大的贡献之一，是把“容错”带进了主流工程视野；Resilience4j 则更像现代版本：轻量、模块化、配置友好、和 Spring Boot 3 搭得很顺。

你把这三件套（CircuitBreaker + RateLimiter + Bulkhead）用顺了，线上再来一次“下游抖动”，你会明显感受到：系统不再跟着一起抽搐——那一刻真的挺爽的🙂。

🧧福利赠与你🧧

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学SpringBoot」，bug菌郑重承诺，凡是学习此专栏的同学，均能获取到所需的知识和技能，全网最快速入门SpringBoot，就像滚雪球一样，越滚越大， 无边无际，指数级提升。

最后，如果这篇文章对你有所帮助，帮忙给作者来个一键三连，关注、点赞、收藏，您的支持就是我坚持写作最大的动力。

同时欢迎大家关注公众号:「猿圈奇妙屋」 ，以便学习更多同类型的技术文章，免费白嫖最新BAT互联网公司面试题、4000G PDF编程电子书、简历模板、技术文章Markdown文档等海量资料。

ps：本文涉及所有源代码，均已上传至Gitee：https://gitee.com/bugjun01/SpringBoot-demo 开源，供同学们一对一参考 Gitee传送门https://gitee.com/bugjun01/SpringBoot-demo，同时，原创开源不易，欢迎给个star🌟，想体验下被🌟的感jio，非常感谢❗

🫵 Who am I?

我是 bug菌：

• 热活跃于 CSDN:https://blog.csdn.net/weixin_43970743 | 掘金:https://juejin.cn/user/695333581765240 | InfoQ:https://www.infoq.cn/profile/4F581734D60B28/publish | 51CTO:https://blog.51cto.com/u_15700751 | 华为云:https://bbs.huaweicloud.com/community/usersnew/id_1582617489455371 | 阿里云:https://developer.aliyun.com/profile/uolxikq5k3gke | 腾讯云:https://cloud.tencent.com/developer/user/10216480/articles 等技术社区；
• CSDN 博客之星 Top30、华为云多年度十佳博主&卓越贡献奖、掘金多年度人气作者 Top40；
• 掘金、InfoQ、51CTO 等平台签约及优质作者；
• 全网粉丝累计 30w+。

更多高质量技术内容及成长资料，可查看这个合集入口 👉 点击查看:https://bbs.csdn.net/topics/612438251 👈️
硬核技术公众号 「猿圈奇妙屋」https://bbs.csdn.net/topics/612438251 期待你的加入，一起进阶、一起打怪升级。

- End -