Spring Cloud OpenFeign

https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html/
Admin
Spring Cloud OpenFeign is a declarative REST client for Spring Boot applications that simplifies...
Tokens:12,700
Snippets:100
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Spring Boot application with @EnableFeignClients

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Example Spring Boot application class annotated with @SpringBootApplication and @EnableFeignClients to enable Feign clients. The main method runs the SpringApplication.

```java
@SpringBootApplication
@EnableFeignClients
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}
```

--------------------------------

### Feign client interface StoreClient.java

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Example Feign client interface named StoreClient, annotated with @FeignClient("stores"). It defines methods for GET, POST, and DELETE requests using Spring MVC annotations, including a method with a Pageable parameter and a method with a path variable.

```java
@FeignClient("stores")
public interface StoreClient {
    @RequestMapping(method = RequestMethod.GET, value = "/stores")
    List<Store> getStores();

    @RequestMapping(method = RequestMethod.GET, value = "/stores")
    Page<Store> getStores(Pageable pageable);

    @RequestMapping(method = RequestMethod.POST, value = "/stores/{storeId}", consumes = "application/json")
    Store update(@PathVariable("storeId") Long storeId, Store store);

    @RequestMapping(method = RequestMethod.DELETE, value = "/stores/{storeId:\\d+}")
    void delete(@PathVariable Long storeId);
}
```

--------------------------------

### Feign HATEOAS CollectionModel example

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Feign client method that returns a CollectionModel, enabled when HATEOAS support is active (spring-boot-starter-hateoas or spring-boot-starter-data-rest).

```java
@FeignClient("demo")
public interface DemoTemplate {

    @GetMapping(path = "/stores")
    CollectionModel<Store> getStores();
}
```

--------------------------------

### Feign @MatrixVariable example

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Example of @MatrixVariable usage. The path segment placeholder must match the matrix variable name (matrixVars) on the client side.

```java
@GetMapping("/objects/links/{matrixVars}")
Map<String, List<String>> getObjects(@MatrixVariable Map<String, List<String>> matrixVars);
```

--------------------------------

### Feign Client Interface for CircuitBreaker Configuration

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Defines a Feign client interface with a GET endpoint, used as an example for configuring circuit breakers via configuration properties.

```java
@FeignClient(url = "http://localhost:8080")
public interface DemoClient {

    @GetMapping("demo")
    String getDemo();
}
```

--------------------------------

### Feign @CollectionFormat CSV example

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Feign client method annotated with @CollectionFormat to use CSV format instead of the default EXPLODED.

```java
@FeignClient(name = "demo")
protected interface DemoFeignClient {

    @CollectionFormat(feign.CollectionFormat.CSV)
    @GetMapping(path = "/test")
    ResponseEntity performRequest(String test);

}
```

--------------------------------

### Implement LoadBalancerFeignRequestTransformer to add headers

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Define a LoadBalancerFeignRequestTransformer bean to transform the load-balanced HTTP request using the selected ServiceInstance. The example adds X-ServiceId and X-InstanceId headers. Multiple transformers are applied in bean definition order; use LoadBalancerFeignRequestTransformer.DEFAULT_ORDER to specify order.

```java
@Bean
public LoadBalancerFeignRequestTransformer transformer() {
    return new LoadBalancerFeignRequestTransformer() {

        @Override
        public Request transformRequest(Request request, ServiceInstance instance) {
            Map<String, Collection<String>> headers = new HashMap<>(request.headers());
            headers.put("X-ServiceId", Collections.singletonList(instance.getServiceId()));
            headers.put("X-InstanceId", Collections.singletonList(instance.getInstanceId()));
            return Request.create(request.httpMethod(), request.url(), headers, request.body(), request.charset(),
                    request.requestTemplate());
        }
    };
}
```

--------------------------------

### Feign @SpringQueryMap example with Params class

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

The Params class defines query parameters param1 and param2. The DemoTemplate Feign client uses @SpringQueryMap to map a POJO parameter to query parameters.

```java
// Params.java
public class Params {
    private String param1;
    private String param2;

    // [Getters and setters omitted for brevity]
}
```

```java
@FeignClient("demo")
public interface DemoTemplate {

    @GetMapping(path = "/demo")
    String demoEndpoint(@SpringQueryMap Params params);
}
```

--------------------------------

### Feign client interface with @Cacheable annotation

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Example Feign client interface using @Cacheable to enable caching when @EnableCaching is used and CachingCapability is registered.

```java
public interface DemoClient {

    @GetMapping("/demo/{filterParam}")
    @Cacheable(cacheNames = "demo-cache", key = "#keyParam")
    String demoEndpoint(String keyParam, @PathVariable String filterParam);
}
```

--------------------------------

### Autowire Feign client with ObjectProvider

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Workaround for early initialization errors: autowire the Feign client with ObjectProvider instead of direct injection.

```java
@Autowired
ObjectProvider<TestFeignClient> testFeignClient;
```

--------------------------------

### Enable X-Forwarded headers with spring.cloud.loadbalancer.x-forwarded.enabled

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Enable X-Forwarded-Host and X-Forwarded-Proto support for load-balanced requests.

```properties
spring.cloud.loadbalancer.x-forwarded.enabled=true
```

--------------------------------

### Feign client with contextId fooClient

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Defines a Feign client named 'stores' with contextId 'fooClient' and custom configuration FooConfiguration. Use contextId to avoid name collision when multiple clients share the same name or url.

```java
@FeignClient(contextId = "fooClient", name = "stores", configuration = FooConfiguration.class)
public interface FooClient {
    //..
}
```

--------------------------------

### Create MicrometerCapability bean for metrics-only support

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Creates a MicrometerCapability bean for metrics-only support with Feign. Requires disabling Micrometer support via spring.cloud.openfeign.micrometer.enabled=false.

```java
@Configuration
public class FooConfiguration {
    @Bean
    public MicrometerCapability micrometerCapability(MeterRegistry meterRegistry) {
        return new MicrometerCapability(meterRegistry);
    }
}
```

--------------------------------

### Feign client with contextId barClient

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Defines a second Feign client with the same name 'stores' but different contextId 'barClient' and configuration BarConfiguration. This allows multiple clients pointing to the same server with different custom configurations.

```java
@FeignClient(contextId = "barClient", name = "stores", configuration = BarConfiguration.class)
public interface BarClient {
    //..
}
```

--------------------------------

### Enable Feign request and response compression

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Enables GZIP compression for Feign requests and responses by setting the corresponding properties to true.

```properties
spring.cloud.openfeign.compression.request.enabled=true
spring.cloud.openfeign.compression.response.enabled=true
```

--------------------------------

### Configure Feign client with application.yml properties

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Shows how to configure a Feign client named 'feignName' using Spring Cloud OpenFeign configuration properties in application.yml. Includes URL, timeouts, logger level, error decoder, retryer, default query parameters, request headers, interceptors, response interceptor, dismiss404, encoder, decoder, contract, capabilities, query map encoder, and micrometer.enabled.

```yaml
spring:
    cloud:
        openfeign:
            client:
                config:
                    feignName:
                        url: http://remote-service.com
                        connectTimeout: 5000
                        readTimeout: 5000
                        loggerLevel: full
                        errorDecoder: com.example.SimpleErrorDecoder
                        retryer: com.example.SimpleRetryer
                        defaultQueryParameters:
                            query: queryValue
                        defaultRequestHeaders:
                            header: headerValue
                        requestInterceptors:
                            - com.example.FooRequestInterceptor
                            - com.example.BarRequestInterceptor
                        responseInterceptor: com.example.BazResponseInterceptor
                        dismiss404: false
                        encoder: com.example.SimpleEncoder
                        decoder: com.example.SimpleDecoder
                        contract: com.example.SimpleContract
                        capabilities:
                            - com.example.FooCapability
                            - com.example.BarCapability
                        queryMapEncoder: com.example.SimpleQueryMapEncoder
                        micrometer.enabled: false

```

--------------------------------

### Override Feign defaults with @FeignClient configuration

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Declares a Feign client named 'stores' with a custom configuration class FooConfiguration. The client is composed from FeignClientsConfiguration plus FooConfiguration, which overrides the defaults. FooConfiguration does not need @Configuration, but if it has it, exclude it from @ComponentScan to avoid becoming the default source for feign.Decoder, feign.Encoder, feign.Contract, etc.

```java
@FeignClient(name = "stores", configuration = FooConfiguration.class)
public interface StoreClient {
    //..
}
```

--------------------------------

### Configure Feign request compression settings

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Configures Feign request compression with selective media types and a minimum request size threshold. Note that compression is not enabled when OkHttpClient is present and spring.cloud.openfeign.okhttp.enabled is true because OkHttp uses transparent compression.

```properties
spring.cloud.openfeign.compression.request.enabled=true
spring.cloud.openfeign.compression.request.mime-types=text/xml,application/xml,application/json
spring.cloud.openfeign.compression.request.min-request-size=2048
```

--------------------------------

### Enable DEBUG logging for a Feign client in application.yml

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Sets the Feign logger for the UserClient interface to DEBUG level, which is required for Feign logging to respond. Place this in application.yml.

```yaml
logging.level.project.user.UserClient: DEBUG
```

--------------------------------

### Customize MicrometerObservationCapability bean

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Customizes the MicrometerObservationCapability bean by providing your own instance with an ObservationRegistry, overriding the default auto-configured bean.

```java
@Configuration
public class FooConfiguration {
    @Bean
    public MicrometerObservationCapability micrometerObservationCapability(ObservationRegistry registry) {
        return new MicrometerObservationCapability(registry);
    }
}
```

--------------------------------

### Use placeholders in Feign client name and url

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Shows how to use placeholders in the name and url attributes of @FeignClient. The placeholders are resolved from configuration properties, allowing dynamic values.

```java
@FeignClient(name = "${feign.name}", url = "${feign.url}")
public interface StoreClient {
    //..
}
```

--------------------------------

### CircuitBreaker Configuration Properties for DemoClient

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

YAML configuration enabling circuit breakers and setting resilience4j circuit breaker and time limiter properties for the DemoClientgetDemo instance. Note the alphanumeric-ids setting to control naming.

```yaml
spring:
  cloud:
    openfeign:
      circuitbreaker:
        enabled: true
        alphanumeric-ids:
          enabled: true
resilience4j:
  circuitbreaker:
    instances:
      DemoClientgetDemo:
        minimumNumberOfCalls: 69
  timelimiter:
    instances:
      DemoClientgetDemo:
        timeoutDuration: 10s
```

--------------------------------

### Set Feign Logger.Level to FULL in a @Configuration class

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Configures the Feign Logger.Level to FULL for the client associated with this configuration, enabling detailed logging of headers, body, and metadata.

```java
@Configuration
public class FooConfiguration {
    @Bean
    Logger.Level feignLoggerLevel() {
        return Logger.Level.FULL;
    }
}
```

--------------------------------

### Create Feign Clients Manually with Feign Builder API

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Shows how to create Feign clients manually using the Feign Builder API, injecting the default FeignClientsConfiguration and configuring separate request interceptors for different clients. The autowired Contract bean supports SpringMVC annotations.

```java
@Import(FeignClientsConfiguration.class)
class FooController {

    private FooClient fooClient;

    private FooClient adminClient;

    @Autowired
    public FooController(Client client, Encoder encoder, Decoder decoder, Contract contract, MicrometerObservationCapability micrometerObservationCapability) {
        this.fooClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .addCapability(micrometerObservationCapability)
                .requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
                .target(FooClient.class, "https://PROD-SVC");

        this.adminClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .addCapability(micrometerObservationCapability)
                .requestInterceptor(new BasicAuthRequestInterceptor("admin", "admin"))
                .target(FooClient.class, "https://PROD-SVC");
    }
}
```

--------------------------------

### Enable OAuth2 support with spring.cloud.openfeign.oauth2.enabled

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Enable OAuth2 support for Feign clients. Requires the spring-boot-starter-oauth2-client dependency. When enabled and OAuth2 client context resource details are present, an OAuth2AccessTokenInterceptor bean is created that resolves an access token before each request. The token is retrieved using the OAuth2AuthorizedClientManager, using the clientRegistrationId from spring.cloud.openfeign.oauth2.clientRegistrationId if specified, otherwise the serviceId from the url host segment.

```properties
spring.cloud.openfeign.oauth2.enabled=true
```

--------------------------------

### Configure default Feign client with application.yml

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Configuration properties for the default Feign client. Sets connectTimeout and readTimeout to 5000 milliseconds and loggerLevel to basic. These properties override @Configuration bean values unless spring.cloud.openfeign.client.default-to-properties is set to false.

```yaml
spring:
    cloud:
        openfeign:
            client:
                config:
                    default:
                        connectTimeout: 5000
                        readTimeout: 5000
                        loggerLevel: basic
```

--------------------------------

### Feign client with fallbackFactory attribute

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Uses the fallbackFactory attribute to access the cause that triggered the fallback. The factory's create method receives the Throwable cause and returns a fallback instance. The fallback class implements the client interface and provides the same behavior as the simple fallback.

```java
@FeignClient(name = "testClientWithFactory", url = "http://localhost:${server.port}/",
            fallbackFactory = TestFallbackFactory.class)
protected interface TestClientWithFactory {

    @RequestMapping(method = RequestMethod.GET, value = "/hello")
    Hello getHello();

    @RequestMapping(method = RequestMethod.GET, value = "/hellonotfound")
    String getException();

}

@Component
static class TestFallbackFactory implements FallbackFactory<FallbackWithFactory> {

    @Override
    public FallbackWithFactory create(Throwable cause) {
        return new FallbackWithFactory();
    }

}

static class FallbackWithFactory implements TestClientWithFactory {

    @Override
    public Hello getHello() {
        throw new NoFallbackAvailableException("Boom!", new RuntimeException());
    }

    @Override
    public String getException() {
        return "Fixed response";
    }

}
```

--------------------------------

### Feign client with fallback attribute

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Enables a fallback for a Feign client by setting the fallback attribute to a class that implements the client interface. The fallback class must be a Spring bean. The getHello method throws NoFallbackAvailableException, while getException returns a fixed response.

```java
@FeignClient(name = "test", url = "http://localhost:${server.port}/", fallback = Fallback.class)
protected interface TestClient {

    @RequestMapping(method = RequestMethod.GET, value = "/hello")
    Hello getHello();

    @RequestMapping(method = RequestMethod.GET, value = "/hellonotfound")
    String getException();

}

@Component
static class Fallback implements TestClient {

    @Override
    public Hello getHello() {
        throw new NoFallbackAvailableException("Boom!", new RuntimeException());
    }

    @Override
    public String getException() {
        return "Fixed response";
    }

}
```

--------------------------------

### Feign inheritance with UserService, UserResource, and UserClient

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Shows Feign inheritance support: a base interface UserService defines common operations, a REST controller implements it, and a Feign client extends it. Note that @FeignClient interfaces should not be shared between server and client, and class-level @RequestMapping on @FeignClient interfaces is no longer supported.

```java
public interface UserService {

    @RequestMapping(method = RequestMethod.GET, value ="/users/{id}")
    User getUser(@PathVariable("id") long id);
}
```

```java
@RestController
public class UserResource implements UserService {

}
```

```java
package project.user;

@FeignClient("users")
public interface UserClient extends UserService {

}
```

--------------------------------

### Disable CircuitBreaker Support with Prototype Feign.Builder

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Creates a vanilla Feign.Builder with prototype scope to disable Spring Cloud CircuitBreaker support on a per-client basis.

```java
@Configuration
public class FooConfiguration {
    @Bean
    @Scope("prototype")
    public Feign.Builder feignBuilder() {
        return Feign.builder();
    }
}
```

--------------------------------

### Enable Feign client refresh with spring.cloud.openfeign.client.refresh-enabled

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Enable refresh behavior for Feign clients. By default, refresh behavior is disabled. When enabled, each Feign client is created with a refresh-scoped feign.Request.Options bean and a url wrapped under org.springframework.cloud.openfeign.RefreshableUrl, allowing properties such as connectTimeout and readTimeout to be refreshed via POST /actuator/refresh.

```properties
spring.cloud.openfeign.client.refresh-enabled=true
```

--------------------------------

### Register a custom Feign Capability bean

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Registers a custom Capability bean in a @FeignClient configuration to modify core Feign components, such as decorating the Client.

```java
@Configuration
public class FooConfiguration {
    @Bean
    Capability customCapability() {
        return new CustomCapability();
    }
}
```

--------------------------------

### Override Feign beans with @Configuration class

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Defines a @Configuration class that overrides the default Feign contract and adds a request interceptor. This replaces SpringMvcContract with feign.Contract.Default and adds a BasicAuthRequestInterceptor to the collection of RequestInterceptors.

```java
@Configuration
public class FooConfiguration {
    @Bean
    public Contract feignContract() {
        return new feign.Contract.Default();
    }

    @Bean
    public BasicAuthRequestInterceptor basicAuthRequestInterceptor() {
        return new BasicAuthRequestInterceptor("user", "password");
    }
}

```

--------------------------------

### Disable parent context inheritance for Feign clients

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Configures Feign clients to not inherit beans from the parent context by overriding inheritParentConfiguration() to return false in a FeignClientConfigurer bean.

```java
@Configuration
public class CustomConfiguration {
    @Bean
    public FeignClientConfigurer feignClientConfigurer() {
        return new FeignClientConfigurer() {
            @Override
            public boolean inheritParentConfiguration() {
                 return false;
            }
        };
    }
}
```

--------------------------------

### Feign client with primary=false

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Disables the @Primary marker on a Feign client by setting primary to false. This is useful when multiple beans of the same type exist and you do not want the Feign instance to be the primary candidate for injection.

```java
@FeignClient(name = "hello", primary = false)
public interface HelloClient {
    // methods here
}
```

--------------------------------

### Custom CircuitBreakerNameResolver to Retain Old Naming Pattern

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Provides a CircuitBreakerNameResolver bean to change the circuit breaker name pattern, allowing retention of the old pattern (feignClientName_calledMethod) introduced in 2020.0.4.

```java
@Configuration
public class FooConfiguration {
    @Bean
    public CircuitBreakerNameResolver circuitBreakerNameResolver() {
        return (String feignClientName, Target<?> target, Method method) -> feignClientName + "_" + method.getName();
    }
}
```

--------------------------------

### Disable Spring Data Jackson converters

Source: https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html

Disables automatic converters for Spring Data Page and Sort when Jackson Databind and Spring Data Commons are on the classpath.

```properties
spring.cloud.openfeign.autoconfiguration.jackson.enabled=false
```
Tokens:
Raw