Mastering Spring Cloud OpenFeign: Configuration, Customization, and Best Practices

Environment

Spring Cloud 3.1.5

1. Overview

Spring Cloud OpenFeign is a declarative, template‑based HTTP client that simplifies remote calls; developers can invoke remote services with the same syntax as local method calls, while OpenFeign builds request templates from annotated interfaces and injects dynamic proxies into the Spring context.

2. OpenFeign Configuration

2.1 Enable Feature

Add the starter dependency:

groupId: org.springframework.cloud
artifactId: spring-cloud-starter-openfeign

Enable it in the application:

@SpringBootApplication
@EnableFeignClients
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Example client:

@FeignClient(name = "demoService")
public interface DemoFeign {
    @GetMapping("/info/{id}")
    public Object info(@PathVariable("id") Integer id);
}

The name attribute defines the client name used by Spring Cloud LoadBalancer; an optional url can specify an absolute endpoint.

2.2 Custom Configuration

Specify a custom configuration class:

@FeignClient(name = "demoService", configuration = DemoConfiguration.class)
public interface DemoFeign {}

By default Spring Cloud OpenFeign registers the following beans:

Decoder : ResponseEntityDecoder – decodes response bodies.

Encoder : SpringEncoder – encodes request bodies.

Logger : Slf4jLogger – logs Feign activity.

MicrometerCapability – enabled when feign-micrometer and a MeterRegistry are present.

CachingCapability – enabled with @EnableCaching (can be disabled via feign.cache.enabled).

Contract : SpringMvcContract – processes Spring MVC annotations on the interface.

Feign.Builder : FeignCircuitBreaker.Builder – adds circuit‑breaker support when present.

Client : uses FeignBlockingLoadBalancerClient if LoadBalancer is on the classpath; otherwise the default JDK URLConnection client.

Beans that can be overridden in a custom configuration include:

Logger.Level

Retryer

ErrorDecoder

Request.Options

Collection<RequestInterceptor>

SetterFactory

QueryMapEncoder

Capability

(e.g., MicrometerCapability, CachingCapability)

Dynamic name & URL

@FeignClient(name = "${pack.demo.name}", url = "${pack.demo.url}")
public interface DemoFeign {}

pack:
  demo:
    name: demoService
    url: http://localhost:8088/demos

Timeout configuration

feign:
  client:
    config:
      default:
        connectTimeout: 5000
        readTimeout: 5000

All interfaces default to a 5‑second timeout.

Dynamic timeout refresh

feign:
  client:
    refresh-enabled: true

When @RefreshScope is enabled, connectTimeout and readTimeout can be updated via /actuator/refresh.

Custom log level

Via configuration file:

logging:
  level:
    '[com.pack.feign.test.DemoFeign]': debug

Or per‑client:

feign:
  client:
    config:
      demoService:
        logger-level: full

Bean definition:

@Bean
public Logger.Level loggerLevel() {
    return Logger.Level.FULL;
}

Custom retryer

@Bean
public Retryer feignRetryer() {
    Retryer.Default retryer = new Retryer.Default(100, SECONDS.toMillis(1), 2);
    return retryer;
}

Custom request interceptor

@Bean
public RequestInterceptor headerRequestInterceptor() {
    return template -> {
        template.header("X-API-TOKEN", "666666");
    };
}

Or via properties:

feign:
  client:
    config:
      demoService:
        request-interceptors:
        - com.pack.feign.HeaderRequestInterceptor

Manual Feign client creation

public class DemoController {
    private DemoFeign demoFeign;
    @Autowired
    public DemoController(Client client, Encoder encoder, Decoder decoder) {
        this.demoFeign = Feign.builder()
            .client(client)
            .encoder(encoder)
            .decoder(decoder)
            .requestInterceptor(new HeaderRequestInterceptor("X-API-TOKEN", "666666"))
            .target(DemoFeign.class, "http://localhost:8088/demos");
    }
}

Service fallback

Requires Spring Cloud CircuitBreaker on the classpath:

@FeignClient(
    url = "http://localhost:8088/demos",
    name = "demoService",
    configuration = DemoFeignConfiguration.class,
    fallback = DemoFeignFallback.class)
public interface DemoFeign {
    @GetMapping("/info/{id}")
    public Object info(@PathVariable("id") Integer id);
}

public class DemoFeignFallback implements DemoFeign {
    public Object info(Integer id) {
        return "default - " + id;
    }
}

Fallback factory

@FeignClient(
    url = "http://localhost:8088/demos",
    name = "demoService",
    configuration = DemoFeignConfiguration.class,
    fallbackFactory = DemoFeignFallbackFactory.class)
public interface DemoFeign {}

public class DemoFeignFallbackFactory implements FallbackFactory<DemoFeign> {
    static class DemoFeignFallback implements DemoFeign {
        private final Throwable cause;
        public DemoFeignFallback(Throwable cause) { this.cause = cause; }
        @Override
        public Object info(Integer id) {
            return "接口调用异常 - " + this.cause.getMessage();
        }
    }
    @Override
    public DemoFeign create(Throwable cause) {
        return new DemoFeignFallback(cause);
    }
}

Caching support

Enable caching with @EnableCaching and annotate methods:

@FeignClient(...)
public interface DemoFeign {
    @GetMapping("/info/{id}")
    @Cacheable(cacheNames = "demo-cache", key = "#id")
    public Object info(@PathVariable("id") Integer id);
}

Feign inheritance

@FeignClient(url = "http://localhost:8088/users", name = "userService")
public interface UserService {
    @GetMapping("/{id}")
    User getUser(@PathVariable("id") Long id);
}

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

Note: Feign interfaces should not be shared between server and client, and class‑level @RequestMapping is no longer supported.

Request/response compression

feign:
  compression:
    request:
      enabled: true
    response:
      enabled: true

Control MIME types and minimum request size:

feign:
  compression:
    request:
      mime-types: text/xml,application/xml,application/json
      min-request-size: 2048

Reactive client support

OpenFeign does not support Spring WebClient; the recommended reactive alternative is feign-reactive:

<dependency>
  <groupId>com.playtika.reactivefeign</groupId>
  <artifactId>feign-reactor-webclient</artifactId>
  <version>3.3.0</version>
</dependency>

@ReactiveFeignClient(
    url = "http://localhost:8088/demos",
    name = "demoReactorFeign",
    fallback = DemoReactorFeignFallback.class,
    configuration = {DemoReactorFeignConfig.class})
public interface DemoReactorFeign {
    @GetMapping("/info/{id}")
    public Mono<Object> info(@PathVariable("id") Integer id);
}

Conclusion

Spring Cloud OpenFeign provides a powerful, declarative way to call remote services, reducing boilerplate networking code and allowing developers to focus on business logic. Its extensibility—through custom beans, fallback mechanisms, caching, compression, and reactive alternatives—makes it a versatile choice for building resilient microservice architectures.