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.

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

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).

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

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:

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

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

@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 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.