Spring Boot 内嵌 Web 容器启动机制解析：ServletWebServerApplicationContext 深度剖析

Spring Boot 内嵌 Web 容器启动机制解析：ServletWebServerApplicationContext 深度剖析

在 Spring Boot 应用中，内嵌 Web 服务器（如 Tomcat、Jetty、Undertow）的自动创建与集成是其“开箱即用”体验的关键一环。这一能力的核心支撑类是ServletWebServerApplicationContext及其子类AnnotationConfigServletWebServerApplicationContext。它们不仅承担了标准 Spring 容器的职责，还负责 Web 服务器的生命周期管理。

本文将深入源码，解析这两个上下文类的工作原理，结合启动流程、典型问题与调试技巧，帮助开发者理解 Spring Boot 如何无缝整合 Web 容器。

一、类结构与职责划分

1. 核心类图关系

AbstractApplicationContext └── GenericApplicationContext └── AbstractRefreshableConfigApplicationContext └── AbstractRefreshableWebApplicationContext └── ServletWebServerApplicationContext ← 管理 WebServer └── AnnotationConfigServletWebServerApplicationContext ← 支持注解扫描

• ServletWebServerApplicationContext
  实现ConfigurableWebServerApplicationContext接口，核心职责是创建并管理内嵌 Web 服务器。

• AnnotationConfigServletWebServerApplicationContext
  在前者基础上实现AnnotationConfigRegistry，支持通过@ComponentScan或指定包路径加载 Bean，常用于单元测试或编程式启动。

二、Web 容器启动主流程

Spring Boot Web 应用的启动最终会调用ServletWebServerApplicationContext.refresh()，其关键步骤如下：

1.refresh()—— 标准容器刷新（继承自父类）

@Overridepublicvoidrefresh()throwsBeansException,IllegalStateException{super.refresh();// 调用 AbstractApplicationContext.refresh()}

此方法会执行标准的 12 步刷新流程（如初始化 BeanFactory、注册 BPP、实例化单例等）。

2.onRefresh()—— Web 容器创建入口（模板方法）

这是AbstractApplicationContext.refresh()中预留的扩展点，在ServletWebServerApplicationContext中被重写：

@OverrideprotectedvoidonRefresh(){super.onRefresh();try{createWebServer();// ← 关键：创建并初始化 WebServer}catch(Throwableex){thrownewApplicationContextException("Unable to start web server",ex);}}

✅设计模式：模板方法 + 钩子（Hook），将 Web 特定逻辑插入通用刷新流程。

3.createWebServer()—— 创建内嵌 Web 服务器

privatevoidcreateWebServer(){WebServerwebServer=this.webServer;ServletContextservletContext=getServletContext();if(webServer==null&&servletContext==null){// 1. 获取 ServletWebServerFactory（如 TomcatServletWebServerFactory）ServletWebServerFactoryfactory=getWebServerFactory();// 2. 通过工厂创建 WebServer，并传入 selfInitialize 回调this.webServer=factory.getWebServer(getSelfInitializer());}elseif(servletContext!=null){try{getSelfInitializer().onStartup(servletContext);}catch(ServletExceptionex){thrownewApplicationContextException("Cannot initialize servlet context",ex);}}initPropertySources();}

关键点解析：

• getWebServerFactory()
  从容器中获取类型为ServletWebServerFactory的 Bean（由ServletWebServerFactoryAutoConfiguration自动配置）。

• getSelfInitializer()
  返回一个ServletContextInitializer回调，用于将 Spring 的DispatcherServlet、Filter、Listener 注册到 Servlet 容器：

  privateorg.springframework.boot.web.servlet.ServletContextInitializergetSelfInitializer(){returnthis::selfInitialize;}privatevoidselfInitialize(ServletContextservletContext)throwsServletException{prepareWebApplicationContext(servletContext);registerApplicationScope(servletContext);WebApplicationContextUtils.registerWebApplicationScopes(getBeanFactory(),servletContext);// 注册所有 ServletContextInitializer（包括 DispatcherServletRegistrationBean）ServletContextInitializerBeansinitializers=newServletContextInitializerBeans(getBeanFactory());for(ServletContextInitializerinitializer:initializers){initializer.onStartup(servletContext);}}

📌核心机制：
Spring Boot 将DispatcherServlet包装为ServletRegistrationBean，并通过ServletContextInitializer机制注册到内嵌容器，无需 web.xml。

4.finishRefresh()—— 启动 Web 服务器

在所有 Bean 初始化完成后，finishRefresh()被调用：

@OverrideprotectedvoidfinishRefresh(){super.finishRefresh();// 启动 WebServer（如 Tomcat.start()）WebServerwebServer=startWebServer();if(webServer!=null){publishEvent(newServletWebServerInitializedEvent(webServer,this));}}

此时，内嵌服务器（如 Tomcat）正式监听端口，应用可对外提供服务。

三、代码示例：编程式启动 Web 应用

AnnotationConfigServletWebServerApplicationContext常用于测试或嵌入式场景：

publicclassProgrammaticWebApp{publicstaticvoidmain(String[]args){// 1. 创建上下文AnnotationConfigServletWebServerApplicationContextcontext=newAnnotationConfigServletWebServerApplicationContext();// 2. 注册配置类context.register(WebConfig.class);// 3. 刷新容器（触发 WebServer 创建与启动）context.refresh();System.out.println("Server started on port: "+context.getWebServer().getPort());// 4. 优雅关闭context.close();}}@Configuration@EnableAutoConfiguration@ComponentScanpublicclassWebConfig{@BeanpublicRouterFunction<ServerResponse>routes(){returnroute(GET("/hello"),req->ok().bodyValue("Hello from embedded server"));}}

✅适用场景：

• 集成测试；
• 微服务嵌入式网关；
• 动态模块化 Web 应用。

四、常见问题与解决方案

❌ 问题 1：启动时报 “Unable to start embedded container”

典型日志：

ApplicationContextException: Unable to start web server Caused by: IllegalArgumentException: No servlet or filter mapping specified

原因分析：

• 未引入 Web Starter（如spring-boot-starter-web）；
• 手动排除了DispatcherServletAutoConfiguration；
• 自定义ServletWebServerFactory配置错误。

✅排查步骤：

1. 检查依赖是否包含spring-boot-starter-web；
2. 查看自动配置报告（--debug），确认TomcatServletWebServerFactory是否生效；
3. 确保至少有一个@RestController或RouterFunction。

❌ 问题 2：端口被占用或无法绑定

现象：
WebServerException: Unable to start embedded Tomcat

✅解决方案：

• 修改端口：

  server:port:8081

• 允许随机端口（测试场景）：

  @SpringBootTest(webEnvironment=SpringBootTest.WebEnvironment.RANDOM_PORT)publicclassMyWebTest{...}

❌ 问题 3：自定义 Servlet/Filter 未注册

原因：

• 未使用@ServletComponentScan（仅适用于@WebServlet等注解）；
• 未定义为ServletRegistrationBean/FilterRegistrationBean。

✅正确做法：

@BeanpublicFilterRegistrationBean<MyFilter>myFilter(){FilterRegistrationBean<MyFilter>registration=newFilterRegistrationBean<>();registration.setFilter(newMyFilter());registration.addUrlPatterns("/api/*");returnregistration;}

⚠️注意：
直接使用@Component的Filter不会被自动注册，必须通过FilterRegistrationBean。

❌ 问题 4：Web 上下文未正确关联 ServletContext

现象：
WebApplicationContextUtils.getWebApplicationContext(servletContext)返回 null。

✅原因与修复：
确保调用了prepareWebApplicationContext(servletContext)（由selfInitialize自动完成）。若手动创建上下文，需显式设置：

context.setServletContext(servletContext);

五、最佳实践与注意事项

✅ 推荐做法

1. 优先使用@SpringBootApplication，避免手动管理ApplicationContext；
2. 自定义 Web 配置通过WebServerFactoryCustomizer实现：

   @BeanpublicWebServerFactoryCustomizer<TomcatServletWebServerFactory>tomcatCustomizer(){returnfactory->factory.setPort(9090);}

3. 测试时使用@SpringBootTest+RANDOM_PORT，避免端口冲突。

⚠️ 注意事项

• ServletWebServerApplicationContext仅适用于 Servlet 栈（非 Reactive）；
• 不要在onRefresh()阶段依赖尚未初始化的 Bean；
• 内嵌服务器的生命周期由上下文管理，不要手动调用webServer.start()。

六、总结

ServletWebServerApplicationContext是 Spring Boot 实现“内嵌 Web 容器”的核心桥梁。它通过重写onRefresh()和finishRefresh()，将 Web 服务器的创建与启动无缝嵌入 Spring 容器的刷新流程，并借助ServletContextInitializer机制完成 Servlet 组件的注册。

理解其工作原理，不仅能帮助我们高效排查启动问题，也为自定义 Web 行为（如多端口监听、动态路由）提供了坚实基础。建议结合调试（在createWebServer()设断点）与自动配置报告，深入掌握这一关键机制。

💡上周热门博文

• Spring 事务源码导读：从 @Transactional 到底层数据库提交的完整流程
• Spring 中不同 Scope 的 Bean 创建机制详解
• Spring XML 配置中＜import＞标签的解析机制与最佳实践
• Spring XML 解析中的 Document 加载与 EntityResolver 机制详解