正软商城

SpringBoot优雅停机实现原理与最佳实践指南

时间：2026-07-17

在微服务和云原生架构日益普及的今天，应用的平滑启停能力，早已成为保障系统高可用的关键环节。而 Spring Boot 在 2.3 版本中引入了一项非常重要的更新——对内嵌 Web 容器的优雅停机提供了原生支持。这彻底改变了此前需要开发者手动编码实现这一功能的局面，可以说是一次不小的进步。

SpringBoot优雅停机实现原理与最佳实践指南

一、什么是“优雅停机”？

所谓优雅停机（Graceful Shutdown），核心目标是在应用停止的过程中，尽可能避免对正在处理的请求造成影响。具体来说，需要做到以下四点：

  1. 立即停止接收新的请求；
  2. 允许已经进入的请求继续处理完成；
  3. 安全释放所有资源（比如数据库连接、线程池、缓存等）；
  4. 避免客户端收到 5xx 错误或连接中断。

如果没有实现优雅停机，在滚动更新、缩容或重启时，很容易出现下面这种典型的异常：

ERROR ... - Error creating bean with name 'orderController': 
Singleton bean creation not allowed while singletons of this factory are in destruction
org.springframework.beans.factory.BeanCreationNotAllowedException: ...

这个异常信息其实很直白：Spring 容器已经在销毁了，但此时仍有请求试图获取 Controller Bean。这恰恰是停机流程设计不当的直接后果。

二、核心组件与层级关系

要理解优雅停机，首先得搞清楚各个组件之间的“居住”关系：

JVM
 └── 内嵌 Web 容器（如 Tomcat）
      └── Servlet 容器（StandardContext）
           └── DispatcherServlet（Spring MVC 入口）
                └── Spring ApplicationContext（IoC 容器）
                     └── 所有 Spring Bean（@Controller, @Service 等）

⚠️ 关键点：Spring 容器是运行在 Web 容器内部的。停机时，必须协调好二者的关闭顺序，否则就会出现“Web 容器还在处理请求，但 Spring 容器已经拒绝服务”的竞态条件。

三、Spring Boot < 2.3：手动实现的“伪优雅”

在 2.3 版本之前，Spring Boot 并没有内置的优雅停机能力。它的默认行为是什么样的呢？

  1. 收到 SIGTERM 信号（比如 kill -15）；
  2. 立即关闭 Spring 容器 → 设置 singletonsCurrentlyInDestruction = true；
  3. 此时，Web 容器仍在运行，还在继续接受新连接并分配线程；
  4. 如果这时有请求进来，DispatcherServlet 尝试通过 getBean("orderController") 获取 Controller；
  5. 因为 Spring 容器已经标记为“销毁中”，所以会抛出 BeanCreationNotAllowedException。

❌ 问题本质：关闭顺序错误

先关 Spring，再关 Web 容器 → 中间存在一个非常危险的“时间窗口”。

?️ 开发者的“workaround”

当时，开发者们不得不手动实现一套逻辑来解决问题：

@Component
public class GracefulShutdown implements TomcatConnectorCustomizer, 
                                      ApplicationListener {
    private volatile Connector connector;
    @Override
    public void customize(Connector connector) {
        this.connector = connector;
    }
    @Override
    public void onApplicationEvent(ContextClosedEvent event) {
        connector.pause(); // 停止接收新请求
        Executor executor = connector.getProtocolHandler().getExecutor();
        if (executor instanceof ThreadPoolExecutor) {
            try {
                ((ThreadPoolExecutor) executor).shutdown();
                ((ThreadPoolExecutor) executor).awaitTermination(30, TimeUnit.SECONDS);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        }
    }
}

同时，还需要将这个自定义组件注册到 Tomcat 中：

@Bean
public ServletWebServerFactory servletContainer() {
    TomcatServletWebServerFactory tomcat = new TomcatServletWebServerFactory();
    tomcat.addConnectorCustomizers(gracefulShutdown());
    return tomcat;
}

? 但即便这样，也无法完美处理 HTTP/1.1 keep-alive 连接复用场景下带来的新请求。

四、Spring Boot ≥ 2.3：原生优雅停机

到了 Spring Boot 2.3，事情就简单多了。官方引入了 标准化的优雅停机机制，只需要两行配置就能搞定：

server:
  shutdown: graceful          # 启用优雅停机
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s  # 等待超时时间

✅ 核心思想：反转关闭顺序 + 流量控制前置

现在的停机流程变成了这样：

  1. Web 容器立即 pause：停止接受新连接（Tomcat 会调用 connector.pause()）；
  2. 等待已进入的请求完成：最多等待 timeout-per-shutdown-phase 设定的时间；
  3. 确认没有活跃请求后，再关闭 Spring 容器：销毁所有 Bean；
  4. 最后彻底停止 Web 容器的线程池。

? 底层原理

1. SmartLifecycle 控制关闭阶段

Spring Boot 注册了一个 WebServerGracefulShutdownLifecycle，它实现了 SmartLifecycle 接口，并设置了：

@Override
public int getPhase() {
    return Integer.MAX_VALUE; // 最后启动，最先停止
}

这就保证了它的 stop() 方法会在普通 Bean 销毁之前执行。

2. WebServer 接口标准化

不同的内嵌服务器现在都实现了统一的 GracefulShutdown 行为：

3. 与 Spring 生命周期深度集成

通过 LifecycleProcessor 来协调所有 SmartLifecycle Bean 的关闭顺序，确保 Web 容器优雅关闭完成之后，才触发 ApplicationContext.close()。

五、2.3 前后对比总表

维度 Spring Boot < 2.3 Spring Boot ≥ 2.3
是否内置支持 ❌ 需手动编码 ✅ 开箱即用
关闭起点 Spring 容器 Web 容器
新请求处理 继续 accept → 高风险 立即拒绝（pause/503）→ 安全
已进入请求 可能因 Spring 关闭而失败 等待完成（最多 timeout）
典型异常 BeanCreationNotAllowedException 高频 极少（除非超时）
配置复杂度 高（需自定义监听器） 低（仅需 YAML）
多容器支持 仅限手动适配 自动支持 Tomcat/Jetty/Undertow/Netty
K8s 友好度 差 优秀

六、生产环境最佳实践

1. 启用优雅停机（2.3+）

server:
  shutdown: graceful
spring:
  lifecycle:
    timeout-per-shutdown-phase: 45s  # 建议大于业务最大请求耗时

2. Kubernetes 部署配合 preStop

spec:
  containers:
    - name: app
      lifecycle:
        preStop:
          exec:
            command: ["sleep", "15"]  # 给 LB 时间摘除节点
      terminationGracePeriodSeconds: 60

3. Windows 服务需走 Actuator

management:
  endpoint:
    shutdown:
      enabled: true
  endpoints:
    web:
      exposure:
        include: "shutdown"

然后通过外部命令触发：

curl -X POST http://localhost:8080/actuator/shutdown

4. 监控与告警

? 一句话建议：

只要你的 Spring Boot 版本 ≥ 2.3，务必启用 server.shutdown=graceful，并配合基础设施实现流量摘除。这能显著提升系统在滚动更新、弹性伸缩场景下的稳定性与用户体验。

本文转载于：https://www.jb51.net/program/362479bgh.htm 如有侵犯，请联系zhengruancom@outlook.com删除。
免责声明：正软商城发布此文仅为传递信息，不代表正软商城认同其观点或证实其描述。

同类商品

相关文章

更多