Understanding the Dynamic Proxy Mechanism of Spring Cloud OpenFeign

OpenFeign originated from the Netflix Feign project, which was initially part of Netflix OSS and later contributed to the open‑source community, becoming the Spring Cloud OpenFeign component we use today.

OpenFeign provides a declarative way to perform remote calls, dramatically simplifying the programming experience; a single method call can replace the multi‑line code required by WebClient.

String response = helloWorldService.hello("Vincent Y.");

The helloWorldService reference is a special interface annotated with @FeignClient . Its definition looks like this:

@FeignClient(value = "hello-world-serv")
public interface HelloWorldService {
    @PostMapping("/sayHello")
    String hello(String guestName);
}

During application startup, OpenFeign scans the classpath for interfaces marked with @FeignClient , generates a dynamic proxy for each, and registers the proxy as a Spring bean.

The dynamic proxy converts interface method invocations into HTTP requests that are sent to the target service.

OpenFeign Dynamic Proxy

At initialization, OpenFeign creates a proxy class that handles all remote calls made through the annotated interface. The following diagram illustrates the proxy creation process:

Steps 1‑3 occur during project startup; step 4 (the actual remote call) happens at runtime.

The startup process includes:

Project Loading: @EnableFeignClients acts as a switch, importing FeignClientsRegistrar via Spring’s @Import annotation.

Package Scanning: FeignClientsRegistrar scans the specified packages for @FeignClient interfaces and creates FeignClientFactoryBean instances.

Annotation Parsing: FeignClientFactoryBean extracts service name, path, and fallback configuration, then triggers dynamic proxy creation handled by ReflectiveFeign .

Dynamic Proxy Construction: ReflectiveFeign builds a MethodHandler for each method, encapsulating HTTP method, URL, headers, etc., and creates a Java InvocationHandler proxy that implements the interface.

The MethodHandler relies on the Contract abstraction to translate Spring MVC annotations into metadata. For Spring MVC, SpringMvcContract is used.

Key parts of SpringMvcContract that parse method‑level annotations (e.g., @RequestMapping , @GetMapping , @PostMapping ) are shown below:

// Parse RequestMapping on FeignClient method
protected void processAnnotationOnMethod(MethodMetadata data, Annotation methodAnnotation, Method method) {
    // omitted code ...
    if (!RequestMapping.class.isInstance(methodAnnotation) &&
        !methodAnnotation.annotationType().isAnnotationPresent(RequestMapping.class)) {
        return;
    }
    RequestMapping methodMapping = findMergedAnnotation(method, RequestMapping.class);
    RequestMethod[] methods = methodMapping.method();
    if (methods.length == 0) {
        methods = new RequestMethod[] { RequestMethod.GET };
    }
    checkOne(method, methods, "method");
    data.template().method(Request.HttpMethod.valueOf(methods[0].name()));
    // parse path, produces, consumes, headers ...
}

Even if a method uses @GetMapping or @PostMapping , OpenFeign can still resolve it because those annotations are meta‑annotated with @RequestMapping :

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@RequestMapping(method = RequestMethod.GET)
public @interface GetMapping {
    // ...
}

Summary

OpenFeign addresses the complexity of remote service calls by generating a dynamic proxy that turns simple interface method invocations into HTTP requests, separating business logic from communication concerns.

Final Note (Support the Author)

If this article helped you, please like, view, share, or bookmark it. Your support motivates the author to keep producing quality content.

The author also offers premium knowledge resources (e.g., Spring full‑stack series, massive data sharding, DDD micro‑services) via a paid “knowledge planet” community.

Follow the public account "码猿技术专栏" for more technical articles and community discussions.