Spring Boot优雅停机核心是停止接收新请求、处理完存量任务、释放资源后安全退出；自2.3起原生支持，需配置server.shutdown=graceful和spring.lifecycle.timeout-per-shutdown-phase（建议45–60s），配合@PreDestroy清理资源，禁用kill-9，K8s中需合理设置preStop与terminationGracePeriodSeconds。
Spring Boot 实现优雅停机，核心是让应用在退出前停止接收新请求、处理完正在执行的任务、释放连接池/线程池/MQ消费者等资源，最后安全退出 JVM。从 Spring Boot 2.3 开始，框架已原生支持，无需手写钩子，但必须正确配置和使用。
配置内置优雅停机（推荐首选）
这是最简单、最稳定的方式，适用于 Tomcat/Jetty/Undertow 所有内嵌容器。
- 在 application.yml 中添加：
server:
shutdown: graceful
spring:
lifecycle:
timeout-per-shutdown-phase: 45s
-
server.shutdown: graceful 启用 Web 容器层的优雅停机：收到 SIGTERM（如
kill -15 PID）后，Tomcat 会立即关闭 Acceptor 线程，不再接受新 HTTP 请求；同时允许已入队的工作线程继续完成当前请求。 -
spring.lifecycle.timeout-per-shutdown-phase 控制整个关闭流程的最大等待时间，默认 30 秒，建议根据业务最长请求耗时设为 45–60 秒。超时后 Spring 会强制调用
close()，未完成的请求可能被中断。
配合 @PreDestroy 和 DisposableBean 清理业务资源
优雅停机触发后，Spring 容器会按逆序销毁 Bean。你可以在关键组件中主动释放资源：
- 使用
@PreDestroy注解方法（推荐，轻量、清晰）：
@Component
public class DatabaseCleaner {
private final HikariDataSource dataSource;
public DatabaseCleaner(HikariDataSource dataSource) {
this.dataSource = dataSource;
}
@PreDestroy
public void closeDataSource() {
if (!dataSource.isClosed()) {
dataSource.close();
System.out.println("HikariCP connection pool closed gracefully");
}
}
}
- 或实现
DisposableBean接口，重写destroy()方法，效果一致。 - 注意：不要在
@PreDestroy中执行耗时操作（如等待 10 秒），它运行在主线程中，会拖慢整体关机节奏；耗时清理应交由异步任务 + 超时控制来管理。
通过 Actuator 远程触发（适合发布平台集成）
当需要脚本化、平台化控制停机（如 K8s preStop hook 或 CI/CD 流水线），可启用 Actuator 的 /actuator/shutdown 端点：
立即学习“Java免费学习笔记（深入）”；
- 引入依赖：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>
- 在配置中暴露并启用：
management:
endpoints:
web:
exposure:
include: shutdown,health
endpoint:
shutdown:
enabled: true
- 调用方式（需确保端口可达且权限受控）：
curl -X POST http://localhost:8080/actuator/shutdown
- ⚠️ 生产环境务必配合 Spring Security 限制访问，避免未授权调用导致服务意外下线。
关键注意事项
即使配了优雅停机，仍可能失效——常见原因包括：
- 误用
kill -9：JVM 不执行任何关闭钩子，@PreDestroy、连接池关闭、Actuator 均无效；生产环境禁用该命令。 - K8s preStop 未配或超时过短：应在 Pod 删除前调用
curl http://localhost:8080/actuator/shutdown或发送kill -15，且terminationGracePeriodSeconds必须 ≥timeout-per-shutdown-phase+ 缓冲（建议 ≥ 90 秒）。 - 自定义线程池未托管给 Spring：若手动 new ThreadPoolExecutor，需在
@PreDestroy中显式调用shutdown()+awaitTermination()。 - 异步消息消费（如 @RabbitListener / @KafkaListener）默认支持优雅停机，但需确认 listener 容器配置了
setPhase(2147483647)或更高相位，确保晚于 Web 容器关闭。
