1. 为什么会盯上prepareRefresh()这个不起眼的方法很多人在读Spring源码时习惯把注意力放在refresh()这个大方法上一眼扫过去看到obtainFreshBeanFactory()、invokeBeanFactoryPostProcessors()、finishRefresh()这些名字就觉得是核心结果翻开头几步就略过了prepareRefresh()。我刚开始也是这么干的直到有一次排查一个“容器启动一半却报IllegalStateException”的问题才被迫把这四行源码看了一遍又一遍。说它不起眼是因为这个方法确实“不干重活”不创建BeanFactory不注册BeanDefinition不执行后处理器也不发布事件。它做的就是启动前的准备工作——打时间戳、改状态位、检查属性源、为后续监听器注册和早期事件收集铺路。但恰恰是这些“琐碎”的前置逻辑决定了整个refresh()流程能不能安全启动出问题时能不能给出正确的报错位置。如果你正准备啃Spring源码或者已经被ClassPathXmlApplicationContext、AnnotationConfigApplicationContext的启动过程折磨过你会发现理解prepareRefresh()是读懂整个刷新流程的基础。它是refresh()的“第一块多米诺骨牌”也是排查容器启动异常时最容易被忽略的检查点。这篇文章就把这个方法的每一行逻辑拆给你看顺带附上我实际调试中踩过的坑和总结的经验。2. prepareRefresh()在容器刷新流程中的定位与职责2.1 refresh()调度链中的第一步AbstractApplicationContext.refresh()是Spring IoC容器启动的核心入口这个方法被ConfigurableApplicationContext接口定义几乎所有想启动容器的调用最终都会落到它身上。经典实现一共有十几步我摘出最前面的一部分方便你定位prepareRefresh()的位置Override public void refresh() throws BeansException, IllegalStateException { synchronized (this.startupShutdownMonitor) { // Prepare this context for refreshing. prepareRefresh(); // Tell the subclass to refresh the internal bean factory. ConfigurableListableBeanFactory beanFactory obtainFreshBeanFactory(); // Prepare the bean factory for use in this context. prepareBeanFactory(beanFactory); try { // Allows post-processing of the bean factory in context subclasses. postProcessBeanFactory(beanFactory); // Invoke factory processors registered as beans in the context. invokeBeanFactoryPostProcessors(beanFactory); // Register bean processors that intercept bean creation. registerBeanPostProcessors(beanFactory); // Initialize message source for this context. initMessageSource(); // Initialize event multicaster for this context. initApplicationEventMulticaster(); // Check for listener beans and register them. registerListeners(); // Instantiate all remaining (non-lazy-init) singletons. finishBeanFactoryInitialization(beanFactory); // Last step: publish corresponding event. finishRefresh(); } catch (BeansException ex) { // 清理已创建的bean重置active状态 destroyBeans(); cancelRefresh(ex); throw ex; } finally { resetCommonCaches(); } } }注意refresh()整个方法体被synchronized (this.startupShutdownMonitor)锁住这意味着同一时刻只能有一个线程执行完整的启动或关闭流程。prepareRefresh()虽然逻辑不复杂但作为持锁后的第一段代码如果它执行失败后续所有步骤都不会执行也不会进入catch块里的destroyBeans()和cancelRefresh(ex)——因为异常发生在try块之外。这是很多人没留意到的细节prepareRefresh()抛出的异常不会被catch (BeansException ex)捕获它会直接向上抛出容器的状态可能停留在“半启动”状态。这种设计其实是有意的既然准备工作都没做完就不该启动容器修复流程直接把错误抛给调用方更干净。但代价是如果你在prepareRefresh()里踩了异常后面的清理逻辑都执行不到排查时要往更上层找原因。2.2 方法职责全景五件事一个不能少prepareRefresh()在Spring 5.3.x中的完整实现如下这段代码是理解本篇文章后续所有内容的主线protected void prepareRefresh() { // Switch to active. this.startupTime System.currentTimeMillis(); this.closed.set(false); this.active.set(true); if (logger.isDebugEnabled()) { if (logger.isTraceEnabled()) { logger.trace(Refreshing this); } else { logger.debug(Refreshing this.getDisplayName()); } } // Initialize any placeholder property sources in the context environment. initPropertySources(); // Validate that all properties marked as required are resolvable: // see ConfigurablePropertyResolver#setRequiredProperties getEnvironment().validateRequiredProperties(); // Store pre-refresh ApplicationListeners... if (this.earlyApplicationListeners null) { this.earlyApplicationListeners new LinkedHashSet(this.applicationListeners); } else { // Reset local application listeners to pre-refresh state. this.applicationListeners.clear(); this.applicationListeners.addAll(this.earlyApplicationListeners); } // Allow for the collection of early ApplicationEvents, // to be published once the multicaster is available... this.earlyApplicationEvents new LinkedHashSet(); }我把这五件事整理成了一个速查表后面逐个拆解步骤操作关键字段/方法失败后果1打时间戳并切换状态startupTime、closed、active状态未更新后续isActive()判断出错2打印刷新日志getDisplayName()无影响3初始化属性源initPropertySources()子类属性源缺失后续占位符解析失败4校验必填属性validateRequiredProperties()抛IllegalStateException启动失败5备份监听器并初始化事件收集器earlyApplicationListeners、earlyApplicationEvents重复刷新时监听器状态错乱早期事件丢失3. 状态管理细节startupTime、closed与active的用法3.1 启动时间戳和两个AtomicBoolean的赋值startupTime是一个long类型的字段用于记录容器启动的毫秒时间戳。它主要服务两类场景一是通过getStartupDate()暴露给外部监控二是在Spring的JMX支持中作为元数据展示。你可能觉得记录时间戳没什么技术含量但它必须在refresh()最开始就完成因为后续每一步如果能记录耗时基准点就是这里。再看状态位closed和active都是AtomicBoolean类型。prepareRefresh()里直接调用closed.set(false)和active.set(true)。为什么要用并发安全类来管理这两个布尔值因为Spring容器可能被多个线程同时访问——比如一个线程在启动另一个线程调用了close()想要关闭容器。如果没有原子性和可见性保障线程之间可能看到彼此未同步的状态导致“容器已经关闭了但启动流程还在继续”的错乱。AtomicBoolean提供了两种保证一是CAS赋值的原子性二是读写之间的happens-before关系保证了其他线程能第一时间看到最新状态。3.2 isActive()的应用场景与状态切换的时序陷阱active状态位不是摆着看的AbstractApplicationContext里有一个isActive()方法它的实现逻辑就是读取this.active.get()并且要求closed为false。实际调用isActive()的地方非常多比如在getBean()的入口、在事件广播的过程中、在ApplicationContext对外暴露生命周期时。如果容器处于“刷新中”或者“已关闭”状态某些操作就会直接拒绝执行。这里有一个时序上的坑值得注意prepareRefresh()把active设为true但此时BeanFactory还没有创建出来。如果你的自定义代码在prepareRefresh()之前调用了getBean()Spring会检查isActive()但此时返回的可能是上一次关闭后的状态。我在实际项目中就见过有人在ApplicationContext构造器里提前注入依赖结果容器都没刷新就已经开始取Bean最后拿到一堆坏引用。另外一个状态陷阱是异常回滚路径refresh()的catch块中会调用cancelRefresh(ex)这个方法的内部会把active置为false。换句话说Spring 5中的状态机是“启动过程中失败 → 标记为不活跃 → 外部通过判断isActive()决定能否继续使用”。这也解释了为什么在prepareRefresh()中主动设置active true是必须的——因为上一次失败后它可能还是false。4. 属性源初始化和必填属性校验最容易写坏的扩展点4.1 initPropertySources()的模板方法机制initPropertySources()是一个protected方法在AbstractApplicationContext中默认是空实现/** * Initialize any placeholder property sources in the context environment. */ protected void initPropertySources() { // For subclasses: do nothing by default. }它存在的意义就是让子类有机会在容器进入实质准备阶段之前向Environment中注册额外的PropertySource属性源。这本质上是一个模板方法模式父类定义了调用时机不预设任何逻辑子类按需重写。最常见的重写场景有两个。第一个是Web应用环境下的AbstractRefreshableWebApplicationContext它的initPropertySources()会调用ConfigurableWebEnvironment.initPropertySources(servletContext, servletConfig)把Servlet容器中的初始化参数合并到Spring的Environment中。第二个是自定义的上下文实现比如你希望从本地配置文件或者远端的配置中心加载某些预设参数就可以在initPropertySources()里往environment.getPropertySources()里追加自定义的PropertySource。这里要特别提醒initPropertySources()是在prepareRefresh()里被调用的这个时机点非常早早到Environment虽然在构造ApplicationContext时已经初始化但还没有经历后续任何后处理器的加工。所以在这个方法里你只能操作已经存在的PropertySource不要指望那些由BeanFactoryPostProcessor动态注册的属性源已经就位。我见过有人在这里尝试读取一个由Spring Cloud Config引入的属性结果当然是什么都读不到因为配置中心的属性源是在后置处理阶段才挂上去的。4.2 validateRequiredProperties()与setRequiredProperties()的配合逻辑prepareRefresh()的第四步是校验必填属性getEnvironment().validateRequiredProperties();这个方法最终会调用到AbstractPropertyResolver.validateRequiredProperties()它的核心逻辑是遍历requiredProperties集合逐项在当前的PropertyResolver里查找。requiredProperties本身不是凭空冒出来的而是通过ConfigurablePropertyResolver.setRequiredProperties(String...)提前注册的。这是什么意思呢假设你的应用强制要求启动时必须提供名为app.name的系统属性你可以这么写AnnotationConfigApplicationContext ctx new AnnotationConfigApplicationContext(); ctx.getEnvironment().setRequiredProperties(app.name); ctx.register(AppConfig.class); ctx.refresh();当prepareRefresh()执行到validateRequiredProperties()时如果app.name不存在会直接抛出IllegalStateException异常信息会带上缺失的属性名The following properties were declared as required but could not be resolved: [app.name]这个机制非常适合做启动期强制检查。比如多环境部署时生产环境必须指定某个profile或配置标识与其等到运行时因为占位符解析失败而出现诡异的空指针不如在启动阶段直接fail fast。通过Failed to load ApplicationContext的错误日志你第一时间就能定位是哪个配置没给全。站在“为什么这么做”的角度这里其实是在给后续的占位符解析做防御Spring在解析Value(${...})或XML里的${...}时如果属性源里找不到就拿不到值很多场景下Spring会直接报错但报错信息往往比较绕不如在容器启动最早期集中校验一次提前把相关配置问题一次性报出来。4.3 自定义Environment时容易踩的坑如果你实现了自己的Environment子类或者通过ApplicationContextInitializer替换了默认的Environment有两点要格外注意。第一getEnvironment()返回的是ConfigurableEnvironment类型如果你的自定义实现没有实现这个接口prepareRefresh()里直接调用validateRequiredProperties()会抛ClassCastException。第二Environment的初始化时机。默认情况下AnnotationConfigApplicationContext和ClassPathXmlApplicationContext都会在构造阶段调用getEnvironment()惰性创建Environment对象但在部分自定义ApplicationContext中Environment字段可能是空的。如果你在prepareRefresh()阶段的initPropertySources()里去操作env.getPropertySources()拿到一个null就白忙一场。最佳实践是如果你要扩展Environment逻辑优先走ApplicationContextInitializer或者PropertySource这类Spring官方预留的扩展机制不要轻易去重写initPropertySources()除非你清楚自己回到的是“必须在refresh早期注入属性源”这个极端场景。5. 监听器备份与早期事件收集prepareRefresh里最容易被轻视的两行逻辑5.1 earlyApplicationListeners的备份与重置机制来看prepareRefresh()的后半部分这两段逻辑处理的是ApplicationListener的注册与事件的暂存很多初学者读到这里就晕了。我先帮你梳理一下if (this.earlyApplicationListeners null) { this.earlyApplicationListeners new LinkedHashSet(this.applicationListeners); } else { this.applicationListeners.clear(); this.applicationListeners.addAll(this.earlyApplicationListeners); }applicationListeners是AbstractApplicationContext中存放“通过代码注册的监听器”的集合注意它和“通过BeanFactory注册的监听器也就是ApplicationListener类型的Bean”是两套体系。applicationListeners这个集合在refresh()过程中会被反复修改尤其是后续节点还要往里面添加从BeanFactory中发现的监听器。这段代码设置了一个“快照”机制第一次执行prepareRefresh()时earlyApplicationListeners是null于是把当时的applicationListeners完整备份到earlyApplicationListeners里。当容器第二次执行refresh()也就是热重启场景时早期监听器快照已经存在就需要把applicationListeners清空并恢复到第一次刷新前的状态。为什么要这么干因为如果容器可以重复刷新而applicationListeners里混入了上一次刷新过程中被动态添加的监听器第二次刷新时这些监听器就会重复执行。利用备份把集合重置回“pre-refresh状态”保证每次刷新都是同样的起点。使用LinkedHashSet而非普通ArrayList则是既保持了监听器注册的先后顺序又可以自动去重。5.2 earlyApplicationEvents为什么事件要被暂存紧接着后面这一行也很关键this.earlyApplicationEvents new LinkedHashSet();earlyApplicationEvents被初始化为一个空的集合它存在的意义我在第一次读到的时候也想了好一会儿。你要先理解SpringEventMulticaster的初始化时机它是在refresh()执行到initApplicationEventMulticaster()这一步才会被创建的。那么在multicaster出现之前如果有一些早期事件要被发布比如ContextRefreshedEvent之前的某些自定义事件或者在某些BeanFactoryPostProcessor执行期间ApplicationListener类型的Bean尚未注册完成事件往哪里发答案就是先暂存到earlyApplicationEvents里。这是一份“缓冲队列”在multicaster可用之前把事件都收集起来等registerListeners()执行时统一发布出去。换句话说prepareRefresh()预创建了收集容器给后续注册监听器和发布早期事件打好了底子。如果你去看ApplicationEventMulticaster不存在时Spring是怎么处理事件发布的会发现逻辑分支还挺多。但在refresh()的标准流程里真正的早期事件收集是从这里开始的。earlyApplicationEvents另一个作用是“防丢失”某些实现了ApplicationEventPublisherAware的组件在初始化时可能提前发布事件没有这层缓冲这些事件就会静默消失。5.3 早期事件什么时候被真正发布早期事件的发布时机在registerListeners()方法的末尾。这个方法属于AbstractApplicationContext执行时initApplicationEventMulticaster()已经跑完multicaster已经可用。源码关键片段如下// Publish early application events now that we have a multicaster... SetApplicationEvent earlyEventsToProcess this.earlyApplicationEvents; this.earlyApplicationEvents null; if (!CollectionUtils.isEmpty(earlyEventsToProcess)) { for (ApplicationEvent earlyEvent : earlyEventsToProcess) { getApplicationEventMulticaster().multicastEvent(earlyEvent); } }注意两个细节。第一earlyApplicationEvents被取出来后立刻被赋值为null相当于完成了使命就销毁。第二这里的发布时间点在initApplicationEventMulticaster()之后、finishBeanFactoryInitialization()之前也就是说早期事件发布时那些未被实例化的Bean监听器还不会收到通知——因为扫描出的监听器Bean虽然在这个阶段已经注册但还没有实例化完成。这个时序问题在实际排查中容易造成困惑“我监听的事件为什么没收到”答案往往是在容器刷新早期监听器Bean还不在存活状态。6. 版本差异Spring 6中的状态管理与refresh流程演进如果你读的是Spring Framework 6.x或者Spring Boot 3.x的源码会发现prepareRefresh()内部有两个值得注意的变化。第一个变化是容器的状态管理不再是两个独立的AtomicBoolean结束。Spring 6把closed、active合并进了一个更精细的ContextStatus枚举状态集合prepareRefresh()里改成类似这样的写法protected void prepareRefresh() { this.startupTime System.currentTimeMillis(); this.status.set(CLOSED); this.status.set(ACTIVE); // ... }具体细节因版本patch级别略有差异但核心目的不变用更严格的状态机来管理容器的生命周期避免之前双布尔状态在某些并发路径下自相矛盾的问题。第二个变化是日志体系和部分内部API的调整但prepareRefresh()的整体职责没有变时间戳、状态切换、属性源初始化、必填校验、监听器备份、早期事件收集依然是六大职责。这意味着即使你手头的是Spring 6项目理解了5.x的实现逻辑之后再去读6.x代码难度会低很多。阅读版本差异时一个高效的方法是把两个版本的prepareRefresh()方法体并列放在IDE里做diff对比。你会发现5.x里的很多“魔法”其实没有消失只是换了表达方式。7. 常见问题与排查技巧实录7.1 必填属性校验失败的定位与规避启动时报错The following properties were declared as required but could not be resolved: [app.env]这个异常的核心信息在 IllegalStateException 的消息里它会直接列出所有缺失的必填属性名。解决方式很简单去检查对应属性为什么没被解析到——是系统环境变量没配还是配置文件没被加载还是PropertySource的顺序导致某个同名校验被前面的同名属性盖住了。注意PropertySource解析有优先级systemProperties高于systemEnvironment和配置文件属性源所以如果你在系统属性里设了一个空字符串的值那校验也会“通过”因为属性存在但值为空validateRequiredProperties()只看属性键是否可解析不校验null之后的表现。7.2 重复刷新导致监听器重复执行的场景某些框架为了实现“动态配置热加载”会基于同一个ApplicationContext实例再次调用refresh()。如果你在监听器集合里手动添加过监听器又没有依赖earlyApplicationListeners的备份机制第二次刷新时监听器就会重复注册。解决方式是尽量通过registerListener()或者BeanApplicationListener接口这样的Spring原生机制注册让prepareRefresh()的备份逻辑帮你兜底。7.3 早期事件为什么在实际项目中“没发出去”这是使用Spring事件机制时最典型的困惑我明明在BeanFactoryPostProcessor里通过applicationContext.publishEvent()发布了一个事件但监听器收不到。原因多数情况下就是上面提到的时序问题——事件在multicaster创建之前被发布进入了earlyApplicationEvents但监听器Bean 还没实例化。解决方案不是去调整prepareRefresh()而是尽量避免在这么早的阶段发布业务事件如果确实有这种需求可以考虑把事件延后到finishRefresh()之后用ApplicationRunner或ApplicationReadyEvent来触发。7.4 一个实用的源码调试技巧最后分享一个我自己调试prepareRefresh()时常用的技巧在这几个方法里把日志级别调到TRACE。Spring 5在refresh()启动时会输出Refreshing [类名]的debug日志TRACE级别下还会输出更多细节。配合debug断点重点看以下五个值startupTime是否为0为0说明容器没有正常执行过刷新closed.get()与active.get()的当前值applicationListeners和earlyApplicationListeners的大小earlyApplicationEvents是否在第二次刷新时还在收集旧事件environment.getRequiredProperties()里注册了哪些必填项检查这五个值的过程基本就能覆盖prepareRefresh()调试中的大部分疑难问题。8. 写在最后我的几个实战体会和扩展建议把prepareRefresh()读透之后再看Spring源码心里会踏实很多。我个人最大的体会是Spring容器的启动过程之所以设计得这么复杂是因为它需要同时兼顾扩展性、健壮性和不同应用场景的兼容性。prepareRefresh()中短短的十几行代码实际上已经包含了状态管理、模板方法、集合快照、缓冲队列这四种设计思路每一种放在对应的工程场景里都很有代表性。如果你正在读refresh()流程我建议你在prepareRefresh()这一层多停一会儿不要急着往下冲。把每个字段的初始值、赋值时机、被谁读取、被谁修改都画出来可以画在纸上也可以写在IDE的注释里搞清楚这五个数据的生命周期再往后看obtainFreshBeanFactory()、finishRefresh()就会轻松一大截。后续想继续深挖的话可以顺着两个方向延伸一是对比prepareRefresh()和close()/doClose()的状态复位逻辑理解容器完整生命周期的对称性二是结合AbstractRefreshableWebApplicationContext去读initPropertySources()在Servlet环境下的真实重写看看Spring是如何把“环境准备”这个动作下沉到不同场景的。等这两块也摸清楚了你对Spring容器启动过程的理解基本就超过绝大多数业务开发了。