Sentinel Annotation

In modern microservice architectures, applications constantly face unpredictable traffic surges, downstream service degradation, and potential cascade failures. As a powerful open-source traffic governance component originated by Alibaba, Sentinel delivers robust capabilities including rate limiting, circuit breaking, system adaptive protection, and hot-spot parameter control.

While developers can programmatically define protected resources using the SphU.entry() API, Sentinel also provides the @SentinelResource annotation. This declarative approach allows developers to seamlessly mark resources and configure fallback logic, significantly reducing code invasiveness and improving maintainability.
The @SentinelResource annotation is used to identify resources and wire up custom handling logic. Its most commonly utilized attributes include:

• value: The resource name (mandatory). All traffic control, throttling, and circuit-breaking rules configured in the Sentinel Dashboard are bound to this identifier.
• entryType: The traffic direction, which can be set to either EntryType.IN (inbound traffic) or EntryType.OUT (outbound traffic). It defaults to OUT.
• blockHandler: The name of the method designated to handle BlockException. This method is invoked when a request is blocked due to flow control, concurrency limits, circuit breaking, or system protection rules.
• fallback: The name of the method designated to handle general business exceptions. It is triggered when the protected method throws any exception other than a BlockException.
• defaultFallback: A global default fallback method, ideal for scenarios where multiple resources share the same fallback logic.
• blockHandlerClass / fallbackClass: Specifies external utility classes where the block handler or fallback methods reside. Note that these external methods must be declared as static.
• exceptionsToIgnore: Specifies exception types that should be ignored by the fallback mechanism, allowing them to propagate naturally without triggering fallback behavior.

Quick Start Guide

To get started with the annotation-based approach, you need to include the Sentinel AspectJ dependency in your project. If you are already utilizing Spring Cloud Alibaba via spring-cloud-starter-alibaba-sentinel, this dependency is automatically imported. Otherwise, add it manually:

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-annotation-aspectj</artifactId>
    <version>1.8.6</version>
</dependency>

For standard Spring applications, you also need to explicitly register the Sentinel resource aspect bean:

@Configuration
public class SentinelAspectConfiguration {
    @Bean
    public SentinelResourceAspect sentinelResourceAspect() {
        return new SentinelResourceAspect();
    }
}

Business Integration Example

Below is a practical implementation demonstrating how to protect a service method using @SentinelResource alongside custom block handlers and fallback methods:

@Service
public class OrderService {

    @SentinelResource(
        value = "queryOrder",
        blockHandler = "queryOrderBlock",
        fallback = "queryOrderFallback"
    )
    public Order queryOrder(Long orderId) {
        if (orderId == null) {
            throw new IllegalArgumentException("Order ID cannot be null");
        }
        return orderDao.findById(orderId);
    }

    // Handles traffic blocking caused by Sentinel rules (BlockException)
    public Order queryOrderBlock(Long orderId, BlockException ex) {
        log.warn("Request blocked by Sentinel rules: {}", ex.getClass().getSimpleName());
        return Order.degradedOrder(orderId);
    }

    // Handles unexpected business exceptions
    public Order queryOrderFallback(Long orderId, Throwable throwable) {
        log.error("Business exception occurred during order query: {}", throwable.getMessage());
        return Order.fallbackOrder(orderId);
    }
}

By leveraging @SentinelResource, developers can cleanly separate core business logic from resilience handling, ensuring high availability and resilience across distributed systems with minimal boilerplate code.