Skip to content

Spring @Configuration proxy modes

The @Configuration annotation in Spring Framework supports a proxyBeanMethods attribute which determines how the container interacts with @Bean methods, defining the trade-off between internal dependency management and startup performance.^[600-developer-spring-springboot2.md]

Configuration Modes

The behavior of @Configuration classes is primarily controlled by the proxyBeanMethods attribute, which offers two distinct modes: Full and Lite.

Full Mode (proxyBeanMethods = true)

When proxyBeanMethods is set to true, the configuration class is treated as a "Full" configuration.^[600-developer-spring-springboot2.md] In this mode, Spring creates a CGLIB proxy for the configuration class at startup.^[600-developer-spring-springboot2.md] This proxy intercepts calls to @Bean methods to ensure that the same bean instance is returned every time a method is invoked within the class.^[600-developer-spring-springboot2.md] This guarantees that references between beans are strictly single-instance, meaning if one bean method calls another, the result is the cached singleton rather than a new object.^[600-developer-spring-springboot2.md]

Key characteristics: * Guaranteed Singletons: Ensures that invoking a @Bean method multiple times (even directly within the class) returns the exact same component instance.^[600-developer-spring-springboot2.md] * Required for Dependencies: This mode is mandatory when there are inter-bean dependencies, i.e., when one @Bean method relies on another @Bean method to function correctly.^[600-developer-spring-springboot2.md]

Lite Mode (proxyBeanMethods = false)

When proxyBeanMethods is set to false, the configuration class operates in "Lite" mode.^[600-developer-spring-springboot2.md] In this state, Spring does not create a CGLIB proxy for the configuration class.^[600-developer-spring-springboot2.md] Consequently, @Bean methods behave like plain factory methods; every invocation of the method results in the creation of a new component instance.^[600-developer-spring-springboot2.md]

Key characteristics: * No Inter-method Calls: This mode assumes that there are no direct dependencies between @Bean methods within the class.^[600-developer-spring-springboot2.md] * Performance Benefit: By skipping the proxy generation, the application startup process is faster and reduces complexity.^[600-developer-spring-springboot2.md]

Default Behavior and Selection

The default mode for @Configuration classes is typically the Full mode (proxyBeanMethods = true) to ensure standard Spring behavior where bean references are singletons.^[600-developer-spring-springboot2.md] Developers should generally choose Lite mode only when the configuration class contains simple beans with no dependencies on each other, allowing for a lighter runtime footprint.^[600-developer-spring-springboot2.md]

Sources

^[600-developer-spring-springboot2.md]