SpringBoot 优雅停机演进：实现原理与最佳实践

问题本质：关闭顺序错误

先关 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 # 等待超时时间

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

停机流程变为：

1. Web 容器立即 pause：停止 accept 新连接（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 行为：

• Tomcat：pause() + 等待线程池
• Jetty：停止 acceptor 线程
• Undertow：返回 503 给新请求
• Reactor Netty：发送 GOAWAY（HTTP/2）

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

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

2.3 前后对比总表

生产环境最佳实践

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，并配合基础设施实现流量摘除。这能显著提升系统在滚动更新、弹性伸缩场景下的稳定性与用户体验。