Simplifying OpenFeign Calls in Local Development via Custom Bean Registration

In everyday development, OpenFeign is widely used for inter‑service calls, but its default load‑balancing can cause problems when a local service and a Docker‑based service are registered in Nacos with different IP ranges. Requests may be routed to the Docker instance, leading to network failures.

Problem Overview

When a local FeignClient calls serviceA , the built‑in load balancer may select either the local instance (reachable via 192.168.x.x ) or the Docker instance (reachable via 172.17.x.x ). The two subnets cannot communicate, causing request failures.

One quick fix is to add a url attribute to the @FeignClient annotation, but this requires code changes before each deployment and is error‑prone.

Feign Internals

Feign clients are created by @EnableFeignClients , which imports FeignClientsRegistrar . This registrar uses ImportBeanDefinitionRegistrar to generate BeanDefinition objects for each interface annotated with @FeignClient . The generated bean is a dynamic proxy that delegates HTTP calls via FeignInvocationHandler .

Custom ImportBeanDefinitionRegistrar

To avoid hard‑coding URLs, we implement a custom LocalFeignClientRegistrar that also implements ImportBeanDefinitionRegistrar , ResourceLoaderAware , EnvironmentAware , and BeanFactoryAware . It scans the configured base package for @FeignClient interfaces, validates that they are interfaces, and extracts annotation attributes.

@Override
public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata, BeanDefinitionRegistry registry) {
    // scanning logic ...
    for (BeanDefinition candidate : candidateComponents) {
        // verify interface and retrieve attributes
        registerFeignClient(registry, metadata, attributes);
    }
}

During registration we build a Feign.Builder using beans for Client , Encoder , Decoder , and Contract that are already defined in the Spring context.

Feign.Builder builder = Feign.builder()
    .encoder(encoder)
    .decoder(decoder)
    .contract(contract);

The target URL is chosen in the following order:

If addressMapping (defined in LocalFeignProperties ) contains a URL for the service name, use it with a simple Client.Default .

Else, if the original @FeignClient annotation provides a url , use that.

Otherwise, fall back to the service name with a LoadBalancerFeignClient for standard Ribbon load‑balancing.

Object target;
if (StringUtils.hasText(serviceUrl)) {
    target = builder.client(defaultClient).target(clazz, serviceUrl);
} else if (StringUtils.hasText(originUrl)) {
    target = builder.client(defaultClient).target(clazz, originUrl);
} else {
    target = builder.client(ribbonClient).target(clazz, "http://" + name);
}

The resulting BeanDefinition is registered with the Spring container, marked as primary when required, and can be lazily initialized.

Configuration and Usage

Add the auto‑configuration class to spring.factories and include the dependency spring-cloud-starter-openfeign . In application.yml enable the feature and provide the mapping:

feign:
  local:
    enable: true
    basePackage: com.service
    addressMapping:
      hydra-service: http://127.0.0.1:8088
      trunks-service: http://127.0.0.1:8099

Define a Feign client interface as usual; the url value in the annotation will be overridden by the mapping when the feature is enabled.

@FeignClient(value = "hydra-service", contextId = "hydra-serviceA", url = "http://127.0.0.1:8099/")
public interface ClientA {
    @GetMapping("/test/get")
    String get();
    @GetMapping("/test/user")
    User getUser();
}

Running the application shows the package scan, the overridden URL, and successful responses from the local service.

Conclusion

The presented approach removes the need to modify @FeignClient annotations for local debugging, reduces manual errors, and illustrates how Spring’s extension points (ImportBeanDefinitionRegistrar, BeanDefinitionBuilder, and conditional configuration) can be leveraged to customize framework behavior.