CommandLineRunner 和 ApplicationRunner 是什么？怎么在 Spring Boot 启动后执行初始化逻辑？

简化版

CommandLineRunner 和 ApplicationRunner 是 Spring Boot 提供的「启动后回调」——实现它们的 run() 方法，Spring Boot 会在容器完全启动就绪、但对外提供服务之前自动调用一次，用来做「应用启动后要执行一次的初始化逻辑」（预加载缓存、检查外部依赖、打印启动信息、执行数据初始化等）。两者的唯一区别是「拿参数的方式」：CommandLineRunner.run(String... args) 拿到的是原始的命令行参数字符串数组；ApplicationRunner.run(ApplicationArguments args) 拿到的是封装解析后的 ApplicationArguments（能区分「选项参数 --key=value」和「非选项参数」，更方便）。执行时机：在 SpringApplication.run() 快结束时、ApplicationReadyEvent 前后被调用，此时所有 Bean 都已初始化好，可以安全地注入并使用任何依赖。多个 Runner 的顺序：用 @Order 注解或实现 Ordered 接口控制（数字小的先执行）。

详细版

两者对比：

维度	CommandLineRunner	ApplicationRunner
方法签名	run(String... args)	run(ApplicationArguments args)
参数形式	原始字符串数组	封装解析后的对象
区分选项/非选项	不能（要自己解析）	能（getOptionNames/getNonOptionArgs）
执行时机	相同（容器就绪后、对外服务前）	相同
用途	相同（启动后一次性初始化）	相同

@Component
@Order(1)                                 // 多个 Runner 时控制顺序
public class CacheWarmupRunner implements CommandLineRunner {
    @Autowired private CacheService cacheService;   // 可安全注入使用
    @Override
    public void run(String... args) {
        cacheService.warmUp();            // 启动后预热缓存
    }
}

@Component
@Order(2)
public class ArgsRunner implements ApplicationRunner {
    @Override
    public void run(ApplicationArguments args) {
        // --server.port=8081 debug → 能区分选项参数和非选项参数
        Set<String> options = args.getOptionNames();       // [server.port]
        List<String> values = args.getOptionValues("server.port"); // [8081]
        List<String> nonOptions = args.getNonOptionArgs();  // [debug]
    }
}

⚠️ Runner 里抛异常会导致应用启动失败——CommandLineRunner/ApplicationRunner 的 run() 抛出异常，会向上传播，导致 SpringApplication.run() 抛异常、应用启动失败退出。这既是「特性」（关键的启动前检查失败就该阻止启动，比如「必需的外部服务连不上就别启动」），也是「坑」（一个无关紧要的初始化任务抛异常，把整个应用干趴下）。所以：关键性检查（依赖必须就绪）可以放任由它失败；非关键的初始化（如预热缓存失败）应该自己 try-catch 兜住，别让它拖垮启动。另外，Runner 是同步执行的，会阻塞启动完成，耗时任务应异步化或放到后台线程。

完整版教学

一、为什么需要「启动后回调」

先理解「启动后要执行一次逻辑」这个需求，以及为什么不放别处：

应用启动后常需要执行一次性的初始化：
  - 预热缓存（把热点数据先加载到缓存）
  - 检查外部依赖（数据库、Redis、下游服务是否就绪）
  - 加载配置字典、初始化数据
  - 打印启动横幅、注册到服务发现

为什么不放这些地方？
  ① main 方法里 SpringApplication.run() 之后写？
     → 能，但拿不到 Spring 管理的 Bean（要手动 getBean，别扭）
  ② 放某个 Bean 的 @PostConstruct？
     → @PostConstruct 在"这个 Bean 初始化时"执行，
       此时其他 Bean 可能还没就绪、容器还没完全启动
     → 不保证"整个应用都就绪了"

CommandLineRunner/ApplicationRunner：
  在"容器完全就绪后"执行，能安全用所有 Bean → 正好合适

启动后回调的价值是「在应用完全就绪后、执行一次性初始化」——它比 @PostConstruct（单个 Bean 初始化时执行，此时整个容器未必就绪）时机更晚更安全，比 main 方法里手写（拿不到托管 Bean）更方便。它保证「所有 Bean 都初始化好了」，能安全注入并使用任何依赖。理解「Runner 在容器完全就绪后执行一次性初始化、比 @PostConstruct 时机更晚更全、比 main 手写更方便拿 Bean」，就理解了它的定位。

二、CommandLineRunner：拿原始参数

CommandLineRunner 是最简单的启动回调：

public interface CommandLineRunner {
    void run(String... args) throws Exception;
}

args 是什么：main 方法收到的原始命令行参数
  java -jar app.jar foo bar --server.port=8081
  → args = ["foo", "bar", "--server.port=8081"]
  （原封不动的字符串数组，不做任何解析）

用法：
  @Component
  class MyRunner implements CommandLineRunner {
      public void run(String... args) {
          // 启动后执行，args 是原始参数
      }
  }

适合：不关心参数、或参数简单自己处理的场景

CommandLineRunner.run(String... args) 拿到的是「原始命令行参数字符串数组」——不做任何解析，--server.port=8081 也是原样的一个字符串。适合「不关心参数」或「参数简单自己处理」的场景。实现接口 + 标 @Component 即可。理解「CommandLineRunner.run(String… args) 拿原始命令行参数数组、不解析、适合简单场景」，就掌握了 CommandLineRunner。

三、ApplicationRunner：拿解析后的参数

ApplicationRunner 与 CommandLineRunner 唯一的区别是「参数已经解析好了」：

public interface ApplicationRunner {
    void run(ApplicationArguments args) throws Exception;
}

ApplicationArguments 把参数分成两类：
  选项参数（option）：形如 --key=value 的
    getOptionNames()          → 所有选项名 [server.port, spring.profiles.active]
    getOptionValues("key")    → 某选项的值列表
  非选项参数（non-option）：普通的位置参数
    getNonOptionArgs()        → [foo, bar]
  getSourceArgs()             → 原始数组（和 CommandLineRunner 一样）

例：java -jar app.jar init --mode=fast --tags=a --tags=b
  getNonOptionArgs()      → [init]
  getOptionNames()        → [mode, tags]
  getOptionValues("tags") → [a, b]

适合：需要按"选项/非选项"处理参数的场景（更方便）

ApplicationRunner.run(ApplicationArguments args) 拿到的是封装解析后的参数——ApplicationArguments 把参数分成「选项参数 --key=value」（getOptionNames/getOptionValues）和「非选项参数」（getNonOptionArgs），还能拿原始数组。相比 CommandLineRunner 要自己解析，它更方便。理解「ApplicationRunner.run(ApplicationArguments) 拿解析后的参数、区分选项 —key=value 和非选项参数、比 CommandLineRunner 更方便」，就掌握了 ApplicationRunner——两者只差在参数形式。

四、执行时机：在整个启动流程中的位置

理解 Runner 在 SpringApplication.run() 里的确切位置：

SpringApplication.run() 的大致流程（简化）：
  1. 准备 Environment（加载配置、profile）
  2. 创建 ApplicationContext
  3. refresh 容器（实例化所有单例 Bean、@PostConstruct 等）
  4. afterRefresh
  5. ★ 调用所有 CommandLineRunner / ApplicationRunner 的 run()
  6. 发布 ApplicationReadyEvent（应用就绪）

关键点：
  - Runner 在"容器 refresh 完成"之后 → 所有 Bean 都就绪，能安全用
  - Runner 在"对外提供服务"之前 → 可以做启动前的最后准备
    （不过内嵌 web 服务器此时通常已启动、开始接收请求，
     所以别指望它能"完全挡在流量之前"——要挡流量用健康检查/就绪探针）
  - CommandLineRunner 和 ApplicationRunner 混在一起，按 @Order 统一排序

Runner 的执行时机在 SpringApplication.run() 里——容器 refresh 完成（所有 Bean 就绪）之后、ApplicationReadyEvent 前后。所以能安全用所有 Bean。但要注意：内嵌 web 服务器此时通常已启动开始接收请求，Runner 不能完全「挡在流量之前」（要挡流量该用 K8s 就绪探针/健康检查）。CommandLineRunner 和 ApplicationRunner 混在一起按 @Order 统一排序。理解「Runner 在容器 refresh 后、ApplicationReadyEvent 前后执行、能用所有 Bean、但 web 已开始接收请求不能完全挡流量」，就理解了它的执行时机。

五、多个 Runner 的顺序控制

实际项目常有多个 Runner，需要控制执行顺序：

多个 Runner 的顺序：用 @Order 或 Ordered 接口
  @Order(1) 的先执行，@Order(2) 的后执行（数字小的优先）

  @Component @Order(1)
  class DbCheckRunner implements CommandLineRunner { }  // 先检查数据库
  @Component @Order(2)
  class CacheWarmupRunner implements CommandLineRunner { } // 再预热缓存

注意：
  - CommandLineRunner 和 ApplicationRunner 是"同一个排序队列"
    （不是先跑完所有 CommandLineRunner 再跑 ApplicationRunner）
    它们按 @Order 值统一排序、依次执行
  - 不标 @Order 的顺序不确定，有依赖关系一定要显式标

典型用途：有先后依赖的初始化
  先"连数据库/检查依赖"，再"基于数据库预热缓存"

多个 Runner 用 @Order（或 Ordered 接口） 控制顺序（数字小的先执行）。关键点：CommandLineRunner 和 ApplicationRunner 在同一个排序队列，按 @Order 统一排序，不是「先跑完所有 CommandLineRunner」。有先后依赖的初始化（先检查数据库、再预热缓存）一定要显式标 @Order（不标顺序不确定）。理解「多 Runner 用 @Order 排序数字小的先、CommandLineRunner 和 ApplicationRunner 同队列统一排序、有依赖必须显式标」，就掌握了顺序控制。

六、异常处理与耗时任务

生产使用 Runner 有两个必须注意的点：异常传播和同步阻塞：

坑一：Runner 抛异常 → 应用启动失败
  run() 抛出异常会向上传播，导致 SpringApplication.run() 失败、应用退出
  这是双刃剑：
    ✓ 好处：关键检查失败就该阻止启动
      （如"必需的下游服务连不上"，启动了也是残废，不如别启动）
    ✗ 坏处：无关紧要的任务失败也会拖垮启动
      → 非关键初始化要自己 try-catch 兜住

  策略：
    关键依赖检查 → 让它失败（阻止启动，快速暴露问题）
    非关键预热/统计 → try-catch，记日志但不影响启动

坑二：Runner 是同步执行，会阻塞启动完成
  一个耗时 30 秒的 Runner → 应用要 30 秒后才"完全就绪"
  → 耗时任务应异步（提交到线程池/@Async），或改成后台定时任务

小结：Runner 适合"轻量、快速、关键"的启动后初始化

Runner 的两个生产注意点：① 异常传播导致启动失败（双刃剑——关键检查失败该阻止启动、非关键任务失败要 try-catch 兜住）；② 同步阻塞启动（耗时任务会拖慢「完全就绪」，应异步化或改后台任务）。所以 Runner 适合「轻量、快速、关键」的启动后初始化。理解「Runner 抛异常会导致启动失败(关键检查该失败、非关键要 try-catch)、同步执行会阻塞启动(耗时任务异步化)、适合轻量关键初始化」，就掌握了生产使用要点。

记忆钩子：「CommandLineRunner/ApplicationRunner = Spring Boot 启动后回调，容器完全就绪后、对外服务前执行一次性初始化(预热缓存/检查依赖/数据初始化)；唯一区别是拿参数方式：CommandLineRunner.run(String… args)拿原始数组、ApplicationRunner.run(ApplicationArguments)拿解析后的(区分选项—key=value 和非选项)；比 @PostConstruct 时机更晚更全、能安全用所有 Bean；多个用 @Order 排序(两者同队列)；坑:run()抛异常导致启动失败(关键检查该失败、非关键 try-catch)、同步阻塞启动(耗时任务异步化)」。

七、常见误区与追问

• 误区：CommandLineRunner 和 ApplicationRunner 功能不同。 功能、执行时机完全相同，唯一区别是拿参数的方式——CommandLineRunner 拿原始字符串数组，ApplicationRunner 拿封装解析后的 ApplicationArguments（能区分选项 —key=value 和非选项参数）。
• 误区：启动初始化应该放 @PostConstruct。 @PostConstruct 在「单个 Bean 初始化时」执行，此时其他 Bean 可能还没就绪、容器未完全启动；要「整个应用就绪后」执行一次性初始化用 Runner 更安全（所有 Bean 都可用）。
• 误区：Runner 里抛异常无所谓。 run() 抛异常会向上传播导致 SpringApplication.run() 失败、应用启动退出；非关键的初始化任务要自己 try-catch 兜住，否则一个小任务失败会拖垮整个应用启动。
• 误区：Runner 能挡在所有流量之前做准备。 内嵌 web 服务器在 Runner 执行时通常已启动、开始接收请求；要真正「就绪前不接流量」应使用 K8s 就绪探针（readiness probe）或健康检查，而非依赖 Runner。
• 追问：多个 Runner 的执行顺序怎么定？ 用 @Order 注解或实现 Ordered 接口，数字小的先执行；CommandLineRunner 和 ApplicationRunner 在同一个排序队列里按 @Order 统一排序（不是先跑完一类再跑另一类）；不标 @Order 顺序不确定。
• 追问：Runner 是同步还是异步执行？会不会阻塞启动？ 同步执行，会阻塞「应用完全就绪」的时间点——一个耗时的 Runner 会让应用晚就绪那么久；耗时任务应提交到线程池/用 @Async 异步执行，或改成后台定时任务，避免拖慢启动。
• 追问：想在应用完全就绪后（含 web 服务器已起）做事，除了 Runner 还有别的方式吗？ 可以监听 ApplicationReadyEvent（@EventListener(ApplicationReadyEvent.class)）——它在所有 Runner 执行完、应用完全就绪后发布，语义更明确，也是常用的启动后钩子。

八、加强记忆

CommandLineRunner 和 ApplicationRunner 是 Spring Boot 的「启动后回调」——实现 run()，Spring Boot 在容器完全 refresh 就绪后、ApplicationReadyEvent 前后自动调用一次，用于「应用启动后的一次性初始化」（预热缓存、检查外部依赖、数据初始化、打印启动信息）。它比 @PostConstruct（单 Bean 初始化时、容器未必就绪）时机更晚更全，能安全注入并使用任何 Bean。两者唯一区别是拿参数方式：CommandLineRunner.run(String... args) 拿原始命令行参数数组（不解析）；ApplicationRunner.run(ApplicationArguments args) 拿封装解析后的对象（区分「选项参数 --key=value」getOptionNames/getOptionValues 和「非选项参数」getNonOptionArgs，更方便）。多个 Runner 用 @Order/Ordered 排序（数字小的先，两者在同一队列统一排序）。两个生产坑：① run() 抛异常会导致应用启动失败（关键检查失败该阻止启动、非关键任务要 try-catch 兜住）；② 同步执行会阻塞启动就绪（耗时任务应异步化）。注意 web 服务器在 Runner 执行时通常已开始接收请求，挡流量要用就绪探针。一句话「CommandLineRunner/ApplicationRunner 是启动后一次性初始化回调(容器就绪后执行、能用所有 Bean)，区别只在拿参数(原始数组 vs 解析后 ApplicationArguments)；@Order 排序；抛异常会导致启动失败(非关键要 try-catch)、同步阻塞启动(耗时异步化)」。