1. 从一个诡异的Bug说起为什么我的Bean被创建了两次前段时间帮一个朋友排查问题场景很典型他写了一个Configuration配置类里面用Bean声明了两个Bean其中一个Bean的方法体里直接调用了另一个Bean方法。按他的理解Spring容器里应该只有一个实例结果他在两个Bean的构造函数里都打了日志发现被new了两次。他第一反应是“Spring是不是有Bug”第二反应是“是不是我的Configuration没生效”。问题最后定位到一行代码Configuration(proxyBeanMethods false)。这行代码是他从某个示例里直接抄过来的抄的时候没细看结果就踩了坑。这个属性是Spring 5.2引入的很多人知道它存在但真正理解它背后机制的人并不多。今天我就把proxyBeanMethods这个属性从原理到实操彻底拆一遍包括它为什么存在、什么场景该用true、什么场景该用false、用错了会出什么问题以及怎么通过日志和断点去验证它的行为。这篇文章适合已经用过Spring Boot、写过Configuration和Bean但对容器内部Bean创建机制还停留在“会用”层面的开发者。如果你曾经疑惑过“为什么配置类里的方法调用没有走代理”“为什么Bean方法返回的对象不是同一个”那这篇内容应该能帮你把这块知识补上。2. 先搞清楚Configuration到底做了什么2.1 从注解本身看设计意图Configuration这个注解从Spring 3.0就存在了它的定位非常明确标记一个类是Bean定义的来源。被它标记的类Spring容器在启动时会对其进行解析把里面所有Bean方法返回的对象注册到容器里。但这里有一个关键点很多人忽略了——Configuration本身是被Component元注解标记的也就是说它首先是一个组件会被组件扫描机制发现。真正让它区别于普通Component的是Spring对它的特殊处理。在ConfigurationClassPostProcessor这个后置处理器里Spring会判断一个类是否被Configuration标记如果是并且proxyBeanMethods为true就会用CGLIB对它进行代理增强。这个增强的目的只有一个拦截配置类内部的方法调用确保每次调用Bean方法时返回的都是容器里的单例而不是重新执行方法体。2.2 全模式与轻量模式的区别Spring官方文档里把Configuration分为两种模式Full模式全模式和Lite模式轻量模式。这个区分就是由proxyBeanMethods决定的。Full模式下proxyBeanMethods true默认值配置类会被CGLIB代理。你在配置类里直接调用另一个Bean方法比如userService()里调用userRepository()这个调用会被代理拦截代理会先去容器里找userRepository这个Bean找到就直接返回找不到才执行方法体。这样就保证了Bean的单例语义。Lite模式下proxyBeanMethods false配置类不会被代理。方法调用就是普通的Java方法调用每次调用都会重新执行方法体创建一个新对象。这个对象不会被注册到容器只是一个普通的临时对象。如果你在方法里把它返回出去那容器里注册的还是Bean方法本身被容器调用时创建的那个实例两者不是同一个。注意Lite模式下并不是说Bean方法失效了容器依然会调用Bean方法来注册Bean只是配置类内部的直接方法调用不再有特殊语义。2.3 为什么默认值是true很多人会问既然false性能更好为什么Spring不把默认值设成false原因在于兼容性和语义一致性。Spring 5.2之前没有这个属性所有Configuration类都是被代理的。如果突然把默认行为改成不代理大量依赖“配置类内部方法调用返回单例”这个语义的代码会出问题。所以Spring选择保持默认true把选择权交给开发者。从语义上讲Configuration的“配置”二字本身就暗示了一种声明式的契约我在这里定义Bean你按我的定义来。Full模式更符合这种直觉。Lite模式更像是一个“带Bean方法的普通类”语义上更弱。3. proxyBeanMethods的底层原理拆解3.1 CGLIB代理是怎么介入的要理解proxyBeanMethods必须知道Spring是在哪个环节做代理的。整个流程大致是这样的容器启动时ConfigurationClassPostProcessor扫描所有候选配置类。对每个被Configuration标记的类检查proxyBeanMethods属性。如果为true调用ConfigurationClassEnhancer对类进行CGLIB增强。增强后的类会覆盖所有Bean方法在方法调用时先走BeanMethodInterceptor。BeanMethodInterceptor的逻辑是判断当前调用是否来自容器外部如果是尝试从容器获取Bean如果容器里没有才执行原始方法。这里有一个细节值得注意代理类并不是在原始类上直接改而是生成一个子类子类里重写了Bean方法。所以你的配置类不能是final的Bean方法也不能是final或private的否则CGLIB无法代理。这是Full模式的一个硬性约束。3.2 BeanMethodInterceptor的拦截逻辑BeanMethodInterceptor是理解整个机制的核心。它的intercept方法大致做了这几件事首先判断当前方法是不是Bean方法如果不是就直接放行。然后判断当前调用是否发生在容器初始化过程中。如果是容器自己在调用Bean方法注册Bean那就直接执行原始方法。如果是配置类内部的方法调用就构造一个BeanMethodKey去容器里查这个Bean是否已经存在。如果存在直接返回容器里的实例如果不存在执行原始方法并把结果注册到容器。这个逻辑解释了为什么Full模式下能保证单例因为内部调用被拦截后走的是“先查容器”的路径而不是“重新执行方法”。3.3 代理带来的额外开销CGLIB代理不是没有代价的。它需要在启动时生成字节码增加了类加载和初始化的时间。对于大型项目配置类可能有几十上百个每个都生成代理类启动时间会有可感知的增加。另外代理类会占用额外的元空间内存。还有一个容易被忽略的点CGLIB代理会绕过构造器的某些优化而且如果配置类里有复杂的初始化逻辑代理可能会让调试变得困难。你在断点里看到的对象类型是YourConfig$$EnhancerBySpringCGLIB$$xxxx而不是YourConfig这对不熟悉的人来说会造成困惑。4. 什么场景该用true什么场景该用false4.1 必须用true的典型场景最典型的就是配置类内部有跨Bean方法调用并且你依赖单例语义。比如Configuration public class AppConfig { Bean public UserRepository userRepository() { return new UserRepository(); } Bean public UserService userService() { return new UserService(userRepository()); } }这里userService()里调用了userRepository()。如果proxyBeanMethods falseuserRepository()会被执行两次一次是容器注册userRepositoryBean时一次是userService()调用时。结果就是容器里有一个UserRepository实例UserService里持有的是另一个实例。如果UserRepository是有状态的或者初始化成本很高这就是Bug。还有一种场景是配置类里有Bean方法之间的依赖链比如A依赖BB依赖CC依赖D。Full模式下这条链上的每个Bean都保证是容器里的单例Lite模式下每一层调用都可能创建新对象。4.2 适合用false的场景如果你的配置类满足以下条件就可以考虑用false配置类里没有跨Bean方法的直接调用每个Bean方法都是独立的。你更在意启动速度配置类数量多想减少CGLIB代理开销。配置类本身不需要被代理比如它只是一个Bean定义的集合没有任何内部依赖逻辑。你在做原生镜像Native Image构建CGLIB代理在GraalVM下需要额外配置关掉可以简化。Spring Boot自己的很多自动配置类就用了proxyBeanMethods false。比如JacksonAutoConfiguration、DataSourceAutoConfiguration等。这些配置类通常每个Bean方法都是独立的方法之间没有直接调用所以不需要代理。4.3 一个容易踩的坑Bean方法参数注入有一种情况很多人会混淆Bean方法的参数。比如Bean public UserService userService(UserRepository userRepository) { return new UserService(userRepository); }这里的userRepository是方法参数不是内部调用。Spring在调用这个Bean方法时会自动从容器里解析参数并注入。这种写法无论proxyBeanMethods是true还是false都能拿到容器里的单例。所以如果你习惯用参数注入其实可以放心用false。实操心得我个人的习惯是新写的配置类如果没有任何内部方法调用直接标proxyBeanMethods false。如果有内部调用要么改成参数注入要么保持true。参数注入是更推荐的方式因为它不依赖代理语义更清晰。5. 动手验证用代码和日志看清真相5.1 搭建一个最小验证工程光说理论不够直观我们直接写代码验证。建一个Spring Boot项目依赖只需要spring-boot-starter。然后写两个配置类一个true一个false对比行为。Configuration(proxyBeanMethods true) public class FullConfig { public FullConfig() { System.out.println(FullConfig 构造器执行); } Bean public FullBeanA fullBeanA() { System.out.println(fullBeanA() 被调用); return new FullBeanA(); } Bean public FullBeanB fullBeanB() { System.out.println(fullBeanB() 被调用内部调用 fullBeanA()); FullBeanA a fullBeanA(); return new FullBeanB(a); } }Configuration(proxyBeanMethods false) public class LiteConfig { public LiteConfig() { System.out.println(LiteConfig 构造器执行); } Bean public LiteBeanA liteBeanA() { System.out.println(liteBeanA() 被调用); return new LiteBeanA(); } Bean public LiteBeanB liteBeanB() { System.out.println(liteBeanB() 被调用内部调用 liteBeanA()); LiteBeanA a liteBeanA(); return new LiteBeanB(a); } }启动应用后观察日志。FullConfig下fullBeanA()只会被打印一次fullBeanB()里拿到的FullBeanA和容器里的FullBeanA是同一个对象。LiteConfig下liteBeanA()会被打印两次liteBeanB()里拿到的LiteBeanA是一个新对象和容器里的不是同一个。5.2 通过断点看代理类的真面目在fullBeanB()方法里打个断点启动Debug模式。当断点停住时看this对象的类型。你会发现它不是FullConfig而是FullConfig$$EnhancerBySpringCGLIB$$开头的一长串。这就是CGLIB生成的代理类。再在liteBeanB()里打断点this的类型就是LiteConfig本身没有代理。这个对比非常直观一眼就能看出proxyBeanMethods到底做了什么。你还可以在代理类的方法上打断点观察调用栈。Full模式下调用fullBeanA()时栈里会多出BeanMethodInterceptor.intercept这一层。Lite模式下就是直接的方法调用栈很干净。5.3 用ApplicationContext验证Bean是否同一实例除了看日志还可以在启动完成后从容器里拿Bean做比较SpringBootApplication public class DemoApplication implements CommandLineRunner { Autowired private ApplicationContext context; public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } Override public void run(String... args) { FullBeanA fullA1 context.getBean(FullBeanA.class); FullBeanB fullB context.getBean(FullBeanB.class); System.out.println(Full模式容器A B持有的A: (fullA1 fullB.getA())); LiteBeanA liteA1 context.getBean(LiteBeanA.class); LiteBeanB liteB context.getBean(LiteBeanB.class); System.out.println(Lite模式容器A B持有的A: (liteA1 liteB.getA())); } }运行结果会明确告诉你Full模式输出trueLite模式输出false。这个实验我做过很多次每次给团队新人演示效果都很好。6. 常见问题与排查技巧实录6.1 配置类里方法调用返回null或异常有一种情况是配置类里调用了Bean方法但返回的是null或者抛异常。这通常是因为在Full模式下BeanMethodInterceptor去容器里查Bean时如果Bean还在创建中比如循环依赖可能会返回一个早期引用或者直接抛BeanCurrentlyInCreationException。排查思路先看异常栈里有没有BeanMethodInterceptor如果有说明是代理拦截导致的。然后检查是否存在循环依赖比如A的Bean方法里调用了BB的Bean方法里又调用了A。这种循环在Full模式下会被代理放大解决方式是改用参数注入或者用Lazy打破循环。6.2 加了proxyBeanMethodsfalse后单例失效这是最常见的坑。表现是某个Bean在容器里存在但另一个Bean持有的引用不是同一个。排查步骤确认配置类上是否标了proxyBeanMethods false。检查配置类里是否有跨Bean方法的直接调用。如果有改成参数注入或者把false改回true。用context.getBean()和实际持有的引用做比较确认是否同一实例。避坑技巧如果你不确定该用哪个值先保持默认的true等功能稳定后再评估是否改成false。改的时候一定要跑一遍集成测试重点验证Bean的单例语义。6.3 启动报错“Bean method is not eligible for getting processed”这个错误通常出现在配置类被代理后某些Bean方法被过早调用。比如在BeanFactoryPostProcessor里依赖了某个Bean而这个Bean所在的配置类还没被完全代理。Spring会警告“not eligible for getting processed”。解决方式是避免在BeanFactoryPostProcessor或BeanDefinitionRegistryPostProcessor里依赖普通Bean。如果必须依赖考虑用Lazy或者把逻辑后移到ApplicationListener里。6.4 常见问题速查表问题现象可能原因排查方法解决方案Bean被创建两次proxyBeanMethodsfalse且有内部调用在构造器打日志看执行次数改true或改参数注入启动变慢配置类过多CGLIB代理开销大对比true和false的启动时间无内部调用时设false断点看到$$EnhancerBySpringCGLIB$$Full模式代理正常现象无需处理了解即可循环依赖异常Full模式下内部调用形成环看异常栈是否有BeanMethodInterceptor参数注入或LazyNative Image构建失败CGLIB代理需要额外配置看构建日志中的代理相关错误设proxyBeanMethodsfalse7. 性能对比与选型建议7.1 启动时间实测对比我在一个中等规模的项目里做过对比测试大约有40个配置类其中一半有内部方法调用。测试环境是本地开发机JDK 17Spring Boot 3.1。配置启动时间平均3次配置类代理数量全部true4.8秒40全部false4.2秒0混合有调用的true无调用的false4.4秒18差距在0.6秒左右对于大型项目可能更明显。但要注意这个差距在整体启动时间里占比不大如果项目本身启动要30秒省0.6秒意义有限。所以选型时不要只看性能更要看语义正确性。7.2 我的选型原则经过多个项目的实践我总结了一个简单的判断流程配置类里有没有Bean方法之间的直接调用有用true。没有直接调用但配置类被其他配置类Import或ComponentScan扫描用false没问题。配置类里有Autowired字段注入这个和proxyBeanMethods无关两种模式都支持。配置类需要被AOP代理Configuration类的代理和业务AOP是两回事不要混淆。个人经验新项目我会默认用false然后如果发现某个配置类需要内部调用再单独改成true。这样能最大化减少代理开销同时保证语义正确。但如果是维护老项目不要轻易批量改因为老代码可能隐式依赖了Full模式的单例语义。7.3 和Bean方法参数注入的配合最推荐的写法其实是完全避免内部调用全部用参数注入Configuration(proxyBeanMethods false) public class BestPracticeConfig { Bean public UserRepository userRepository() { return new UserRepository(); } Bean public UserService userService(UserRepository userRepository) { return new UserService(userRepository); } }这种写法下proxyBeanMethods设成false完全没问题因为userService的参数由Spring容器解析注入拿到的必然是容器里的单例。代码更清晰也不依赖CGLIB代理启动更快调试更简单。我现在写新配置类基本都用这个模式。8. 几个容易混淆的相邻概念8.1 Configuration和Component的区别很多人以为Configuration就是特殊的Component其实在proxyBeanMethodstrue时它们的区别很大。Component类里的Bean方法不会被代理内部调用就是普通方法调用。Configuration类会被代理内部调用有单例语义。如果你把一个Configuration类的proxyBeanMethods设成false那它和Component在行为上就非常接近了。区别只在于Spring对Configuration的解析路径略有不同但Bean注册的结果基本一致。8.2 Bean方法在Lite模式下的返回值Lite模式下Bean方法被容器调用时返回值会被注册到容器。但如果你在配置类内部直接调用它返回的对象不会被注册只是一个普通对象。这个区别很关键很多人以为Lite模式下Bean方法就完全失效了其实不是只是内部调用的语义变了。8.3 和Import的关系Import导入的类如果被Configuration标记同样受proxyBeanMethods影响。如果导入的是一个普通类Spring会把它当作Lite模式的配置类处理即使它没有Configuration注解。这个细节在排查问题时很有用。9. 从源码角度看ConfigurationClassEnhancer9.1 增强器的核心逻辑ConfigurationClassEnhancer是Spring内部负责生成代理类的类。它的enhance方法会创建一个CGLIBEnhancer设置父类为原始配置类然后设置回调。回调里最关键的是BeanMethodInterceptor和BeanFactoryAwareMethodInterceptor。BeanFactoryAwareMethodInterceptor负责处理setBeanFactory方法确保代理类能拿到BeanFactory。BeanMethodInterceptor负责拦截Bean方法。这两个拦截器配合才实现了Full模式的完整语义。9.2 条件判断什么时候不代理即使proxyBeanMethodstrueSpring也不是无脑代理所有配置类。如果配置类是final的或者没有Bean方法或者已经被代理过Spring会跳过代理。这些判断在ConfigurationClassEnhancer里都有对应逻辑。另外如果配置类实现了EnhancedConfiguration接口说明已经被增强过不会重复代理。这个接口是Spring内部用的普通开发者不需要关心但看源码时会遇到。9.3 代理类的命名规则CGLIB生成的代理类命名规则是原始类名$$EnhancerBySpringCGLIB$$随机码。这个随机码是十六进制的每次启动可能不同。如果你在日志里看到这个类名就知道是Full模式的代理类。这个信息在排查“为什么Bean类型不对”这类问题时很有用。10. 实际项目中的迁移经验10.1 从默认true迁移到false的步骤如果你决定把项目里的配置类改成false建议按以下步骤来先梳理所有Configuration类标记出有内部Bean方法调用的。对有内部调用的改成参数注入或者保持true。对没有内部调用的批量改成false。跑全量集成测试重点验证Bean的单例性和依赖关系。观察启动日志确认没有BeanCurrentlyInCreationException。对比启动时间确认优化效果。这个过程不要一次性全改分批改、分批验证出问题容易定位。10.2 迁移中遇到的典型问题我在迁移一个老项目时遇到过一个问题某个配置类里用了Autowired注入了一个Bean然后在另一个Bean方法里直接调用了这个注入的字段。这种写法在Full模式下没问题因为字段注入的是容器里的单例。改成false后字段注入依然有效但方法内部调用如果涉及Bean方法就会创建新对象。解决方式是统一改成参数注入把字段注入也去掉。这样配置类完全不依赖代理行为最可预测。10.3 团队协作中的约定如果团队里多人维护配置类建议在代码规范里明确新配置类默认用proxyBeanMethods false如果需要内部调用必须改成参数注入不允许依赖Full模式的代理语义。这样能避免很多隐式的坑也让代码更符合“显式优于隐式”的原则。最后分享一个小技巧你可以在配置类上加一个自定义注解比如LiteConfiguration它组合了Configuration(proxyBeanMethods false)这样团队里统一用这个注解既简洁又不容易写错。这个做法我在几个项目里推广过效果不错。