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

微服务和云原生时代，应用的平滑启停是保障系统高可用的关键环节。spring boot 在 2.3 版本引入了对内嵌 web 容器优雅停机的原生支持，改变此前需要手动编码实现局面。

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

优雅停机（graceful shutdown） 是指在应用停止过程中：

立即停止接收新请求；
允许已进入的请求继续处理完成；
安全释放资源（数据库连接、线程池、缓存等）；
避免客户端收到 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 等）

web 容器（tomcat/jetty/undertow）：负责网络连接与线程调度。
servlet 容器：管理 servlet、filter 生命周期。
spring 容器：即 applicationcontext，管理 bean 的创建与销毁。
spring boot：不是容器，而是自动集成 web 容器 + spring 容器的启动框架。

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

三、spring boot < 2.3：手动实现的“伪优雅”

在2.3之前，spring boot 没有内置优雅停机能力。默认行为是：

收到 sigterm（如 kill -15）；
立即关闭 spring 容器 → 设置 singletonscurrentlyindestruction = true；
web 容器仍在运行，继续 accept 新连接并分配线程；
若此时有请求进入，dispatcherservlet 尝试通过 getbean("ordercontroller") 获取 controller；
因 spring 容器已标记为“销毁中”，抛出 beancreationnotallowedexception。

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

先关 spring，再关 web 容器 → 存在危险时间窗口。

🛠️ 开发者workaround

需手动实现以下逻辑：

@component
public class gracefulshutdown implements tomcatconnectorcustomizer, 
                                      applicationlistener<contextclosedevent> {
    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  # 等待超时时间

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

停机流程变为：

web 容器立即 pause：停止 accept 新连接（tomcat 调用 connector.pause()）；
等待已进入的请求完成：最多等待 timeout-per-shutdown-phase 时间；
确认无活跃请求后，关闭 spring 容器：销毁所有 bean；
彻底停止 web 容器线程池。

🧠 底层原理

1.smartlifecycle控制关闭阶段

spring boot 注册了 webservergracefulshutdownlifecycle，它实现 smartlifecycle 接口，并设置：

@override
public int getphase() {
    return integer.max_value; // 最后启动，最先停止
}

确保其 stop() 方法在普通 bean 销毁之前执行。

2.webserver 接口标准化

不同内嵌服务器实现统一的 gracefulshutdown 行为：

tomcat：pause() + 等待线程池
jetty：停止 acceptor 线程
undertow：返回 503 给新请求
reactor netty：发送 goaway（http/2）

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.监控与告警

监控停机期间的 5xx 错误率；
若仍有 beancreationnotallowedexception，检查：
- 超时时间是否足够；
- lb 摘除延迟；
- 是否存在长轮询/websocket 未处理。

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

到此这篇关于springboot 优雅停机实现原理与最佳实践指南的文章就介绍到这了,更多相关springboot 优雅停机内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

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

2026年04月20日 • Java •我要评论