feign-reactive

The project is divided into several modules depending on your runtime and reactive library requirements:

• feign-reactor-core: Base classes and interfaces for implementing alternative reactor Feign implementations.
• feign-reactor-webclient: Implementation based on Spring WebClient.
• feign-reactor-cloud: Spring Cloud implementation (supports Ribbon/Hystrix).
• feign-reactor-java11: Implementation based on Java 11 HttpClient (high performance).
• feign-reactor-rx2: Rx2 compatible implementation (depends on feign-reactor-webclient).
• feign-reactor-rx3: Rx3 compatible implementation (depends on feign-reactor-webclient).
• feign-reactor-jetty: Experimental Reactive Jetty client implementation. Offers higher reactivity by streaming request bodies and receiving responses before the request body is fully sent.
• feign-reactor-spring-cloud-starter: Single dependency for Spring Cloud applications (uses WebClient by default).
• feign-reactor-bom: Maven BOM for simplified dependency management.

For RxJava users, define your Feign API interface where every method:

• May accept Flowable, Observable, Single, or Maybe as a request body.
• Must return Flowable, Observable, Single, or Maybe.

Use Rx2ReactiveFeign or Rx3ReactiveFeign to build the client.

@Headers({"Accept: application/json"})
public interface IcecreamServiceApi {

  @RequestLine("GET /icecream/flavors")
  Flowable<Flavor> getAvailableFlavors();

  @RequestLine("POST /icecream/orders")
  @Headers("Content-Type: application/json")
  Single<Bill> makeOrder(IceCreamOrder order);

  @RequestLine("POST /icecream/bills/pay")
  @Headers("Content-Type: application/json")
  Single<Long> payBill(Bill bill);
}

// Build the client
IcecreamServiceApi client = Rx2ReactiveFeign
    .builder()
    .target(IcecreamServiceApi.class, "http://www.icecreame.com");

// Execute nonblocking requests
Flowable<Flavor> flavors = client.getAvailableFlavors();

To use the Reactor-based implementation, define your Feign API interface where every method:

• May accept org.reactivestreams.Publisher as a request body.
• Must return reactor.core.publisher.Mono or reactor.core.publisher.Flux.

Use WebReactiveFeign (for WebClient), JettyReactiveFeign, or Java11ReactiveFeign to build the client.

@Headers({ "Accept: application/json" })
public interface IcecreamServiceApi {

  @RequestLine("GET /icecream/flavors")
  Flux<Flavor> getAvailableFlavors();

  @RequestLine("POST /icecream/orders")
  @Headers("Content-Type: application/json")
  Mono<Bill> makeOrder(IceCreamOrder order);

  @RequestLine("POST /icecream/bills/pay")
  @Headers("Content-Type: application/json")
  Mono<Void> payBill(Publisher<Bill> bill);
}

// Build the client
IcecreamServiceApi client = WebReactiveFeign
            .<IcecreamServiceApi>builder()
            .target(IcecreamServiceApi.class, "http://www.icecreame.com");

// Execute nonblocking requests
Flux<Flavor> flavors = client.getAvailableFlavors();

For Spring Cloud 2.2.0+ environments, it is highly recommended to use the cloud2 module (CircuitBreaker + LoadBalancer) instead of the legacy cloud module.

Setup: Add the feign-reactor-cloud module to your classpath and exclude the legacy feign-reactor-cloud (if applicable/necessary for your dependency tree).

Global Toggle Properties:

• reactive.feign.loadbalancer.enabled: Disable loadbalancer configuration.
• reactive.feign.circuit.breaker.enabled: Disable circuit breaker configuration.

Configuration via Beans:

• LoadBalancer: Define a ReactiveLoadBalancer.Factory bean in your client configuration.
• CircuitBreaker: Use a ReactiveFeignCircuitBreakerFactory bean, or a ReactiveCircuitBreakerFactory combined with a ReactiveFeignCircuitBreakerCustomizer bean.

New Retry Properties (Cloud2): Unlike the legacy module, LoadBalancer in Cloud2 does not have a direct retry configuration, but you can use:

• retryOnSame: Number of retries for the same server.
• retryOnNext: Number of retries for the next server.

You have two primary ways to add headers to your requests:

1. ReactiveHttpRequestInterceptor: Use this for dynamic headers, such as extracting an authentication token from the Reactor subscriberContext.
2. @RequestHeader parameter: Use the standard Feign @RequestHeader annotation on specific method parameters to pass a single header or a map of headers.

// Using an interceptor to add a static header and a dynamic header from context
ReactiveFeignBuilder
    .addRequestInterceptor(ReactiveHttpRequestInterceptors.addHeader("Cache-Control", "no-cache"))
    .addRequestInterceptor(request -> Mono
            .subscriberContext()
            .map(ctx -> ctx
                    .<String>getOrEmpty("authToken")
                    .map(authToken -> {
                      MultiValueMapUtils.addOrdered(request.headers(), "Authorization", authToken);
                      return request;
                    })
                    .orElse(request)));