Spring Boot 钩子全集实战（十二）：`CommandLineRunner` 详解

Spring Boot 钩子全集实战（十二）：CommandLineRunner 详解

在上一篇中，我们深入剖析了 ApplicationRunner 这一应用启动完成前的核心扩展接口，实现了全局资源初始化、命令行参数解析的场景需求。今天，我们将继续跟进 Spring Boot 启动生命周期，解析与 ApplicationRunner 相辅相成的核心扩展接口 ——CommandLineRunner。

一、CommandLineRunner 是什么？

CommandLineRunner是Spring Boot 框架提供的专属扩展接口（位于 org.springframework.boot 包下），与 ApplicationRunner 同为 Spring Boot 应用启动流程的高级扩展点。

它的核心作用是让开发者实现该接口后，重写指定的业务方法，用于在 Spring 容器完全初始化完成、应用即将对外提供服务前，执行自定义的启动后业务逻辑，与 ApplicationRunner 功能定位高度一致，仅在命令行参数处理方式上存在差异。

二、CommandLineRunner 的执行时机

CommandLineRunner 接口方法的执行时机与 ApplicationRunner 紧密关联，遵循严格的 Spring Boot 启动生命周期顺序，具体完整执行链路如下：

0. Spring 容器启动，完成所有 Bean 的创建、依赖注入、初始化（构造方法 → DI → @PostConstruct → InitializingBean#afterPropertiesSet ()）；
1. 容器内所有 Bean 进入就绪状态，Spring 核心容器初始化完成；
2. Spring Boot 检测容器中是否有实现了 ApplicationRunner 接口的 Bean，若有则按指定顺序自动调用其重写的业务方法；
3. ApplicationRunner 执行完成后，Spring Boot 检测容器中是否有实现了 CommandLineRunner 接口的 Bean，若有则按指定顺序自动调用其重写的业务方法；
4. 内嵌 Web 容器（如 Tomcat）启动（若为 Web 应用），应用完成全部启动流程，对外提供服务。

执行时机核心总结：

所有 Bean 初始化完成 → ApplicationRunner 接口方法 → CommandLineRunner 接口方法 → 内嵌容器启动 → 应用就绪对外服务

接口方法说明：

CommandLineRunner 接口仅定义了一个无返回值、接收 String[] 类型参数的方法 run()，开发者只需让目标 Bean 实现该接口，并重写此方法即可写入启动后业务逻辑，String[] 参数对应应用启动时传入的原始命令行参数：

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

其中 String... args 为可变参数，等价于 String[] args，核心特点：

• 直接获取应用启动时传入的原始命令行参数，无任何封装处理；
• 对于带选项名的参数（如 --server.port=8081、--app.env=prod），不会进行解析，仅以完整字符串形式存入数组；
• 保留命令行参数的原始顺序，与传入顺序完全一致。

与 ApplicationRunner 的参数差异对比：

特性	ApplicationRunner	CommandLineRunner
参数类型	ApplicationArguments（封装对象）	String []（原始字符串数组）
参数解析能力	支持解析带选项名的参数（如 --key=value）	不支持解析，仅保留原始完整参数
扩展能力	提供 getOptionNames () 等便捷方法	无扩展方法，需手动处理参数数组
核心定位	复杂命令行参数解析、业务逻辑执行	简单参数接收、无复杂解析需求的场景

三、CommandLineRunner 的生产场景

CommandLineRunner 与 ApplicationRunner 场景高度重合，专注于 “应用启动完成前、所有 Bean 已就绪” 的全局启动任务，更适用于参数处理简单的场景，以下是最常见的生产落地场景：

场景一：应用启动后执行简单一次性任务 / 资源预热

项目启动完成后，需要执行无需复杂参数支持的一次性全局任务，如消息队列消费者启动、本地文件目录检测、基础数据预热等，此时 CommandLineRunner 实现更简洁，无需依赖封装的参数对象。

示例（检测并创建项目必需本地目录）：

@Component
@Slf4j
public class LocalDirCheckRunner implements CommandLineRunner {
    // 项目必需的本地目录路径
    private static final List<String> NECESSARY_DIRS = Arrays.asList(
            "./upload/files",
            "./log/business",
            "./temp/cache"
    );
​
    // 应用启动完成前，执行本地目录检测与创建
    @Override
    public void run(String... args) throws Exception {
        File file;
        for (String dirPath : NECESSARY_DIRS) {
            file = new File(dirPath);
            if (!file.exists()) {
                // 递归创建目录
                boolean mkdirsSuccess = file.mkdirs();
                if (mkdirsSuccess) {
                    log.info("本地目录创建成功：{}", dirPath);
                } else {
                    log.error("本地目录创建失败：{}", dirPath);
                    // 抛出异常终止应用启动，避免后续业务异常
                    throw new RuntimeException("必需本地目录创建失败，应用启动终止");
                }
            } else {
                log.info("本地目录已存在：{}", dirPath);
            }
        }
        log.info("所有必需本地目录检测与创建任务执行完成");
    }
}

场景二：解析简单命令行参数，执行自定义业务逻辑

应用启动时传入简单无复杂选项的命令行参数（如 prod、sync），或仅需对带选项名的参数进行简单匹配，无需精细解析，此时 CommandLineRunner 足以满足需求，实现更轻量化。

示例（解析简单启动参数执行基础数据初始化）：

@Component
@Slf4j
public class SimpleDataInitRunner implements CommandLineRunner {
    @Autowired
    private BasicDataInitService basicDataInitService;
​
    @Override
    public void run(String... args) throws Exception {
        // 1. 打印原始命令行参数
        log.info("应用启动原始命令行参数列表：{}", Arrays.toString(args));
​
        // 2. 解析简单参数（如传入 "init-basic-data" 则执行基础数据初始化）
        if (args != null && args.length > 0) {
            for (String arg : args) {
                if ("init-basic-data".equalsIgnoreCase(arg) 
                        || "--init-basic-data".equalsIgnoreCase(arg)) {
                    log.info("检测到启动参数：开启基础数据初始化，开始执行任务...");
                    basicDataInitService.initBasicDictData();
                    log.info("基础数据初始化任务执行完成");
                    break;
                }
            }
        }
    }
}

扩展一：指定多个 CommandLineRunner 的执行顺序

当容器中存在多个 CommandLineRunner 实现类时，可通过 @Order 注解或实现 Ordered 接口指定执行顺序， @Order 注解值越小，执行优先级越高，与 ApplicationRunner 的排序规则一致。

// 优先级高，先执行（在所有 Order > 1 的 CommandLineRunner 之前执行）
@Component
@Order(1)
@Slf4j
public class PrimaryCommandLineRunner implements CommandLineRunner {
    @Override
    public void run(String... args) throws Exception {
        log.info("第一个 CommandLineRunner 执行（优先级1）");
    }
}
​
// 优先级低，后执行（在 PrimaryCommandLineRunner 之后执行）
@Component
@Order(2)
@Slf4j
public class SecondaryCommandLineRunner implements CommandLineRunner {
    @Override
    public void run(String... args) throws Exception {
        log.info("第二个 CommandLineRunner 执行（优先级2）");
    }
}

扩展二：跨接口（ApplicationRunner + CommandLineRunner）的全局排序

当容器中同时存在 ApplicationRunner 和 CommandLineRunner 实现类时，@Order 注解可实现跨接口的全局排序 —— @Order 值越小，整体执行优先级越高，打破接口类型的限制。

示例（跨接口全局排序）：

// ApplicationRunner 实现类，Order=2
@Component
@Order(2)
@Slf4j
public class MyApplicationRunner implements ApplicationRunner {
    @Override
    public void run(ApplicationArguments args) throws Exception {
        log.info("ApplicationRunner 执行（全局优先级2）");
    }
}
​
// CommandLineRunner 实现类，Order=1（优先级更高，先于上面的 ApplicationRunner 执行）
@Component
@Order(1)
@Slf4j
public class MyCommandLineRunner implements CommandLineRunner {
    @Override
    public void run(String... args) throws Exception {
        log.info("CommandLineRunner 执行（全局优先级1）");
    }
}

执行结果（打破接口默认顺序，按 @Order 全局排序）：

CommandLineRunner 执行（全局优先级1）
ApplicationRunner 执行（全局优先级2）

四、总结

0. 核心定位：CommandLineRunner 是 Spring Boot 专属接口，与 ApplicationRunner 功能互补，核心用于在所有 Bean 初始化完成、应用对外服务前执行简单全局一次性启动任务，由 Spring Boot 容器自动触发，仅支持接收原始命令行参数；
1. 执行核心：严格遵循 “所有 Bean 初始化完成→ApplicationRunner（默认）→CommandLineRunner（默认）→内嵌容器启动→应用就绪” 的执行顺序，支持 @Order 注解实现接口内 / 跨接口的全局排序，值越小优先级越高；
2. 场景价值：在本地目录检测、简单参数解析、基础数据预热等无需复杂参数处理的生产场景中广泛应用，实现简洁轻量化，同时可依托已就绪的全量 Bean 保证任务执行的完整性；
3. 选型建议：复杂命令行参数解析（如 --key=value 格式）优先使用 ApplicationRunner，简单参数接收或无参数的一次性任务优先使用 CommandLineRunner。

📌 关注我，每天 5 分钟，带你从 Java 小白变身编程高手！

👉 点赞 + 关注 + 转发，让更多小伙伴一起进步！