Writing Client Applications
Refer to the sample apps in the “traveler” repository to follow along with the code in this topic.
To use a circuit breaker in a Spring app with a Circuit Breaker Dashboard service instance, you must add the dependencies listed in Client Dependencies to your app’s build file. Be sure to include the dependencies for Circuit Breaker Dashboard as well.
Use a Circuit Breaker
To work with a Circuit Breaker Dashboard instance, your app must include the @EnableCircuitBreaker
annotation on a configuration class.
@SpringBootApplication
@EnableDiscoveryClient
@EnableCircuitBreaker
public class AgencyApplication {
//...
To apply a circuit breaker to a method, annotate the method with @HystrixCommand
, giving the annotation the name of a fallbackMethod
.
@HystrixCommand(fallbackMethod = "getBackupGuide")
public String getGuide() {
return rest.getForObject("https://company/available", String.class);
}
The getGuide()
method uses a RestTemplate
to obtain a guide name from another app called Company, which is registered with a Service Registry instance. (See the Service Registry documentation, specifically Writing Client Applications.) The method thus relies on the Company app to return a response, and if the Company app fails to do so, calls to getGuide()
will fail. When the failures exceed the threshold, the breaker on getGuide()
will open the circuit.
While the circuit is open, the breaker redirects calls to the annotated method, and they instead call the designated fallbackMethod
. The fallback method must be in the same class and have the same method signature (i.e., have the same return type and accept the same parameters) as the annotated method. In the Agency app, the getGuide()
method on the TravelAgent
class falls back to getBackupGuide()
.
String getBackupGuide() {
return "None available! Your backup guide is: Cookie";
}
If you wish, you may also annotate fallback methods themselves with @HystrixCommand
to create a fallback chain.
Use a Circuit Breaker with a Feign Client
If you want to use the Spring Cloud OpenFeign support for Hystrix circuit breakers, you must set the feign.hystrix.enabled
property to true
. In the Feign version of the Agency app, this property is configured in application.yml
:
feign:
hystrix:
enabled: true
To provide a circuit breaker on a Feign client, you must specify a fallback class using a fallback
attribute in the @FeignClient
annotation on the client interface. Fallback methods must be Spring beans. In the Feign version of the Agency app, the CompanyClient
interface uses a CompanyFallback
class, which is annotated with @Component
:
@FeignClient(name = "company", fallback = CompanyClient.CompanyFallback.class)
public interface CompanyClient {
@RequestMapping(method = GET, value="/available")
String availableGuide();
@Component
public static class CompanyFallback implements CompanyClient {
@Override
public String availableGuide() {
return "None available!";
}
}
}
The AgencyApplication
class is annotated with @EnableFeignClients
:
@SpringBootApplication
@EnableDiscoveryClient
@EnableCircuitBreaker
@EnableFeignClients
public class AgencyApplication {
//...
If the Company app becomes unavailable or if the Agency app cannot access it, calls to the Company app through the client’s availableGuide()
method will fail. When successive failures build up to the threshold, Hystrix will open the circuit, and subsequent calls will be redirected to the fallback class’s method until the Company app is accessible again and the circuit is closed.