Simplify Feign Calls in Local Development with Custom URL Routing

OpenFeign is widely used for inter‑service calls in micro‑service projects, but developers often encounter issues when local services and Docker‑deployed services register different IP addresses in Nacos, causing load‑balancing to route requests to unreachable instances.

Problem Overview

In a typical setup, a service may have multiple instances: one registered with a Docker internal IP (e.g.,

172.17.x.x

) and another with a local LAN IP (e.g.,

192.168.x.x

). When a Feign client calls the service, the built‑in load balancer may select the Docker instance, leading to connection failures because the local network cannot reach the Docker network.

One quick fix is to specify the

url

attribute in

@FeignClient

, forcing calls to the local address, but this approach requires code changes for each client and risks forgetting to remove the URL before production deployment.

Feign Internals

The

@EnableFeignClients

annotation triggers

FeignClientsRegistrar

, which imports

FeignClientsRegistrar.class

. This registrar implements

ImportBeanDefinitionRegistrar

and registers a

BeanDefinition

for each interface annotated with

@FeignClient

. The created bean is a dynamic proxy that uses

FeignInvocationHandler

to handle HTTP requests.

Custom ImportBeanDefinitionRegistrar

To avoid hard‑coding URLs, we create a custom registrar that reads a mapping of service names to URLs from configuration and builds Feign clients manually using

Feign.builder()

. The registrar scans the specified base package for

@FeignClient

interfaces, validates them, and registers bean definitions with the appropriate client, encoder, decoder, and contract.

<code>@FeignClient(value = "serviceA", url = "http://127.0.0.1:8088/")
public interface ClientA {
    @GetMapping("/test/get")
    String get();
}</code>

The custom configuration class provides beans for

Contract

,

Client

(default and Ribbon),

Encoder

, and

Decoder

. It also reads

LocalFeignProperties

containing

enable

,

basePackage

, and

addressMapping

(service‑name → URL).

<code>@Data
@Component
@ConfigurationProperties(prefix = "feign.local")
public class LocalFeignProperties {
    private String enable;
    private String basePackage;
    private Map<String, String> addressMapping;
}</code>

During bean registration, the registrar decides the target URL in this order:

If a URL is defined in

addressMapping

, use it with the default client.

Else if the original

@FeignClient

defines a

url

, use it.

Otherwise, use the service name with a load‑balanced client.

Testing the Solution

After packaging the custom starter (including

spring-cloud-starter-openfeign

), add the dependency to your project and enable it via configuration:

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

Create a Feign client interface with any placeholder URL; the custom registrar will replace it with the mapped URL during runtime.

<code>@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();
}</code>

Running the application shows the package scanning logs and confirms that the URL from the configuration overrides the one in the annotation. Calls to the client return expected results, demonstrating that the local routing works correctly.

Conclusion

The presented approach eliminates the need to modify

@FeignClient

annotations for local debugging, reduces manual errors, and deepens understanding of Spring Cloud’s extension points. The custom starter can be disabled in production by setting

feign.local.enable

to

false

and reverting to the standard

@EnableFeignClients

configuration.