核心机制概述

在微服务架构中，Alibaba Sentinel 提供了 @SentinelResource 注解来声明式地定义受保护的资源。借助 AspectJ 的底层支持，该注解能够自动完成资源的织入，并优雅地处理流量控制（限流）和熔断降级引发的 BlockException，以及各类业务运行时异常。

核心属性详解

配置 @SentinelResource 时，需要深入理解以下关键属性及其方法签名约束：

• value：资源的唯一标识名称，为必填项。
• entryType：流量类型，默认为 EntryType.OUT（出流量），通常无需修改。
• blockHandler / blockHandlerClass：专门用于处理 BlockException（如限流、系统负载保护等）。
  • 方法访问修饰符必须为 public。
  • 返回类型和原方法必须完全一致。
  • 参数列表需与原方法一致，且末尾必须追加一个 BlockException 类型的参数。
  • 若通过 blockHandlerClass 指定外部类，则对应方法必须声明为 static。
• fallback / fallbackClass：用于处理业务逻辑抛出的异常（1.6.0 版本后支持所有异常，早期版本仅限 DegradeException）。
  • 返回类型和原方法必须完全一致。
  • 参数列表需与原方法一致，可选择性地在末尾追加一个 Throwable 参数以接收异常实例。
  • 外部类中的 fallback 方法同样必须为 static。
• defaultFallback：全局通用的默认降级逻辑。
  • 参数列表必须为空，或者仅包含一个 Throwable 参数。
  • 若同时配置了 fallback 和 defaultFallback，系统会优先执行 fallback。
• exceptionsToIgnore：异常豁免名单。配置在此处的异常类型将被直接抛出，不计入熔断降级统计，也不会触发任何 fallback 逻辑。

实战场景与代码重构

为了更清晰地展示各项属性的协同工作机制，以下构建了一个订单查询服务的 RESTful 接口，并将降级逻辑剥离到独立的 Handler 类中。

1. 基础资源定义与处理类

@RestController
@RequestMapping("/api/v1/orders")
public class OrderQueryController {

    @GetMapping("/{orderId}")
    @SentinelResource(
        value = "fetch_order_details",
        blockHandler = "handleRateLimit",
        blockHandlerClass = OrderResilienceHandler.class
    )
    public String fetchOrderDetails(@PathVariable("orderId") Long orderId) {
        // 模拟正常的业务处理
        return "Success: Order_" + orderId;
    }
}

@Slf4j
public class OrderResilienceHandler {

    /**
     * 处理限流与系统级降级
     */
    public static String handleRateLimit(Long orderId, BlockException ex) {
        log.warn("Flow control triggered for order: {}", orderId);
        return "Traffic is too high, please retry later.";
    }
}

场景验证：在 Sentinel 控制台为 fetch_order_details 配置 QPS 限流规则。当请求速率超过阈值时，Sentinel 会抛出 BlockException，请求将被 handleRateLimit 拦截并返回限流提示。若此时在方法内部人为制造 10 / 0 等运行时异常，由于未配置 fallback，异常将直接向上层抛出，证明 blockHandler 仅对限流/降级生效，不处理业务异常。

2. 引入 Fallback 处理业务异常

@GetMapping("/fallback/{orderId}")
@SentinelResource(
    value = "fetch_order_with_fallback",
    fallback = "handleBusinessFailure",
    fallbackClass = OrderResilienceHandler.class
)
public String fetchWithFallback(@PathVariable("orderId") Long orderId) {
    if (orderId % 2 == 0) {
        throw new RuntimeException("Database connection timeout");
    }
    return "Success: Order_" + orderId;
}

// 在 OrderResilienceHandler 中新增：
public static String handleBusinessFailure(Long orderId, Throwable ex) {
    log.error("Business logic failed for order: {}", orderId, ex);
    return "System error, order processing failed.";
}

场景验证：当传入偶数 ID 触发 RuntimeException 时，请求会进入 handleBusinessFailure 返回错误提示。若此时在控制台配置限流规则并触发限流，请求同样会进入 handleBusinessFailure。这表明在未配置 blockHandler 的情况下，fallback 会同时接管业务异常和 BlockException。

3. 职责分离：blockHandler 与 fallback 协同

@GetMapping("/resilience/{orderId}")
@SentinelResource(
    value = "fetch_order_resilience",
    blockHandler = "handleRateLimit",
    blockHandlerClass = OrderResilienceHandler.class,
    fallback = "handleBusinessFailure",
    fallbackClass = OrderResilienceHandler.class
)
public String fetchWithResilience(@PathVariable("orderId") Long orderId) {
    if (orderId % 2 == 0) {
        throw new RuntimeException("Database connection timeout");
    }
    return "Success: Order_" + orderId;
}

场景验证：当两者同时配置时，职责被严格划分。触发限流时，由 handleRateLimit 响应；触发业务异常时，由 handleBusinessFailure 响应。这种模式是生产环境中最推荐的做法，能够针对不同的故障类型返回更精确的降级策略。

4. 全局兜底与异常豁免机制

@GetMapping("/global/{orderId}")
@SentinelResource(
    value = "fetch_order_global",
    defaultFallback = "globalDefaultFallback",
    fallbackClass = OrderResilienceHandler.class,
    exceptionsToIgnore = { IllegalArgumentException.class }
)
public String fetchWithGlobalFallback(@PathVariable("orderId") Long orderId) {
    if (orderId <= 0) {
        // 此异常被豁免，直接抛出
        throw new IllegalArgumentException("Invalid Order ID");
    }
    if (orderId % 3 == 0) {
        throw new RuntimeException("Unknown internal error");
    }
    return "Success: Order_" + orderId;
}

// 在 OrderResilienceHandler 中新增：
public static String globalDefaultFallback(Throwable ex) {
    log.error("Global fallback triggered", ex);
    return "Service temporarily unavailable.";
}

场景验证：

• 当传入负数触发 IllegalArgumentException 时，由于该异常被配置在 exceptionsToIgnore 中，系统不会进入任何降级逻辑，而是直接将异常抛给全局异常处理器。
• 当传入 3 的倍数触发 RuntimeException 时，请求进入 globalDefaultFallback 返回通用兜底提示。
• 若在此基础上同时配置 fallback 和 defaultFallback，系统会优先匹配 fallback。defaultFallback 仅作为没有专属 fallback 方法时的最后防线。
• 若同时配置 blockHandler 和 defaultFallback，限流依然由 blockHandler 优先拦截，defaultFallback 仅负责处理漏网的业务异常。