自定义封装 circuitbreakeropenexception 的核心目标是统一异常语义、适配业务错误码、保留原始上下文、便于日志追踪和前端友好提示；推荐继承该异常并添加服务名、操作名、错误码等字段，配合全局异常处理器返回标准 503 响应。
在 Java 中使用熔断器（如 Resilience4j、Hystrix 或自研实现）时，CircuitBreakerOpenException 是熔断器处于 OPEN 状态时抛出的标准异常。它本身是运行时异常（RuntimeException），通常不建议直接暴露给上层业务或前端。因此，**自定义封装的核心目标是：统一异常语义、适配业务错误码、保留原始上下文、便于日志追踪和前端友好提示**。
封装原则：继承 + 语义增强
推荐继承 CircuitBreakerOpenException（如果使用 Resilience4j）或其父类 RuntimeException，并添加业务字段：
- 定义唯一错误码（如
BIZ_CIRCUIT_BREAKER_OPEN） - 携带被熔断的服务名、方法名、降级策略标识等上下文
- 重写
getMessage()，组合原始信息与业务描述 - 提供静态工厂方法，简化抛出逻辑
Resilience4j 场景下的典型封装示例
假设你用的是 Resilience4j 的 CircuitBreaker，其原生异常为 io.github.resilience4j.circuitbreaker.CircuitBreakerOpenException：
public class ServiceCircuitBreakException extends CircuitBreakerOpenException {
private final String service;
private final String operation;
private final String errorCode = "BIZ_CIRCUIT_BREAKER_OPEN";
public ServiceCircuitBreakException(String service, String operation) {
super("Service [" + service + "] is unavailable due to circuit breaker OPEN. Operation: " + operation);
this.service = service;
this.operation = operation;
}
// 静态便捷构造
public static ServiceCircuitBreakException of(String service, String operation) {
return new ServiceCircuitBreakException(service, operation);
}
// getter 省略...
}
在降级逻辑中统一抛出或转换
不要在每个 fallback 方法里手动 new 异常，而是集中处理：
- 使用 Resilience4j 时，在
fallbackMethod或ignoreExceptions后的兜底逻辑中，检查是否因熔断触发，并主动 throw 封装后的异常 - 若使用 Spring Cloud CircuitBreaker（抽象层），可在
Customizer<resilience4jcircuitbreakerfactory></resilience4jcircuitbreakerfactory>中注册全局 fallback，统一转换异常 - 避免在 controller 层 catch 原生
CircuitBreakerOpenException再包装 —— 应前置到服务调用层或熔断拦截点
配合全局异常处理器返回标准响应
Spring Boot 中通过 @ControllerAdvice 捕获自定义异常，输出结构化 JSON：
@ExceptionHandler(ServiceCircuitBreakException.class)
public ResponseEntity<errorresponse> handleCircuitBreak(ServiceCircuitBreakException e) {
ErrorResponse error = ErrorResponse.builder()
.code(e.getErrorCode())
.message("当前服务暂时不可用，请稍后重试")
.detail(String.format("熔断服务：%s，操作：%s", e.getService(), e.getOperation()))
.timestamp(LocalDateTime.now())
.build();
return ResponseEntity.status(503).body(error);
}</errorresponse>
这样前端收到的是明确的 503 Service Unavailable 和可读提示，而非堆栈或模糊错误。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
