Hystrix内部原理与Resilience4j迁移
Hystrix 已进入维护历史，新项目不应把它作为默认选择，但大量 JDK 8/Spring Cloud Netflix 存量系统仍在运行。学习 Hystrix 的价值是看懂线程池隔离、熔断统计、Fallback 与请求上下文；现代 Java 17+/Boot 3 项目则应根据生态选择 Resilience4j、Sentinel 或平台数据面，并明确模块组合边界。
一、双版本技术线
| 技术线 | 常见组合 | 学习目标 |
|---|---|---|
| 存量维护 | JDK 8、Spring Cloud Netflix、Feign+Ribbon+Hystrix | 能读配置、定位线程池/熔断/Fallback问题，制定迁移 |
| 现代应用 | Java 17+、Boot 3、Spring Cloud CircuitBreaker、Resilience4j/Sentinel | 模块化组合Timeout、Bulkhead、Retry、CircuitBreaker并接入Micrometer |
具体兼容性必须按 Boot、Cloud Release Train 和组件精确版本核对。不能在 Boot 3 项目里机械复制旧 @HystrixCommand 配置，也不能把某个 Resilience4j 小版本的属性套到全部版本。
二、Hystrix核心对象
| 对象 | 职责 |
|---|---|
HystrixCommand / HystrixObservableCommand | 包装一次受保护调用 |
| CommandKey | 单个命令统计和配置身份 |
| CommandGroupKey | 逻辑分组，常影响默认线程池归属 |
| ThreadPoolKey | 隔离线程池身份 |
| CircuitBreaker | 根据滚动指标决定是否放行 |
| CommandMetrics | 成功、失败、超时、拒绝、Fallback统计 |
| RequestContext | Request Cache、Collapser等请求级上下文 |
| ExecutionHook/Plugins | 上下文和生命周期扩展；全局插件需谨慎 |
GroupKey 相同不代表所有调用必须共享一个线程池；高风险下游应按故障域设置独立 ThreadPoolKey，否则一个慢下游会占满共享池。
三、HystrixCommand一次执行链
flowchart TD
A["调用execute/queue/observe"] --> B{"Request Cache命中"}
B -- "命中" --> C["复用请求级结果"]
B -- "未命中" --> D{"Circuit是否允许请求"}
D -- "拒绝" --> K["进入Fallback"]
D -- "允许" --> E{"线程池或信号量是否有容量"}
E -- "拒绝" --> K
E -- "允许" --> F["执行run/construct"]
F --> G{"成功、失败或超时"}
G -- "成功" --> H["记录SUCCESS并返回"]
G -- "失败/超时" --> K
K --> L{"Fallback资源和逻辑是否成功"}
L -- "成功" --> M["返回降级结果并记录"]
L -- "失败" --> N["抛出最终异常"]实际顺序和缓存/Observable细节受调用方式影响，但核心是：是否放行、是否有隔离容量、执行结果、Fallback、指标。短路、线程池拒绝、信号量拒绝和执行失败是不同事件，监控不能全部归为“调用失败”。
四、线程池隔离
调用方把任务提交到 Hystrix 专用线程池，工作线程执行下游调用。收益：慢调用主要占用隔离池，不直接占满入口业务线程；可为库存、支付、推荐设置不同池。
flowchart TD
A["业务线程提交Command"] --> B{"隔离线程池/队列是否接收"}
B -- "否" --> C["THREAD_POOL_REJECTED并Fallback"]
B -- "是" --> D["Hystrix工作线程调用下游"]
D --> E{"在超时内结束"}
E -- "是" --> F["返回结果并释放线程"]
E -- "否" --> G["调用方快速进入Fallback"]
G --> H["底层任务能否响应中断取决于客户端"]重要边界：Hystrix 超时后可中断工作线程，但 JDBC、Socket、第三方库不一定响应中断，底层调用可能继续占用线程和连接。因此 HTTP Connect/Read Timeout、数据库 Query Timeout 仍不可省。
线程切换还会丢失普通 ThreadLocal/MDC/SecurityContext。需要经过审查的 ConcurrencyStrategy/Hook 或在提交前捕获、工作线程设置、finally清理。上下文不能泄漏到线程池下一任务。
五、信号量隔离
信号量模式在调用线程直接执行，只限制并发数量，没有线程切换，开销低、ThreadLocal自然保留。它不提供独立工作线程边界：下游阻塞时调用线程仍被占用，不能像线程池隔离那样把慢调用约束在专用池。
适合快速、可预期、非网络或已有严格异步边界的调用。远程阻塞 I/O 使用信号量时，必须依赖客户端超时、入口并发限制和下游容量；不能看到“有信号量”就认为完成隔离。
六、线程池、队列和拒绝
Hystrix 线程池常见 CoreSize、MaxQueueSize、QueueSizeRejectionThreshold。大队列不会增加处理能力，只延迟拒绝并让请求在队列中耗尽 Deadline。
Little's Law 近似帮助理解：
并发在途数 ≈ 到达率 × 平均服务时间下游 100 QPS、平均 200ms，平均在途约 20；还要考虑尾延迟和突发。线程数不能超过下游连接池/容量太多，否则只是把等待从入口移到下游。
maxQueueSize 的实现选择可能在初始化时确定，某些属性不能靠动态配置安全改变底层队列结构；必须按精确版本验证。
七、Rolling Metrics与熔断判断
Hystrix 在滚动时间窗口内按 Bucket 汇总成功、失败、超时、拒绝等事件。典型判断需要同时满足：
- 窗口请求量达到 RequestVolumeThreshold。
- 错误百分比达到 ErrorThresholdPercentage。
- Circuit 打开后等待 SleepWindow。
- 之后允许试探请求；成功关闭，失败继续打开。
请求量门槛避免低流量服务“一次失败就是100%”立即熔断。窗口太长反应迟钝，太短容易抖动；指标 Bucket、阈值和业务流量必须一起评估。
熔断器是每实例本地状态，不是全局开关。不同实例因流量和错误样本不同，可能处于不同状态。
八、哪些事件计入错误
执行异常、Timeout、ThreadPool/Semaphore Rejection、ShortCircuit通常会进入不同指标事件。Bad Request 类异常可用于表达调用方参数错误，不应计入下游健康失败，但滥用会掩盖真实故障。
HTTP 404、业务“库存不足”、连接失败、429、500 的重试和熔断语义不同。要在 Feign ErrorDecoder/客户端边界分类，不能所有非2xx都计为同一种系统失败。
九、Fallback不是“返回成功”
Fallback 要保持业务语义：推荐服务失败可返回空推荐，支付状态查询失败不能返回“未支付”，权限服务失败不能默认放行，库存扣减超时不能返回扣减成功。
Fallback 也有独立并发保护，且应简单、快速、少依赖。Fallback 再调用同一个故障服务会递归放大；调用另一个服务也要有独立保护。
错误响应要保留 degraded=true、错误码和可追踪原因，避免上游把默认对象持久化成业务事实。
十、Request Cache与Collapser
Request Cache 只在初始化了 HystrixRequestContext 的请求范围内按 CacheKey 复用，不是跨请求全局缓存。异步线程和非Servlet入口要正确传播/关闭上下文。
Request Collapser 可在短时间窗把多个单查合并成批量请求，减少下游调用，但增加等待、映射和部分失败复杂度。批量接口必须限制大小，并能把每个结果按请求Key正确拆回。
十一、Resilience4j模块边界
本节负责Hystrix迁移映射；Resilience4j 2.x的Java 17版本线、CircuitBreakerStateMachine、Subtract-on-Evict滑动窗口、Bulkhead、Retry、AtomicRateLimiter、TimeLimiter、Spring Boot 3自动配置和Spring Cloud Factory源码见Resilience4j内部原理与生产治理。
| 模块 | 只解决什么 | 不自动解决 |
|---|---|---|
| CircuitBreaker | 统计并快速拒绝 | 超时、线程隔离 |
| Retry | 有限再次执行 | 幂等、总Deadline |
| RateLimiter | 时间维度许可 | 下游并发隔离 |
| Bulkhead | 并发许可或线程池隔离 | 失败率熔断 |
| TimeLimiter | 限制Future/CompletionStage等待 | 底层I/O必然停止 |
Resilience4j 核心是装饰函数，不默认创建 Hystrix 式线程池。只有 ThreadPoolBulkhead 等模块引入执行器；SemaphoreBulkhead只限制并发。CircuitBreaker本身也不提供Timeout。
十二、Resilience4j CircuitBreaker内部状态
CLOSED 收集滑动窗口指标；达到最小调用量后根据失败率和慢调用率打开。OPEN 到期后进入 HALF_OPEN，允许有限探测；探测结果决定关闭或重开。
滑动窗口可按次数或时间。实现通常维护预聚合总量，Bucket淘汰时减去其统计，不需要每次计算扫描全部调用。最小调用量、失败率、慢调用阈值和半开许可必须结合真实流量。
十三、装饰器顺序为什么影响语义
Retry(CircuitBreaker(call))可能让每次重试尝试分别进入熔断统计；而：
CircuitBreaker(Retry(call))可能只把整组重试最终结果作为一次熔断样本。注解组合的实际顺序受框架Aspect Order影响，应通过集成测试和Metrics证明，关键链路可显式使用Decorators表达顺序。
通用建议：入口总Deadline在最外层，Bulkhead先限制并发，Retry受预算且靠近调用，CircuitBreaker统计口径按业务决定。不存在所有系统通用的唯一顺序。
十四、TimeLimiter与取消边界
TimeLimiter 对 Future/CompletionStage 限制等待时间，配置取消 Future 也不保证底层 Socket、JDBC 或业务事务停止。阻塞调用仍要客户端超时；响应超时后业务事实仍可能成功，需要幂等和查询。
虚拟线程是 Java 21 能力，不是 Java 17 能力；它降低阻塞线程成本，但不能替代连接池、Bulkhead、Timeout、熔断和下游容量。
十五、Hystrix到Resilience4j迁移映射
| Hystrix能力 | Resilience4j方向 | 迁移注意 |
|---|---|---|
| Command Circuit | CircuitBreaker | 指标窗口和异常分类不同 |
| ThreadPool Isolation | ThreadPoolBulkhead | 线程池/队列语义重新压测 |
| Semaphore Isolation | SemaphoreBulkhead | 调用仍在当前线程 |
| Execution Timeout | TimeLimiter + 客户端Timeout | 底层取消边界不同 |
| Fallback | fallbackMethod/recover | 方法签名与异常选择 |
| Request Cache | 业务/框架缓存 | 作用域与Key重新设计 |
| Dashboard Metrics | Micrometer/Actuator | 指标名和标签变化 |
迁移不要一次同时改组件、超时、重试和业务Fallback。先记录旧系统基线，再逐个下游灰度，比较物理尝试数、拒绝率、线程/连接池、P99和业务降级率。
十六、Java 17+、Spring Boot 3.x现代实现
现代项目不再复制 @HystrixCommand，而是先由 Spring Boot 与 Spring Cloud 的兼容矩阵确定依赖基线，再使用 Spring Cloud CircuitBreaker 门面或直接组合 Resilience4j 模块。下面的依赖不单独填写版本，版本必须由与当前 Boot 3.x 匹配的 Spring Cloud BOM 统一管理：
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>不能把“Boot 3.x”当成一个永远固定的版本：Boot 3.0、3.2、3.4 等小版本对应的 Spring Cloud 发布列车、Resilience4j、Micrometer 与 HTTP 客户端能力并不完全相同。先锁定 BOM，再以该版本官方配置元数据和自动配置报告为准；不要从另一条版本线复制属性名。
16.1 最小可运行配置
import java.time.Duration;
import io.github.resilience4j.circuitbreaker.CircuitBreakerConfig;
import io.github.resilience4j.timelimiter.TimeLimiterConfig;
import org.springframework.cloud.client.circuitbreaker.Customizer;
import org.springframework.cloud.circuitbreaker.resilience4j.Resilience4JCircuitBreakerFactory;
import org.springframework.cloud.circuitbreaker.resilience4j.Resilience4JConfigBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
class ResilienceConfiguration {
@Bean
Customizer<Resilience4JCircuitBreakerFactory> inventoryCircuit() {
return factory -> factory.configure(builder -> builder
.circuitBreakerConfig(CircuitBreakerConfig.custom()
.slidingWindowSize(20)
.minimumNumberOfCalls(10)
.failureRateThreshold(50.0f)
.waitDurationInOpenState(Duration.ofSeconds(10))
.permittedNumberOfCallsInHalfOpenState(3)
.build())
.timeLimiterConfig(TimeLimiterConfig.custom()
.timeoutDuration(Duration.ofMillis(800))
.cancelRunningFuture(true)
.build()), "inventory");
}
}import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.circuitbreaker.CircuitBreakerFactory;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
@RestController
public class ResilienceDemoApplication {
private final CircuitBreakerFactory<?, ?> factory;
public ResilienceDemoApplication(CircuitBreakerFactory<?, ?> factory) {
this.factory = factory;
}
public static void main(String[] args) {
SpringApplication.run(ResilienceDemoApplication.class, args);
}
@GetMapping("/inventory/{sku}")
InventoryView inventory(@PathVariable String sku) {
return factory.create("inventory").run(
() -> queryRemoteInventory(sku),
error -> InventoryView.unknown(sku, error.getClass().getSimpleName()));
}
private InventoryView queryRemoteInventory(String sku) {
// Demo用固定异常模拟下游失败；生产中替换为配置了连接、读取和连接池超时的HTTP客户端。
if (sku.startsWith("FAIL")) {
throw new IllegalStateException("inventory unavailable");
}
return new InventoryView(sku, 12, "CONFIRMED", null);
}
record InventoryView(String sku, Integer quantity, String status, String degradedBy) {
static InventoryView unknown(String sku, String reason) {
return new InventoryView(sku, null, "UNKNOWN", reason);
}
}
}调用 /inventory/A100 返回已确认库存；调用 /inventory/FAIL-A100 进入 Fallback，但返回的是 UNKNOWN，不是伪造的“库存为0”或“扣减成功”。record 是 Java 16 正式能力，所以这段代码明确属于 Java 17+ 线，不能复制到 JDK 8 项目。
Actuator 最小暴露配置：
management:
endpoints:
web:
exposure:
include: health,info,metrics先访问 /actuator/metrics 查看当前依赖版本实际注册的指标，再按实例、后端名称、结果类型观察成功、失败、慢调用、拒绝和状态变化。不要凭记忆写死某个小版本的指标名称。
16.2 现代调用链到底怎样走
flowchart TD
A["Controller收到请求"] --> B["业务Service分配Deadline"]
B --> C["CircuitBreakerFactory按inventory取实例"]
C --> D{"熔断状态允许调用吗"}
D -->|否| E["短路并进入语义化Fallback"]
D -->|是| F["TimeLimiter限制等待时间"]
F --> G["执行真实HTTP或RPC调用"]
G --> H["客户端连接与读取超时"]
H --> I["记录成功、失败或慢调用"]
I --> J["更新滑动窗口与熔断状态"]这里有三层不同边界：
TimeLimiter限制上层等待多久，不保证底层 Socket 或数据库语句物理停止。- HTTP/RPC 客户端超时负责约束连接、获取连接、读取等具体阶段；它不能替代总请求 Deadline。
- CircuitBreaker 根据已完成调用结果更新状态；它不是线程池，也不会自动限制并发。
若还需要并发隔离、有限重试或限流，应显式加入 Bulkhead、Retry、RateLimiter，并通过测试确认装饰顺序。生产代码还要把 UNKNOWN、DEGRADED 等事实状态纳入响应契约、日志、Trace 和指标，不能只在服务端悄悄吞掉异常。
十七、JDK 8 Demo：信号量并发隔离
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Semaphore;
import java.util.concurrent.atomic.AtomicInteger;
public final class SemaphoreBulkheadDemo {
public static void main(String[] args) throws Exception {
final Semaphore bulkhead = new Semaphore(2);
final AtomicInteger accepted = new AtomicInteger();
final AtomicInteger rejected = new AtomicInteger();
final CountDownLatch start = new CountDownLatch(1);
final CountDownLatch done = new CountDownLatch(5);
for (int i = 0; i < 5; i++) {
new Thread(new Runnable() {
public void run() {
try {
start.await();
if (!bulkhead.tryAcquire()) {
rejected.incrementAndGet();
return;
}
accepted.incrementAndGet();
try { Thread.sleep(80L); }
finally { bulkhead.release(); }
} catch (InterruptedException ex) {
Thread.currentThread().interrupt();
} finally {
done.countDown();
}
}
}).start();
}
start.countDown();
done.await();
System.out.println("accepted=" + accepted.get());
System.out.println("rejected=" + rejected.get());
}
}同时发起5个任务、许可为2时，非等待式 tryAcquire 会快速拒绝其余任务。生产是否排队、等待多久、怎样Fallback，要由业务Deadline和容量决定。
十八、商业场景：订单聚合接口
订单详情并行调用订单、库存、优惠券、物流：订单是核心，其他可降级。每个下游使用独立 Bulkhead 和Timeout；库存失败显示“暂不可用”而不是“无库存”；优惠券可返回空但标记降级；物流慢不阻塞订单主信息。
总接口Deadline 1500ms 时，四个下游不能各配置1500ms后再重试3次。应并行调用、每个子预算小于总预算、Retry受总预算、Fallback不再远程调用，并把降级状态返回前端和指标系统。
十九、失败窗口
| 窗口 | 风险 | 治理 |
|---|---|---|
| Hystrix超时后底层仍运行 | 线程/连接继续占用 | 客户端Timeout、中断响应、幂等 |
| 共享线程池被单下游占满 | 无关调用拒绝 | 按故障域隔离ThreadPoolKey |
| 大队列积压 | 请求过期后才执行 | 小队列、快速拒绝、Deadline |
| Fallback返回默认成功 | 业务事实被污染 | 保持错误语义和degraded标记 |
| 多实例熔断状态不同 | 流量分布不一致 | 按实例指标、不要假设全局开关 |
| 多层Retry | 物理尝试相乘 | 唯一主要重试层、Retry Budget |
| 迁移配置语义不等价 | 拒绝/超时行为改变 | 基线、灰度、故障注入和回滚 |
二十、熔断、拒绝和Fallback激增Runbook
- 按 Command/实例区分 Failure、Timeout、ShortCircuit、ThreadPoolRejected、SemaphoreRejected、FallbackFailure。
- 检查入口QPS、下游P99、错误类型和熔断窗口请求量，不能只看失败百分比。
- 线程池隔离检查Active、Queue、Completed、Rejection、任务运行和客户端连接池。
- 检查Timeout后底层线程栈和连接是否仍运行，核对HTTP/JDBC超时。
- 检查Fallback是否访问远程依赖、是否掩盖权限/支付/库存错误。
- 检查多层Retry和装饰器顺序，统计每逻辑请求物理Attempt。
- 迁移期间按旧/新实例比较P99、拒绝、熔断、降级、线程和连接资源。
- 修复后注入慢调用、连接失败、线程池耗尽、Fallback失败和半开探测。
二十一、常见错误
| 错误 | 正确理解 |
|---|---|
| Hystrix超时后下游一定停止 | 底层库可能不响应中断 |
| 信号量等于线程隔离 | 调用仍占用当前线程 |
| 大队列提高可用性 | 常把失败变成过期排队 |
| 熔断器包含超时和线程池 | Resilience4j模块需显式组合 |
| Fallback返回空对象就是成功 | 必须符合业务语义并标记降级 |
| Circuit状态全局一致 | 通常每实例本地统计 |
| 注解顺序无影响 | Retry/Circuit/Timeout组合语义不同 |
| Java17已有虚拟线程 | 虚拟线程在Java21正式提供 |