Spring Boot 中 Kafka 优雅停机需让消费者停止拉取新消息、处理完已拉取消息、手动提交偏移量并释放资源，依赖 SmartLifecycle/@PreDestroy 控制容器 stop()、配置 auto-startup=false 和 MANUAL 提交等关键参数，并配合 kill-15 与延长 shutdown-phase 超时实现全流程可控。
Spring Boot 中 Kafka 的优雅停机，核心是让消费者在收到停机信号后不再拉取新消息、继续处理完已拉取但未消费完成的消息，并主动释放连接与资源，避免消息丢失或重复消费。这不能只靠 Spring Boot 内置的 HTTP 优雅停机机制——Kafka 消费者是独立于 Web 容器运行的后台线程，必须单独协调。
Kafka 消费者需显式参与停机流程
默认情况下，Spring Kafka 的 @KafkaListener 容器会在 ApplicationContext 关闭时自动停止，但若未配置得当，可能：
- 停机时仍在 poll 新批次消息，导致部分消息被拉取却来不及处理；
- 正在执行的 listener 方法被强制中断（如未设置超时或未捕获异常），事务不回滚、偏移量未提交；
- 连接未及时关闭，ZooKeeper/Nacos 中的消费者实例下线延迟，影响集群 rebalance。
因此，必须结合 Kafka 自身特性 + Spring 生命周期管理来控制。
关键配置项：让消费者“知悉并响应停机”
在 application.yml 中启用可控的消费者生命周期：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
-
spring.kafka.listener.auto-startup: false—— 启动时不自动开启监听器，避免开发环境连不上 Kafka 导致启动失败； -
spring.kafka.listener.ack-mode: MANUAL_IMMEDIATE或MANUAL—— 手动提交偏移量，确保只在业务逻辑真正完成后再 commit； -
spring.kafka.listener.poll-timeout: 5000—— 缩短单次 poll 超时，使 stop 指令能更快中断阻塞的 poll； -
spring.kafka.listener.idle-event-interval: 60000—— 开启 idle 事件，便于监听空闲状态做清理； -
spring.kafka.consumer.properties.max.poll.records: 10—— 控制每次拉取条数，降低单批次处理压力，缩短停机等待时间。
监听应用关闭事件，主动触发消费者停止
使用 ApplicationRunner 启动消费者，用 SmartLifecycle 或 @PreDestroy 确保有序关闭：
- 为每个
@KafkaListener指定唯一id（如@KafkaListener(id = "orderListener", topics = "order-topic")）； - 注入
KafkaListenerEndpointRegistry，在@PreDestroy方法中获取容器并调用stop()：
@Component
public class KafkaGracefulShutdown {
@Autowired
private KafkaListenerEndpointRegistry registry;
@PreDestroy
public void shutdown() {
registry.getListenerContainers().forEach(container -> {
if (container.isRunning()) {
container.stop(() -> {
System.out.println("Kafka listener stopped gracefully");
});
}
});
}
}
该方式确保：Spring 容器销毁前，消费者线程已进入停止流程，不再发起新 poll，且当前正在执行的 listener 方法可自然完成（配合合理超时与手动 commit）。
配合全局优雅停机，延长整体宽限期
Spring Boot 2.3+ 的 graceful shutdown 默认仅作用于 Web 层。Kafka 消费属于后台任务，需延长总停机窗口：
- 设置
spring.lifecycle.timeout-per-shutdown-phase: 45s（建议 ≥ Kafka 单条消息最长处理时间 × 2）； - 若使用 Actuator 的
/actuator/shutdown，需确认它会触发完整上下文关闭（包括 Kafka 容器）； - 避免使用
kill -9；统一用kill -15触发 JVM ShutdownHook，才能激活上述流程。
此时整个停机链路为：kill -15 → JVM Hook → Spring ContextClosedEvent → Web 容器拒绝新请求 → Kafka 容器 stop() → listener 处理完剩余消息 → 偏移量提交 → 连接释放 → JVM 退出。
