Spring Boot 应用（官网文档解读）

package person.wend.springbootlearnexample2.failureanalyzer;

import org.springframework.boot.diagnostics.AbstractFailureAnalyzer;
import org.springframework.boot.diagnostics.FailureAnalysis;


public class CustomFailureAnalyzer extends AbstractFailureAnalyzer<CustomStartupException> {

    @Override
    protected FailureAnalysis analyze(Throwable rootFailure, CustomStartupException cause) {
        // 错误描述
        String description = "自定义启动错误：" + cause.getMessage();
        // 操作建议
        String action = "请检查相关配置或联系系统管理员。";
        return new FailureAnalysis(description, action, cause);
    }
}

package person.wend.springbootlearnexample2.failureanalyzer;

import org.springframework.boot.diagnostics.AbstractFailureAnalyzer;
import org.springframework.boot.diagnostics.FailureAnalysis;


public class CustomFailureAnalyzer extends AbstractFailureAnalyzer<CustomStartupException> {

    @Override
    protected FailureAnalysis analyze(Throwable rootFailure, CustomStartupException cause) {
        // 错误描述
        String description = "自定义启动错误：" + cause.getMessage();
        // 操作建议
        String action = "请检查相关配置或联系系统管理员。";
        return new FailureAnalysis(description, action, cause);
    }
}

• 应用程序组件可以随时通过注入接口ApplicationAvailability并调用其方法来检索当前可用性状态。更常见的是，应用程序希望监听状态更新或更新应用程序的状态。

• Spring Boot通过 Actuator Health Endpoints 为 Kubernetes 提供了“活跃度”和“就绪度”的 HTTP 探测。

• 例如，我们可以将应用程序的“就绪”状态导出到文件，以便 Kubernetes“exec Probe”可以查看此文件：

@Component
public class MyReadinessStateExporter {

	@EventListener
	public void onStateChange(AvailabilityChangeEvent<ReadinessState> event) {
		switch (event.getState()) {
			case ACCEPTING_TRAFFIC -> {
				// create file /tmp/healthy
			}
			case REFUSING_TRAFFIC -> {
				// remove file /tmp/healthy
			}
		}
	}

}

• 当应用程序崩溃且无法恢复时，我们还可以更新应用程序的状态：

@Component
public class MyLocalCacheVerifier {

	private final ApplicationEventPublisher eventPublisher;

	public MyLocalCacheVerifier(ApplicationEventPublisher eventPublisher) {
		this.eventPublisher = eventPublisher;
	}

	public void checkLocalCache() {
		try {
			// ...
		}
		catch (CacheCompletelyBrokenException ex) {
			AvailabilityChangeEvent.publish(this.eventPublisher, ex, LivenessState.BROKEN);
		}
	}

}

应用程序事件监听器

• 在Spring Boot项目中，我们一般可以使用ContextRefreshedEvent来监听一个事件。ContextRefreshedEvent 是 Spring 框架中的一个事件，当 ApplicationContext 被初始化或者刷新时会发布该事件。

• 我们可以使用SpringApplication.addListeners(…​)或SpringApplicationBuilder.listeners(…​)注册一个监听器。

• 我们也可以通过在 META-INF/spring.factories添加监听器的方式注册一个监听器的Bean。

示例代码

package person.wend.springbootlearnexample2.event;

import org.springframework.context.ApplicationListener;
import org.springframework.context.event.ContextRefreshedEvent;
import org.springframework.stereotype.Component;

@Component
public class ContextRefreshedEventListener implements ApplicationListener<ContextRefreshedEvent> {

    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        // 获取事件源，即 ApplicationContext
        var applicationContext = event.getApplicationContext();

        // 可以在这里执行一些初始化操作，比如获取 Bean 等
        System.out.println("ContextRefreshedEvent 事件被触发，ApplicationContext 已刷新。");
        System.out.println("当前 ApplicationContext 中的 Bean 数量: " + applicationContext.getBeanDefinitionCount());
    }
}

Spring Boot 事件触发顺序

        Spring Boot 应用在运行过程中，各类事件按照以下顺序依次执行：

1. ApplicationStartingEvent：应用启动时触发，此时仅完成监听器和初始化器的注册，其他处理工作尚未开展。

2. ApplicationEnvironmentPreparedEvent：当明确了应用上下文要使用的环境配置，但上下文还未创建时触发该事件。

3. ApplicationContextInitializedEvent：应用上下文准备完毕，且上下文初始化器完成调用，但 Bean 定义尚未加载时触发此事件。

4. ApplicationPreparedEvent：Bean 定义加载完成后，上下文刷新操作启动之前触发该事件。

5. ApplicationStartedEvent：上下文刷新完成，但应用程序和命令行运行器还未调用时触发此事件。

6. AvailabilityChangeEvent（LivenessState.CORRECT）：在 ApplicationStartedEvent 之后立即触发，表明应用处于存活状态。

7. ApplicationReadyEvent：应用程序和命令行运行器调用完成后触发此事件。

8. AvailabilityChangeEvent（ReadinessState.ACCEPTING_TRAFFIC）：在 ApplicationReadyEvent 之后立即触发，意味着应用已准备好处理请求。

9. ApplicationFailedEvent：若应用在启动过程中出现异常，则触发该事件。

        上面的列表仅包括绑定到SpringApplication的SpringApplicationEvents。除此之外，以下事件也在ApplicationPreparedEvent之后和ApplicationStartedEvent之前发布：

• WebServer就绪后发送WebServerInitializedEvent。ServletWebServerInitializedEvent和ReactiveWebServerIninitializedEvent分别是servlet和反应式变体。

• 刷新ApplicationContext时发送ContextRefreshedEvent。

Web环境

        SpringApplication试图代表您创建正确类型的ApplicationContext。用于确定WebApplicationType的算法如下：

• 如果存在Spring MVC，则使用AnnotationConfigServletWebServerApplicationContext

• 如果Spring MVC不存在，并且Spring WebFlux存在，则使用AnnotationConfigReactiveWebServerApplicationContext

• 否则，将使用AnnotationConfigApplicationContext

        这意味着，如果您在同一应用程序中使用SpringMVC和SpringWebFlux中的新WebClient，则默认情况下将使用Spring MVC。

• 您可以通过调用setWebApplicationType（WebApplicationType）轻松地覆盖它。

• 还可以完全控制通过调用setApplicationContextFactory（…）修改使用的ApplicationContext类型。

ApplicationArguments 访问应用程序命令参数

   ApplicationArguments 是 Spring Boot 中的一个接口，用于在应用启动时访问传递给应用的命令行参数。以下从功能、使用场景、使用方式等方面详细介绍其作用。

主要功能

• 解析命令行参数：ApplicationArguments 接口可以将传递给 Spring Boot 应用的命令行参数解析为选项参数（以 -- 开头的参数）和非选项参数，方便开发者对不同类型的参数进行处理。

• 提供参数访问方法：该接口提供了一系列方法，用于获取选项参数的名称、值，以及非选项参数的列表，开发者可以根据需要灵活使用这些方法。

使用场景

• 配置应用行为：通过命令行参数可以动态配置应用的行为，例如指定应用的运行模式（开发模式、生产模式）、数据库连接信息等。

• 传递自定义参数：在应用启动时传递一些自定义的参数，用于执行特定的任务或进行初始化操作。

• 测试和调试：在测试和调试过程中，可以通过命令行参数传递不同的配置，方便对应用进行测试和排查问题。

示例代码

import org.springframework.boot.ApplicationArguments;
import org.springframework.stereotype.Component;

@Component
public class MyCommandLineArgsHandler {

    public MyCommandLineArgsHandler(ApplicationArguments args) {
        // 获取所有选项参数的名称
        System.out.println("选项参数名称: " + args.getOptionNames());

        // 检查是否包含某个选项参数
        if (args.containsOption("debug")) {
            System.out.println("应用以调试模式启动。");
        }

        // 获取某个选项参数的值
        if (args.containsOption("port")) {
            System.out.println("指定的端口号: " + args.getOptionValues("port"));
        }

        // 获取非选项参数的列表
        System.out.println("非选项参数: " + args.getNonOptionArgs());
    }
}

CommandLineRunner 

   CommandLineRunner 接口位于 org.springframework.boot 包下，是一个函数式接口，只包含一个抽象方法 run，定义如下：

package org.springframework.boot;

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

   run 方法接收一个 String 数组参数 args，这个参数包含了应用程序启动时传递的命令行参数。该方法会在 Spring 应用上下文完全初始化之后被调用。

• 使用示例：

import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

@Component
public class MyCommandLineRunner implements CommandLineRunner {

    @Override
    public void run(String... args) throws Exception {
        System.out.println("应用启动后执行的代码逻辑...");
        for (String arg : args) {
            System.out.println("命令行参数: " + arg);
        }
    }
}

ApplicationRunner

   ApplicationRunner 接口同样位于 org.springframework.boot 包下，也是一个函数式接口，其抽象方法 run 接收一个 ApplicationArguments 类型的参数，定义如下：

package org.springframework.boot;

import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;

@FunctionalInterface
public interface ApplicationRunner extends Ordered {
    void run(ApplicationArguments args) throws Exception;
}

   ApplicationArguments 是一个封装了命令行参数的对象，它提供了更方便的方法来处理选项参数和非选项参数。

• 使用示例

import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.stereotype.Component;

@Component
public class MyApplicationRunner implements ApplicationRunner {

    @Override
    public void run(ApplicationArguments args) throws Exception {
        System.out.println("应用启动后执行的代码逻辑...");
        System.out.println("选项参数: " + args.getOptionNames());
        System.out.println("非选项参数: " + args.getNonOptionArgs());
    }
}

使用场景

• 数据初始化：在应用启动后，你可能需要初始化一些数据到数据库或者缓存中，比如加载配置文件、初始化字典数据等。

• 资源预热：提前加载一些常用的资源，以减少后续请求的响应时间，例如预热缓存、初始化连接池等。

• 启动脚本：执行一些启动时的脚本任务，如检查系统环境、创建必要的文件目录等。

两者的区别

• 参数类型：CommandLineRunner 的 run 方法接收的是一个 String 数组，需要开发者自己解析命令行参数；而 ApplicationRunner 的 run 方法接收的是一个 ApplicationArguments 对象，它对命令行参数进行了封装，提供了更方便的方法来处理选项参数和非选项参数。

• 使用场景：如果只是简单地处理命令行参数，CommandLineRunner 就足够了；如果需要更复杂的参数处理，如区分选项参数和非选项参数，ApplicationRunner 会更合适。

@Order 控制顺序执行

        如果程序中存在多个CommandLineRunnner 或者 ApplicationRunner，我们可以使用@Order注解来控制bean 类的最终执行顺序。

应用程序退出

        在 Spring Boot 中，SpringApplication.exit() 方法用于优雅地关闭 Spring Boot 应用程序。该方法会执行一系列的关闭操作，包括：

• 触发 DisposableBean 接口的 destroy() 方法，让实现该接口的 Bean 有机会进行资源清理。

• 调用 SmartLifecycle 接口的 stop() 方法，停止那些实现了该接口的生命周期组件。

• 关闭 ApplicationContext，释放相关资源。

  SpringApplication.exit() 方法会返回一个退出码（int 类型），这个退出码可以用于指示应用程序的退出状态，通常 0 表示正常退出，非 0 表示异常退出。

使用场景

• 程序正常结束：当应用程序完成了它的任务，需要正常关闭时，可以调用该方法。例如，一个定时任务应用在完成所有任务后，主动退出。

• 异常处理：在应用程序遇到严重错误，无法继续运行时，可以调用该方法并返回一个非 0 的退出码，以指示应用程序异常退出。

• 自动化测试：在自动化测试中，测试完成后可以调用该方法关闭应用程序，确保资源被正确释放。

示例代码

正常退出

import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;

@SpringBootApplication
public class NormalExitExample implements CommandLineRunner {

    public static void main(String[] args) {
        ConfigurableApplicationContext context = SpringApplication.run(NormalExitExample.class, args);
    }

    @Override
    public void run(String... args) throws Exception {
        System.out.println("应用程序开始执行任务...");
        // 模拟执行一些任务
        Thread.sleep(2000);
        System.out.println("任务执行完成，准备退出应用程序。");

        // 获取当前的应用上下文
        ConfigurableApplicationContext context = SpringApplication.run(NormalExitExample.class, args);
        // 调用 exit 方法正常退出应用程序，返回退出码 0
        int exitCode = SpringApplication.exit(context, () -> 0);
        System.exit(exitCode);
    }
}

异常退出

import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;

@SpringBootApplication
public class ExceptionExitExample implements CommandLineRunner {

    public static void main(String[] args) {
        ConfigurableApplicationContext context = SpringApplication.run(ExceptionExitExample.class, args);
    }

    @Override
    public void run(String... args) throws Exception {
        System.out.println("应用程序开始执行任务...");
        try {
            // 模拟抛出异常
            throw new RuntimeException("发生了严重错误！");
        } catch (RuntimeException e) {
            System.err.println("捕获到异常: " + e.getMessage());
            System.err.println("准备异常退出应用程序。");

            // 获取当前的应用上下文
            ConfigurableApplicationContext context = SpringApplication.run(ExceptionExitExample.class, args);
            // 调用 exit 方法异常退出应用程序，返回退出码 1
            int exitCode = SpringApplication.exit(context, () -> 1);
            System.exit(exitCode);
        }
    }
}

ExitCodeGenerator 定义退出代码

 @Bean
    public ExitCodeGenerator exitCodeGenerator() {
        return () -> 42;
    }

    public static void main(String[] args) {
        System.exit(SpringApplication.exit(SpringApplication.run(SpringBootLearnExample2Application.class, args)));
    }

管理功能

        我们可以通过指定 spring.application.admin.enabled 属性可开启应用的管理相关功能，开启后会在平台的 MBeanServer 上暴露 SpringApplicationAdminMXBean，可用于远程管理 Spring Boot 应用，对服务包装器实现也有帮助。

应用程序启动追踪

        在应用启动期间，SpringApplication 和 ApplicationContext 会执行众多与应用生命周期、Bean 生命周期及应用事件处理相关的任务。借助 ApplicationStartup，Spring 框架允许使用 StartupStep 对象跟踪应用的启动序列，这些数据可用于性能分析或帮助更好地理解应用启动过程。

        在设置 SpringApplication 实例时可选择 ApplicationStartup 的实现类。例如，可使用 BufferingApplicationStartup，代码示例展示了如何配置该实现类。

@SpringBootApplication
public class MyApplication {

	public static void main(String[] args) {
		SpringApplication application = new SpringApplication(MyApplication.class);
		application.setApplicationStartup(new BufferingApplicationStartup(2048));
		application.run(args);
	}

}

• 具体实现类介绍

  • FlightRecorderApplicationStartup：由 Spring 框架提供，它将 Spring 特定的启动事件添加到 Java Flight Recorder 会话中，用于分析应用程序并关联 Spring 上下文生命周期与 JVM 事件。配置后，可通过启用 Java Flight Recorder 来记录数据。

  • BufferingApplicationStartup：Spring Boot 自带的实现类，用于缓冲启动步骤并将其输出到外部指标系统。应用程序可在任何组件中获取该类型的 Bean。

• 额外配置：Spring Boot 还可配置暴露一个启动端点，以 JSON 文档形式提供启动跟踪信息。

虚拟线程

        在 Java 21 及更高版本中，Spring Boot 支持使用虚拟线程。虚拟线程是 Java 平台引入的轻量级线程，它旨在简化并发编程，提高应用程序的吞吐量和资源利用率。与传统的操作系统线程相比，虚拟线程的创建和销毁成本更低，能够在相同的硬件资源下处理更多的并发任务。

• 启用虚拟线程：要在 Spring Boot 应用中启用虚拟线程，需要设置 spring.threads.virtual.enabled 属性为 true。

• 线程池配置的变化：当启用虚拟线程后，配置线程池的属性将不再生效。这是因为虚拟线程是在 JVM 全局的平台线程池上进行调度，而不是在专用的线程池上。

• 处理守护线程问题：虚拟线程是守护线程，这意味着如果 JVM 中的所有线程都是守护线程，JVM 将退出。例如，当使用 @Scheduled 注解的 Bean 来保持应用程序运行时，可能会出现问题。因为调度器线程是虚拟线程，也就是守护线程，无法使 JVM 保持运行。为了解决这个问题，可以设置 spring.main.keep-alive 属性为 true，确保即使所有线程都是虚拟线程，JVM 也能保持运行。

示例代码

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableScheduling;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;

@SpringBootApplication
@EnableScheduling
public class VirtualThreadExampleApplication {

    public static void main(String[] args) {
        SpringApplication application = new SpringApplication(VirtualThreadExampleApplication.class);
        // 模拟在代码中设置属性
        application.setDefaultProperties(java.util.Map.of(
                "spring.threads.virtual.enabled", "true",
                "spring.main.keep-alive", "true"
        ));
        application.run(args);
    }
}

@Component
class ScheduledTask {

    @Scheduled(fixedRate = 5000)
    public void performTask() {
        System.out.println("Scheduled task is running...");
    }
}

        在上述示例中，我们启用了虚拟线程和定时任务，并设置了 spring.main.keep-alive 属性为 true，以确保 JVM 不会因为虚拟线程是守护线程而提前退出。

参考文献

SpringApplication :: Spring Boot