Spring Boot关闭时如何让Akka Actor处理完待处理消息后再终止

核心实现逻辑 #

要实现Akka Actor待处理消息消费完成后再终止，核心是把Akka的停机流程绑定到Spring Boot的关闭生命周期中，同时禁用Akka默认的JVM关闭钩子，避免Akka被JVM关闭事件直接终止。 #

具体实现步骤 #

1. 调整Akka基础配置 #

在Akka的application.conf配置文件中添加以下配置，关闭默认的停机钩子，开启可自定义的协调关闭逻辑：

akka {
  # 禁用Akka默认的JVM关闭钩子
  jvm-shutdown-hooks = off
  actor {
    # 按业务实际最长消息处理时长调整优雅停机超时时间
    graceful-stop-timeout = 300s
  }
  coordinated-shutdown {
    # 禁止Akka自行触发JVM退出
    jvm-exit-on-shutdown = off
    run-by-jvm-shutdown-hook = off
  }
}

2. 自定义Akka优雅停机的Spring生命周期Bean #

实现SmartLifecycle接口控制Akka停机的优先级，确保Actor消息消费完成后再执行后续Spring销毁逻辑：

import akka.actor.ActorRef;
import akka.actor.ActorSystem;
import akka.pattern.Patterns;
import org.springframework.context.SmartLifecycle;
import org.springframework.stereotype.Component;
import scala.concurrent.Await;
import scala.concurrent.Future;
import scala.concurrent.duration.Duration;
import java.util.concurrent.TimeUnit;

@Component
public class AkkaGracefulShutdownConfig implements SmartLifecycle {
    private final ActorSystem actorSystem;
    // 替换为你自己的根Actor注入实例
    private final ActorRef rootActor;
    private volatile boolean isRunning = true;
    // 和Akka配置的停机超时时间保持一致
    private static final long SHUTDOWN_WAIT_SECONDS = 300;

    public AkkaGracefulShutdownConfig(ActorSystem actorSystem, ActorRef rootActor) {
        this.actorSystem = actorSystem;
        this.rootActor = rootActor;
    }

    @Override
    public void start() {
        isRunning = true;
    }

    @Override
    public void stop() {
        isRunning = false;
        try {
            // 触发根Actor优雅停止，会递归等待所有子Actor处理完存量消息再终止
            Future<Boolean> stopFuture = Patterns.gracefulStop(
                    rootActor,
                    Duration.create(SHUTDOWN_WAIT_SECONDS, TimeUnit.SECONDS)
            );
            Await.result(stopFuture, Duration.create(SHUTDOWN_WAIT_SECONDS, TimeUnit.SECONDS));
            // 所有Actor终止后再关闭ActorSystem
            Await.result(actorSystem.terminate(), Duration.create(SHUTDOWN_WAIT_SECONDS, TimeUnit.SECONDS));
        } catch (Exception e) {
            // 超时后的自定义降级逻辑，可自行实现未处理消息的落盘、告警等操作
            actorSystem.log().error("Akka graceful shutdown timeout, force terminate", e);
        }
    }

    @Override
    public boolean isRunning() {
        return isRunning;
    }

    // 优先级设置为最高，确保Akka停机逻辑在其他Spring Bean销毁前执行
    @Override
    public int getPhase() {
        return Integer.MAX_VALUE - 1;
    }

    @Override
    public boolean isAutoStartup() {
        return true;
    }

    @Override
    public void stop(Runnable callback) {
        stop();
        callback.run();
    }
}

3. 开启Spring Boot优雅关闭 #

在application.yml中添加配置，让Spring Boot预留足够的停机等待时间：

server:
  shutdown: graceful
spring:
  lifecycle:
    # 超时时间设置要大于等于Akka的停机超时时间
    timeout-per-shutdown-phase: 360s

注意事项 #

• Akka默认的gracefulStop方法会递归等待所有子Actor完成存量消息处理，无需额外开发子Actor的等待逻辑
• 如果Actor处理逻辑依赖其他Spring Bean，需要调整对应Bean的销毁优先级，确保Bean在Akka完全关闭后再销毁
• 如果是Akka Cluster集群场景，需要额外配置akka.coordinated-shutdown.terminate-actor-system = on，调整集群退出阶段的等待时长，确保节点退出集群前完成本地消息消费
• 可以在停止逻辑的最前面先关闭上游消息投递入口，避免停机过程中有新消息进入Actor队列

内容的提问来源于stack exchange，提问作者Deepak