Overview

Without circuit breaking, invoking a downstream service that is offline results in prolonged HTTP timeouts or immediate exceptions—often leading to cascading failures across dependent serviecs. This article demonstrates how to integrate Sentinel with OpenFeign to provide graceful degradation and circuit-breaking behavior for remote calls.

In this setup, order-service consumes an interface from account-service via Feign. When account-service is unavailable, the fallback mechanism returns predefined responses instead of propagating errors.

Implementation Steps

1. Define a Fallback Implementation Class

Create a class implementing the Feign client interface to serve as the fallback handler. It must be a valid Spring-managed bean and implement all methods declared in the Feign interface:

package com.example.order.fallback;

import com.example.common.dto.AccountDTO;
import com.example.common.result.ResultData;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

import java.math.BigDecimal;

@Slf4j
@Component
public class AccountServiceFallback implements AccountClient {

    @Override
    public ResultData<String> createAccount(AccountDTO account) {
        return ResultData.fail("Service unavailable: account creation failed");
    }

    @Override
    public ResultData<String> removeAccount(String code) {
        return ResultData.fail("Service unavailable: account deletion failed");
    }

    @Override
    public ResultData<String> updateAccount(AccountDTO account) {
        return ResultData.fail("Service unavailable: account update failed");
    }

    @Override
    public ResultData<AccountDTO> fetchByCode(String code) {
        log.warn("Fallback triggered for account lookup: {}", code);
        AccountDTO stub = new AccountDTO();
        stub.setAccountCode("STUB_001");
        stub.setAccountName("Fallback Account");
        return ResultData.success(stub);
    }

    @Override
    public ResultData<String> deductBalance(String code, BigDecimal amount) {
        return ResultData.fail("Service unavailable: balance deduction failed");
    }
}

2. Provide a Fallback Factory

To inject contextual exception details into the fallback instance, use FallbackFactory. This allows access to the original failure cause:

package com.example.order.fallback;

import com.example.common.exception.ServiceUnavailableException;
import feign.hystrix.FallbackFactory;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

@Component
@Slf4j
public class AccountServiceFallbackFactory implements FallbackFactory<AccountClient> {

    @Override
    public AccountClient create(Throwable cause) {
        log.error("Feign call to account-service failed", cause);
        return new AccountServiceFallback();
    }
}

3. Annotate the Feign Client

Link the fallback factory to the Feign interface using fallbackFactory:

import org.springframework.cloud.openfeign.FeignClient;
import com.example.order.fallback.AccountServiceFallbackFactory;

@FeignClient(
    name = "account-service",
    url = "${account.service.url:http://localhost:8081}",
    fallbackFactory = AccountServiceFallbackFactory.class
)
public interface AccountClient {
    // method declarations omitted for brevity
}

4. Enable Sentinel Integration for Feign

Activate Sentinel-based circuit breaking globally in application.yml:

feign:
  sentinel:
    enabled: true

Ensure spring-cloud-starter-alibaba-sentinel and spring-cloud-starter-openfeign are included in dependencies.

Common Startup Issue & Resolution

After applying the above changes, startup may fail with:

Caused by: java.lang.IllegalStateException: No fallbackFactory instance of type ...

This occurs because Spring Boot’s component scanning does not include the package where AccountServiceFallbackFactory resides. By default, only packages under the main application class are scanned.

If AccountServiceFallbackFactory lives in com.example.order.fallback, but the main @SpringBootApplication class is in com.example.order, no issue arises. However, if the fallback logic resides in a shared module (e.g., com.example.common.fallback) outside the auto-scanned hierarchy, explicit configuration is required.

Fix it by extending the base scan packages:

@SpringBootApplication(scanBasePackages = {
    "com.example.order",
    "com.example.common.fallback"
})
public class OrderApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderApplication.class, args);
    }
}

Avoid over-broad scanning (e.g., "com") — prefer precise, minimal package declarations.

Behavior Validation

Once deployed and configured correctly:

• When account-service is down, Feign calls return fallback responses immediately.
• Sentinel monitors invocation metrics (QPS, latency, error rate) and opens the circuit when thresholds are exceeded.
• During circuit open state, all requetss route directly to fallback without attempting real calls.
• After the configured timeout, Sentinel transitions to half-open state and allows a limited number of probes to assess recovery.

This prevents thread pool exhaustion and avoids propagating failures — effectively mitigating the snowflake effect in distributed systems.