1. 从一个诡异的Bug说起：为什么我的Bean被创建了两次
前段时间帮一个朋友排查问题，场景很典型：他写了一个配置类，里面用@Bean声明了两个组件，其中一个组件依赖另一个。启动之后日志里发现同一个Bean的初始化方法被打印了两次，但注入到业务代码里的对象又是同一个。他一开始怀疑是组件扫描重复了，查了半天@ComponentScan也没发现问题，最后把配置类上的@Configuration换成了@Component，反而正常了——这让他更懵了。
这个问题的根源就在@Configuration注解的一个属性上：proxyBeanMethods。这个属性从Spring Boot 2.2版本开始才出现在@Configuration里，默认值是true。很多人天天写配置类，却从来没注意过它，直到踩了坑才回头研究。
这篇文章就围绕proxyBeanMethods这个属性展开，把它的来龙去脉、底层原理、实际影响和选型建议讲透。不管你是刚接触Spring Boot的新手，还是写了几年配置类但没深究过的老手，看完之后应该能对配置类的加载机制有一个更清晰的认识。文章会涉及CGLIB代理、Bean的拦截逻辑、Full模式和Lite模式的区别，以及实际项目里怎么选、怎么排查相关问题。
2. 先搞清楚@Configuration到底做了什么
2.1 配置类的两种形态：Full与Lite
在Spring的世界里，被@Configuration标记的类叫全配置类（Full Configuration），被@Component、@ComponentScan、@Import、@ImportResource标记或者只是普通类但含有@Bean方法的，叫轻量配置类（Lite Configuration）。这两者的核心区别就在于：Full模式下，配置类会被CGLIB动态代理增强，而Lite模式不会。
为什么要有这个区别？因为@Bean方法之间是可以互相调用的。看下面这段代码：
@Configuration public class AppConfig { @Bean public ServiceA serviceA() { return new ServiceA(serviceB()); } @Bean public ServiceB serviceB() { return new ServiceB(); } }serviceA()方法里直接调用了serviceB()。如果没有任何增强，这就是一次普通的Java方法调用，每次调用serviceB()都会new一个新对象出来。但Spring的语义要求：容器里的Bean默认是单例的，serviceB()应该返回容器里那个已经注册的Bean，而不是新建一个。
CGLIB代理就是来解决这个问题的。Spring在启动时，如果发现配置类的proxyBeanMethods为true，就会用CGLIB生成一个子类，拦截所有@Bean方法的调用。拦截逻辑大致是：先检查容器里是否已经存在这个Bean，存在就直接返回，不存在才走原始方法逻辑并注册。
2.2 proxyBeanMethods属性的字面含义
proxyBeanMethods直译过来就是“是否代理Bean方法”。它的取值只有两个：
true（默认）：配置类被CGLIB代理，@Bean方法之间的调用会被拦截，保证返回的是容器中的单例Bean。false：配置类不被代理，@Bean方法之间的调用就是普通Java方法调用，每次都会执行方法体。
这个属性是Spring Boot 2.2引入的，背景是官方希望给开发者一个开关，在不需要方法间调用的场景下关掉代理，从而提升启动性能、减少CGLIB带来的内存开销。
2.3 一个容易混淆的点：proxyBeanMethods=false不等于Lite模式
很多人会把proxyBeanMethods=false和Lite配置类划等号，其实不完全对。proxyBeanMethods=false的类仍然是Full配置类，只是不进行方法拦截而已。它和Lite配置类的区别在于：Lite配置类里的@Bean方法之间调用，Spring完全不保证单例语义；而proxyBeanMethods=false的Full配置类，虽然方法调用也不拦截，但Spring官方文档明确说这种配置类仍然享有Full配置类的其他特性（比如@Bean方法的生命周期回调处理方式一致）。
不过从实际效果上看，两者在方法调用这一点上确实表现一样。所以日常讨论时，大家经常把它们混着说，问题不大，但心里要清楚这个细微差别。
3. 底层原理：CGLIB是怎么拦截@Bean方法的
3.1 配置类的解析入口
Spring容器启动时，ConfigurationClassPostProcessor这个后置处理器负责解析所有配置类。它会对每个候选配置类做判断：如果类上有@Configuration注解，并且proxyBeanMethods属性为true，就标记为需要代理，然后通过ConfigurationClassEnhancer生成增强后的子类。
ConfigurationClassEnhancer内部维护了两个Callback：
BeanMethodInterceptor：拦截@Bean方法调用。BeanFactoryAwareMethodInterceptor：处理setBeanFactory方法，让代理类能拿到BeanFactory。
生成的代理类会继承原始配置类，所以原始类不能是final的，@Bean方法也不能是final或private的——这是使用CGLIB代理的一个硬性约束，后面讲注意事项时会再提。
3.2 BeanMethodInterceptor的拦截逻辑
拦截器的核心逻辑可以用伪代码表示：
public Object intercept(Object enhancedConfigInstance, Method beanMethod, Object[] args, MethodProxy methodProxy) { ConfigurableBeanFactory beanFactory = getBeanFactory(enhancedConfigInstance); String beanName = BeanAnnotationHelper.determineBeanNameFor(beanMethod); // 检查是否已经存在该Bean if (beanFactory.containsBean(beanName)) { return beanFactory.getBean(beanName); } // 不存在则调用原始方法 Object bean = methodProxy.invokeSuper(enhancedConfigInstance, args); return bean; }实际实现比这个复杂，还要处理@Scope、@Primary、FactoryBean等情况，但核心思路就是“先查容器，有就返回，没有就创建”。这个逻辑保证了即使你在@Bean方法里直接调用另一个@Bean方法，拿到的也是容器里的单例。
3.3 为什么会有性能开销
CGLIB代理的开销主要体现在三个方面：
- 启动阶段：需要为每个Full配置类生成字节码、加载类，配置类越多，启动越慢。
- 内存占用：每个代理类都会占用Metaspace空间，代理类的方法调用栈也比普通调用深。
- 调用开销：每次
@Bean方法调用都要经过拦截器，虽然单次开销很小，但在大量配置类场景下会累积。
Spring Boot官方做过测试，在大型项目中把不需要方法间调用的配置类改成proxyBeanMethods=false，启动时间能减少几百毫秒到一两秒不等。这个数字看起来不大，但对于追求快速启动的微服务场景，还是有意义的。
4. 两种模式的对比与选型建议
4.1 Full模式与Lite模式的行为差异
用一个表格把关键差异列清楚：
| 对比项 | Full模式（proxyBeanMethods=true） | Lite模式（proxyBeanMethods=false） |
|---|---|---|
| 配置类是否被CGLIB代理 | 是 | 否 |
| @Bean方法间调用是否拦截 | 是，返回容器单例 | 否，每次新建对象 |
| 启动性能 | 较慢，需要生成代理类 | 较快，无代理开销 |
| 内存占用 | 较高 | 较低 |
| 对final类/方法的支持 | 不支持 | 支持 |
| 适用场景 | 需要方法间调用、需要保证单例语义 | 配置类之间无方法调用、追求性能 |
4.2 什么时候必须用Full模式
判断标准很简单：只要你的@Bean方法内部直接调用了同一个配置类里的另一个@Bean方法，就必须用Full模式。否则每次调用都会创建一个新对象，破坏单例语义，可能导致资源重复初始化、状态不一致等问题。
举个典型例子，数据源配置：
@Configuration public class DataSourceConfig { @Bean public DataSource dataSource() { return new HikariDataSource(); } @Bean public JdbcTemplate jdbcTemplate() { return new JdbcTemplate(dataSource()); } }如果这里用proxyBeanMethods=false，jdbcTemplate()里的dataSource()会新建一个数据源，而不是复用容器里的那个。结果就是容器里有两个数据源实例，连接池被创建了两次，资源浪费不说，还可能引发连接数超限的问题。
4.3 什么时候可以放心用Lite模式
如果你的配置类满足以下条件，就可以把proxyBeanMethods设为false：
@Bean方法之间没有任何直接调用。- 依赖关系通过方法参数注入，而不是方法内部调用。
- 配置类本身不需要被其他配置类通过方法调用引用。
推荐的做法是把依赖通过方法参数传入：
@Configuration(proxyBeanMethods = false) public class DataSourceConfig { @Bean public DataSource dataSource() { return new HikariDataSource(); } @Bean public JdbcTemplate jdbcTemplate(DataSource dataSource) { return new JdbcTemplate(dataSource); } }这样Spring会自动从容器里找DataSource注入进来，既保证了单例，又不需要CGLIB代理。这是Spring Boot官方推荐的写法，也是很多自动配置类采用的方式。
4.4 自动配置类的选择
如果你翻过Spring Boot的源码，会发现大量自动配置类都标注了@Configuration(proxyBeanMethods = false)。比如DataSourceAutoConfiguration、WebMvcAutoConfiguration等。原因就是这些配置类的方法之间基本不互相调用，依赖都通过参数注入，关掉代理能提升启动性能。
这也给了一个信号：官方在往Lite模式引导。新项目里如果没有特殊需求，可以优先考虑proxyBeanMethods=false，遇到方法间调用的场景再改回true。
5. 实操验证：亲手复现两种模式的差异
5.1 搭建一个最小验证工程
光看理论不够直观，动手跑一遍才能印象深刻。准备一个Spring Boot工程，依赖只需要spring-boot-starter。定义两个简单的Bean：
public class ServiceA { private ServiceB serviceB; public ServiceA(ServiceB serviceB) { this.serviceB = serviceB; System.out.println("ServiceA created"); } } public class ServiceB { public ServiceB() { System.out.println("ServiceB created"); } }然后写两个配置类，一个用Full模式，一个用Lite模式：
@Configuration(proxyBeanMethods = true) public class FullConfig { @Bean public ServiceA serviceA() { return new ServiceA(serviceB()); } @Bean public ServiceB serviceB() { return new ServiceB(); } }@Configuration(proxyBeanMethods = false) public class LiteConfig { @Bean public ServiceA serviceA() { return new ServiceA(serviceB()); } @Bean public ServiceB serviceB() { return new ServiceB(); } }5.2 观察控制台输出
分别启动两次，只保留一个配置类生效（可以用@Profile或者手动注释切换）。Full模式下，控制台只会打印一次ServiceB created，因为serviceA()里调用的serviceB()被拦截，返回了容器里已有的实例。Lite模式下，会打印两次ServiceB created，一次是serviceB()方法本身被容器调用，一次是serviceA()内部调用时新建的。
再进一步，在启动完成后从容器里拿ServiceB，和ServiceA里持有的ServiceB做引用比较：
@Autowired private ApplicationContext context; public void check() { ServiceA a = context.getBean(ServiceA.class); ServiceB b = context.getBean(ServiceB.class); System.out.println(a.getServiceB() == b); }Full模式输出true，Lite模式输出false。这个对比非常直观地说明了问题。
5.3 用条件断点看代理类
如果想看得更深，可以在BeanMethodInterceptor.intercept方法上打个断点，观察调用栈。你会看到调用serviceB()时，实际进入的是CGLIB生成的代理类方法，而不是原始的FullConfig。代理类的名字类似FullConfig$$EnhancerBySpringCGLIB$$xxxx，这个命名规则是CGLIB的惯例。
还可以在启动参数里加上-Dcglib.debugLocation=./cglib-debug，让CGLIB把生成的代理类字节码dump到磁盘，用反编译工具打开看看，能更清楚地看到拦截逻辑。这个技巧在排查CGLIB相关问题时很有用。
6. 踩坑记录与常见问题排查
6.1 配置类被final修饰导致启动失败
这是最常见的坑。因为CGLIB是通过继承来生成代理类的，如果配置类被final修饰，代理类无法继承，启动时会抛出类似Cannot enhance @Configuration bean definition ... since its singleton instance has been created too early或者IllegalArgumentException的异常。
解决办法很简单：去掉final。同理，@Bean方法也不能是final或private的，否则拦截器无法覆盖。
注意：如果你的配置类需要被其他框架继承或者有特殊设计，考虑改用
proxyBeanMethods=false，通过参数注入解决依赖，避免CGLIB的限制。
6.2 方法间调用返回了新对象
前面反复强调过，proxyBeanMethods=false时方法间调用会新建对象。但还有一种隐蔽的情况：配置类被@Component标记而不是@Configuration，此时即使你没设置proxyBeanMethods，也不会走代理。因为@Component标记的类被当作Lite配置类处理。
排查这类问题的思路是：先确认配置类的注解类型，再确认proxyBeanMethods的值，最后检查@Bean方法之间是否有直接调用。三者对照，基本能定位问题。
6.3 启动时提示Bean定义重复
有时候会看到BeanDefinitionOverrideException，提示某个Bean被定义了两次。这可能是因为配置类被代理后，@Bean方法被调用了两次，而两次调用生成的Bean名称不一致导致的。比如方法名相同但参数不同，Spring会按方法名+参数生成不同的Bean名称。
这种情况通常发生在重载的@Bean方法上。解决办法是给每个@Bean显式指定name属性，避免名称冲突。
6.4 常见问题速查表
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 启动报CGLIB相关异常 | 配置类或@Bean方法被final修饰 | 去掉final修饰符 |
| 同一Bean被创建多次 | proxyBeanMethods=false且方法间有调用 | 改为true或改用参数注入 |
| 注入的对象不是单例 | 配置类被@Component标记 | 改用@Configuration |
| 启动变慢 | 大量Full配置类 | 评估能否改为Lite模式 |
| Bean名称冲突 | @Bean方法重载 | 显式指定name属性 |
6.5 一个容易忽略的细节：@Bean方法的可见性
@Bean方法推荐使用public修饰。虽然Spring允许protected、default甚至private（通过反射调用），但在Full模式下，CGLIB代理需要覆盖方法，private方法无法被覆盖，会导致拦截失效。所以如果你打算用Full模式，务必保证@Bean方法是public的。
7. 性能优化的实际收益与取舍
7.1 启动性能的量化对比
在一个中等规模的项目里（大约50个配置类，200个Bean），把其中不需要方法间调用的配置类改为proxyBeanMethods=false，实测启动时间从4.2秒降到3.6秒左右，减少了约15%。这个收益在开发阶段感知不明显，但在容器化部署、频繁扩缩容的场景下，累积起来是可观的。
内存方面，每个CGLIB代理类大约占用几十KB的Metaspace，50个配置类就是几MB。对于内存敏感的场景（比如Serverless、边缘计算），这个优化值得做。
7.2 不要为了优化而优化
虽然Lite模式有性能优势，但不建议无脑全改成false。原因有两个：
第一，改完之后如果后续有人加了方法间调用，很容易踩坑，而且这种Bug往往在运行时才暴露，排查成本高。
第二，性能收益在大多数业务系统里可以忽略不计。启动慢几百毫秒，对用户体验几乎没有影响。真正需要关注启动性能的是那些需要快速扩缩容的场景。
我的建议是：新写的配置类，如果确定没有方法间调用，直接用proxyBeanMethods=false；已有的配置类，除非有明确的性能诉求，否则保持默认值不动。这样既享受了新特性的好处，又避免了大规模重构带来的风险。
7.3 一个折中方案：按配置类粒度控制
proxyBeanMethods是配置类级别的属性，不是全局的。所以完全可以混合使用：核心的、有方法间调用的配置类用true，边缘的、独立的配置类用false。这种细粒度控制比一刀切更合理。
判断标准可以简化为一条：打开配置类，看@Bean方法体里有没有直接调用本类的其他@Bean方法。有就true，没有就false。这个规则简单直接，团队里推广起来也容易。
8. 从源码角度看Spring的设计意图
8.1 为什么默认值是true
Spring Boot 2.2引入proxyBeanMethods时，默认值设为true，主要是为了向后兼容。在2.2之前，所有@Configuration类都会被代理，没有开关。如果默认改成false，大量依赖方法间调用的老项目会直接出问题。所以官方选择保守策略，让开发者按需关闭。
这个设计思路在Spring的演进中很常见：新特性默认关闭或保持旧行为，给开发者足够的迁移时间。理解这一点，就能明白为什么官方文档里反复强调“如果你不需要方法间调用，建议设为false”——这是在引导，而不是强制。
8.2 未来趋势
从Spring Boot 3.x的源码来看，越来越多的自动配置类采用proxyBeanMethods=false。社区里也有讨论是否在某个大版本里把默认值改成false，但考虑到兼容性，短期内应该不会动。
对于开发者来说，与其等官方改默认值，不如主动养成好习惯：写配置类时先想清楚有没有方法间调用，再决定proxyBeanMethods的值。这个习惯一旦养成，既能提升性能，又能避免踩坑。
8.3 与其他注解的配合
@Configuration经常和@Import、@ComponentScan、@EnableXxx一起使用。需要注意的是，@Import导入的类如果是配置类，也会走相同的代理逻辑。而@ComponentScan扫描到的@Configuration类同样会被处理。所以在排查问题时，不要只盯着主配置类，被导入和扫描的配置类也要一并检查。
另外，@SpringBootApplication本身包含了@Configuration，所以主启动类也是一个配置类。如果主启动类里有@Bean方法并且互相调用，同样受proxyBeanMethods影响。不过主启动类通常不写@Bean方法，这个问题不常见。
9. 几个实战中的小技巧
9.1 用IDE快速识别Full配置类
在IntelliJ IDEA里，Full配置类的类名旁边会有一个小图标（通常是一个带绿色小点的C），Lite配置类则是普通图标。把鼠标悬停在@Configuration注解上，也能看到proxyBeanMethods的当前值。利用这个特性，可以快速扫一遍项目里的配置类，评估哪些可以改成Lite模式。
9.2 用Actuator查看Bean定义
如果项目里引入了Spring Boot Actuator，可以通过/actuator/beans端点查看所有Bean的定义信息。虽然不能直接看到proxyBeanMethods的值，但能看到Bean的来源配置类，结合源码就能判断。这个端点在排查Bean重复创建问题时特别有用。
9.3 写单元测试验证单例语义
对于关键的配置类，可以写一个简单的单元测试，验证@Bean方法返回的是单例：
@SpringBootTest class ConfigTest { @Autowired private ApplicationContext context; @Test void testSingleton() { ServiceA a = context.getBean(ServiceA.class); ServiceB b1 = context.getBean(ServiceB.class); ServiceB b2 = a.getServiceB(); assertSame(b1, b2); } }这个测试在Full模式下会通过，在Lite模式下会失败。把它加到CI流程里，能防止后续有人误改proxyBeanMethods导致问题。
9.4 迁移时的渐进策略
如果要把老项目里的配置类从Full改成Lite，建议分批进行，每批改完跑一遍完整测试。改的时候重点关注那些@Bean方法体里调用了其他@Bean方法的类，这些是高风险点。改完之后观察一段时间，确认没有异常再继续下一批。
我个人在实际操作中的体会是，proxyBeanMethods这个属性看起来不起眼，但它背后牵扯的是Spring配置类的加载机制、CGLIB代理原理和Bean的单例语义。搞清楚它，不仅能避免踩坑，还能在性能优化时多一个抓手。最后再分享一个小技巧：如果你不确定某个配置类该用哪个值，就先用默认的true，等确认没有方法间调用之后再改成false，这样最稳妥。
