Spring Boot 启动失败时那段「友好的错误提示」是怎么来的？FailureAnalyzer 是什么？

简化版

当 Spring Boot 启动失败时，控制台会打印一段格式化的、友好的错误提示（APPLICATION FAILED TO START + Description 描述问题 + Action 建议怎么解决），这背后是 FailureAnalyzer 机制。普通 Java 程序启动失败只会甩一大堆异常堆栈，让人一头雾水；Spring Boot 的 FailureAnalyzer 会捕获启动过程中的特定异常，翻译成「人话」——告诉你「问题是什么（Description）」和「该怎么办（Action）」。比如端口被占用，它不会只甩 BindException，而是清楚地说「端口 8080 已被占用，请换个端口或停掉占用它的进程」。原理：Spring Boot 内置了一批针对常见启动错误的 FailureAnalyzer（端口占用、Bean 循环依赖、找不到数据源配置、注入不到 Bean 等），启动失败时遍历它们，找到能「认识」这个异常的分析器，输出友好提示。可以自定义：实现 AbstractFailureAnalyzer<你关心的异常>，在 META-INF/spring.factories（或 3.x 的 imports 文件）注册，给自己框架/组件的特定启动错误也配上友好提示。

详细版

FailureAnalyzer 的输出格式：

***************************
APPLICATION FAILED TO START
***************************

Description:
  Web server failed to start. Port 8080 was already in use.   ← 问题是什么

Action:
  Identify and stop the process that's listening on port 8080
  or configure this application to listen on another port.    ← 怎么解决

Spring Boot 内置的常见 FailureAnalyzer：

分析器	处理的错误
PortInUseFailureAnalyzer	端口被占用
BeanCurrentlyInCreationFailureAnalyzer	Bean 循环依赖
NoSuchBeanDefinitionFailureAnalyzer	注入不到某个 Bean
BeanNotOfRequiredTypeFailureAnalyzer	Bean 类型不匹配
DataSourceBeanCreationFailureAnalyzer	数据源配置缺失/错误
InvalidConfigurationPropertyValueFailureAnalyzer	配置属性值非法

// 自定义 FailureAnalyzer：给自己组件的特定异常配友好提示
public class MyServiceFailureAnalyzer
        extends AbstractFailureAnalyzer<MyServiceNotConfiguredException> {
    @Override
    protected FailureAnalysis analyze(Throwable rootFailure,
                                      MyServiceNotConfiguredException cause) {
        return new FailureAnalysis(
            "MyService 没有配置连接地址",                        // Description
            "请在 application.yml 里设置 myservice.url",         // Action
            cause);
    }
}
// 注册（Spring Boot 3.x）：META-INF/spring/...AutoConfiguration.imports 或 spring.factories
// org.springframework.boot.diagnostics.FailureAnalyzer=com.example.MyServiceFailureAnalyzer

⚠️ FailureAnalyzer 的价值是「把机器语言翻译成人话」，提升排错效率——它不改变「程序确实启动失败了」这个事实，而是让你一眼看懂失败原因和解决办法，不用在几百行异常堆栈里大海捞针。这在团队协作里尤其有用：新人遇到启动失败，看 Action 提示就能自己解决，不用每次都问「这堆红字是啥意思」。写自己的框架/starter 时，为「用户常见的配置错误」写一个 FailureAnalyzer，是很专业的做法——比如「用户忘了配某个必需属性」，与其让他看到一堆 NullPointerException，不如直接告诉他「请配置 xxx」。这是「面向使用者的错误友好性」的体现。

完整版教学

一、问题：启动失败的异常堆栈太难懂

先理解 FailureAnalyzer 要解决的痛点：

普通 Java 程序启动失败：
  甩出一大堆异常堆栈（几十上百行）
  Caused by: ... Caused by: ... Caused by: ...
  → 要在层层嵌套的堆栈里找"根因"
  → 对新手/不熟悉的错误，很难快速定位

例：端口被占用，原始异常大概是：
  org.springframework.boot...BindException
   Caused by: java.net.BindException: Address already in use
   （还夹杂大量 Spring 内部调用栈）
  → 你得看懂"BindException + Address already in use = 端口占用"

痛点：
  - 异常堆栈是"给程序员看的技术细节"，不是"解决方案"
  - 常见错误反复出现，每次都要重新理解堆栈
  → 需要把常见错误"翻译成人话 + 给解决方案"

FailureAnalyzer 要解决的痛点是「启动失败的异常堆栈太难懂」——普通程序失败甩一大堆嵌套堆栈，要在里面找根因，对新手和不熟悉的错误很难快速定位。异常堆栈是「给程序员看的技术细节」，不是「解决方案」。而且常见错误反复出现，每次都要重新理解。需要把常见错误「翻译成人话 + 给解决方案」。理解「启动失败堆栈太难懂、要在嵌套堆栈找根因、异常是技术细节不是解决方案、需要翻译成人话」，就理解了 FailureAnalyzer 的动机。

二、FailureAnalyzer 做什么

FailureAnalyzer 的职责是「捕获特定异常，翻译成 Description + Action」：

FailureAnalyzer 接口（简化）：
  FailureAnalysis analyze(Throwable failure);
  → 输入：启动失败的异常
  → 输出：一个 FailureAnalysis（含 description 和 action），或 null

FailureAnalysis 包含：
  - description：问题是什么（人话描述）
  - action：该怎么解决（可操作的建议）
  - cause：原始异常（保留，供深入排查）

效果：把
  "一堆技术异常堆栈"
  变成
  "Description: 端口 8080 被占用
   Action: 停掉占用进程或换端口"
  → 一眼看懂 + 知道怎么办

FailureAnalyzer 的职责是「输入异常、输出 FailureAnalysis（description 问题 + action 解决办法 + cause 原始异常）」——把技术异常堆栈翻译成「问题是什么 + 该怎么解决」。它保留原始异常供深入排查，但把「人话描述」和「可操作建议」凸显出来。理解「FailureAnalyzer.analyze 输入异常输出 FailureAnalysis(description 问题+action 建议+cause 原始异常)、把堆栈翻译成人话和解决办法」，就理解了它的职责。

三、内置的常见 FailureAnalyzer

Spring Boot 内置了一批针对常见启动错误的分析器：

常见内置分析器（覆盖高频启动错误）：
  PortInUseFailureAnalyzer：端口被占用
    → "Port 8080 was already in use" + "换端口或停占用进程"
  BeanCurrentlyInCreationFailureAnalyzer：Bean 循环依赖
    → 画出循环依赖的链路 + "打破循环（@Lazy 或重构）"
  NoSuchBeanDefinitionFailureAnalyzer：注入不到某 Bean
    → "找不到类型 X 的 Bean" + "检查是否漏标注解/漏配置"
  DataSourceBeanCreationFailureAnalyzer：数据源问题
    → "无法配置数据源：url 未指定" + "配置 spring.datasource.url 或引入嵌入式数据库"
  InvalidConfigurationPropertyValueFailureAnalyzer：配置值非法

这些覆盖了新手最常遇到的启动错误：
  端口占用、循环依赖、注入不到、数据源没配
  → 每个都给出清晰的 Description + Action

Spring Boot 内置了一批分析器覆盖高频启动错误：端口占用（PortInUseFailureAnalyzer）、Bean 循环依赖（BeanCurrentlyInCreationFailureAnalyzer，还会画出循环链路）、注入不到 Bean（NoSuchBeanDefinitionFailureAnalyzer）、数据源没配（DataSourceBeanCreationFailureAnalyzer）、配置值非法等。这些正是新手最常遇到的启动错误，每个都给清晰的 Description + Action。理解「内置分析器覆盖端口占用/循环依赖/注入不到/数据源没配等高频错误、各给 Description+Action」，就理解了内置分析器的覆盖范围。

四、工作机制：启动失败时的分析流程

理解 FailureAnalyzer 是「怎么被触发的」：

工作流程：
  1. SpringApplication.run() 过程中抛出异常（启动失败）
  2. Spring Boot 捕获这个异常（不是直接甩堆栈就退出）
  3. FailureAnalyzers（一个协调器）遍历所有注册的 FailureAnalyzer
  4. 依次问每个分析器："你能分析这个异常吗？"
     - 每个 FailureAnalyzer 通常只认某一类异常
       （通过泛型 AbstractFailureAnalyzer<SpecificException> 声明）
     - 遍历异常链，找到某个分析器能处理的异常类型
  5. 第一个能处理的分析器返回 FailureAnalysis
  6. FailureAnalysisReporter 把它格式化输出到控制台
     （就是那段 APPLICATION FAILED TO START）
  7. 应用退出

关键：
  - 分析器是"按异常类型匹配"的，认识就处理、不认识就跳过
  - 如果没有任何分析器认识这个异常 → 回退到打印原始堆栈
    （所以奇怪的错误还是会看到堆栈，只有"已知常见错误"才有友好提示）

FailureAnalyzer 的工作流程：启动抛异常 → Spring Boot 捕获 → 遍历所有 FailureAnalyzer 问「你能分析吗」（每个只认某类异常，通过泛型声明）→ 第一个能处理的返回 FailureAnalysis → 格式化输出。关键：分析器按异常类型匹配，认识就处理、不认识就跳过；如果没有任何分析器认识这个异常，回退到打印原始堆栈（所以只有「已知常见错误」才有友好提示，奇怪错误还是看堆栈）。理解「启动失败时遍历 FailureAnalyzer 按异常类型匹配、第一个认识的返回分析结果格式化输出、都不认识则回退打印堆栈」，就理解了它的工作机制。

五、自定义 FailureAnalyzer

给自己的框架/组件配友好提示，实现 AbstractFailureAnalyzer：

自定义步骤：
  1. 定义你关心的异常（或用现成的）
     class MyServiceNotConfiguredException extends RuntimeException {}

  2. 继承 AbstractFailureAnalyzer<你的异常>
     class MyAnalyzer extends AbstractFailureAnalyzer<MyServiceNotConfiguredException> {
        protected FailureAnalysis analyze(Throwable root, MyServiceNotConfiguredException cause) {
            return new FailureAnalysis(
                "MyService 未配置连接地址",              // description
                "请在 application.yml 配置 myservice.url",  // action
                cause);
        }
     }
     → AbstractFailureAnalyzer 帮你从异常链里"找出"你声明的那类异常

  3. 注册：
     Spring Boot 2.x：META-INF/spring.factories
       org.springframework.boot.diagnostics.FailureAnalyzer=com.example.MyAnalyzer
     Spring Boot 3.x：也支持 spring.factories 注册 FailureAnalyzer
       （注意：FailureAnalyzer 不能是 Spring Bean，因为启动失败时
        容器可能都没起来 → 用 spring.factories 而非 @Component）

  4. 效果：当你的组件抛出 MyServiceNotConfiguredException 导致启动失败
     → 控制台显示你写的友好提示，而不是一堆堆栈

自定义 FailureAnalyzer：① 继承 AbstractFailureAnalyzer<你的异常>（它帮你从异常链里找出声明的异常类型）；② 在 analyze 里返回 FailureAnalysis（description + action）；③ 在 META-INF/spring.factories 注册（注意 FailureAnalyzer 不能是 Spring Bean，因为启动失败时容器可能没起来，所以用 spring.factories 而非 @Component）。这样你的组件抛特定异常导致启动失败时，显示你写的友好提示。理解「自定义 FailureAnalyzer:继承 AbstractFailureAnalyzer<异常>、analyze 返回 FailureAnalysis、spring.factories 注册(不能是 Bean 因为容器可能没起来)」，就掌握了自定义方法。

六、为什么不能是 Spring Bean

一个关键细节：FailureAnalyzer 为什么用 spring.factories 注册而非 @Component：

问题：FailureAnalyzer 处理的是"启动失败"
  → 启动失败时，Spring 容器可能还没完全起来（甚至根本没起来）
  → 如果 FailureAnalyzer 是 @Component（Spring Bean）
    容器都没起来，怎么拿到这个 Bean 来分析异常？
  → 矛盾！

解决：FailureAnalyzer 用 spring.factories 注册
  spring.factories 是 Spring Boot 用"自己的加载机制"（SpringFactoriesLoader）
  在启动极早期就能加载的，不依赖容器就绪
  → 即使容器没起来，也能加载 FailureAnalyzer 来分析启动异常

例外：如果你的 FailureAnalyzer 需要用到容器里的 Bean
  Spring Boot 提供了让它感知 BeanFactory/Environment 的方式
  （实现 BeanFactoryAware/EnvironmentAware，Spring Boot 会尽量注入
   已就绪的部分），但要小心——那些 Bean 可能因启动失败而不可用

核心：处理"启动失败"的东西，不能依赖"启动成功"（容器就绪）

FailureAnalyzer 用 spring.factories 注册而非 @Component，是因为「它处理启动失败，而失败时容器可能没起来」——如果它是 Spring Bean，容器都没起来就拿不到它来分析异常，矛盾。spring.factories 用 SpringFactoriesLoader 在启动极早期加载，不依赖容器就绪。核心原则：「处理启动失败的东西，不能依赖启动成功（容器就绪）」。这和前面「监听早期事件用 spring.factories」是同一逻辑。理解「FailureAnalyzer 不能是 Bean 因为启动失败时容器可能没起来、用 spring.factories 早期加载不依赖容器、处理失败的东西不能依赖成功」，就理解了这个设计细节。

记忆钩子：「FailureAnalyzer=Spring Boot 启动失败时的’异常翻译官’,把技术异常堆栈翻译成友好提示(APPLICATION FAILED TO START + Description 问题是什么 + Action 怎么解决);内置一批覆盖高频错误:端口占用/Bean循环依赖/注入不到Bean/数据源没配;机制:启动失败时遍历所有 FailureAnalyzer 按异常类型匹配、第一个认识的返回 FailureAnalysis 格式化输出、都不认识则回退打印堆栈;自定义:继承 AbstractFailureAnalyzer<异常>、analyze 返回 FailureAnalysis、spring.factories 注册(不能是 Bean 因为启动失败时容器可能没起来)」。

七、常见误区与追问

误区：那段友好的启动失败提示是 JVM 或日志框架提供的。 是 Spring Boot 的 FailureAnalyzer 机制——它捕获启动异常、翻译成 Description（问题）+ Action（解决办法）格式化输出；普通 Java 程序或非 Spring Boot 应用没有这个，只会甩原始堆栈。
误区：FailureAnalyzer 能分析所有启动异常。 只能分析「已注册的分析器认识的异常类型」——每个 FailureAnalyzer 通过泛型声明它处理哪类异常；如果没有任何分析器认识某个异常，会回退到打印原始堆栈（所以奇怪错误还是看堆栈）。
误区：FailureAnalyzer 用 @Component 注册。 不能——它处理启动失败，而失败时 Spring 容器可能还没起来，用 @Component（Bean）就拿不到；必须用 META-INF/spring.factories 注册（SpringFactoriesLoader 早期加载、不依赖容器就绪）。
误区：FailureAnalyzer 会修复错误让应用启动成功。 不会——它只是「翻译错误、给建议」，不改变「启动失败」的事实；应用还是会退出，只是让你看懂原因、知道怎么修（提升排错效率，不是自动修复）。
追问：端口被占用时那段友好提示是谁给的？ PortInUseFailureAnalyzer——它认识端口绑定失败的异常（PortInUseException），输出 Description「端口 X 已被占用」和 Action「停掉占用进程或换端口」，而不是甩原始的 BindException 堆栈。
追问：怎么给自己的 starter 加启动失败的友好提示？ 定义组件的特定异常，继承 AbstractFailureAnalyzer<该异常> 实现 analyze 返回 FailureAnalysis（description + action），在 META-INF/spring.factories 里注册为 FailureAnalyzer；这样用户配置错误导致启动失败时，看到的是清晰提示而非一堆堆栈——是专业 starter 的做法。
追问：为什么 FailureAnalyzer、早期事件监听器都用 spring.factories 注册？ 因为它们都要在「容器还没就绪/启动失败」时工作，不能依赖 Spring 容器（@Component 需要容器扫描注册）；spring.factories 用 SpringFactoriesLoader 在启动极早期加载，不依赖容器，正好满足「处理启动阶段的东西不能依赖启动成功」这个要求。

八、加强记忆

Spring Boot 启动失败时那段友好提示（APPLICATION FAILED TO START + Description 问题是什么 + Action 怎么解决）来自 FailureAnalyzer 机制——它捕获启动过程的特定异常，翻译成「人话」（问题描述 + 解决建议），而非甩一堆异常堆栈。输出结构：FailureAnalysis（description 问题 + action 建议 + cause 原始异常）。内置分析器覆盖高频启动错误：端口占用（PortInUseFailureAnalyzer）、Bean 循环依赖（会画出循环链路）、注入不到 Bean、数据源没配、配置值非法等。工作机制：启动失败时遍历所有 FailureAnalyzer、按异常类型匹配（每个通过泛型声明处理哪类异常）、第一个认识的返回 FailureAnalysis 格式化输出；都不认识则回退打印原始堆栈（所以只有已知常见错误才有友好提示）。自定义：继承 AbstractFailureAnalyzer<你的异常>、在 analyze 返回 FailureAnalysis、在 META-INF/spring.factories 注册——不能用 @Component，因为启动失败时容器可能没起来、拿不到 Bean（spring.factories 用 SpringFactoriesLoader 早期加载不依赖容器，与早期事件监听器同理）。它只翻译错误不修复错误。一句话「FailureAnalyzer 是启动失败的异常翻译官,把堆栈翻译成 Description(问题)+Action(解决);内置覆盖端口占用/循环依赖/注入不到/数据源没配;遍历按异常类型匹配、认识就翻译不认识回退打印堆栈;自定义继承 AbstractFailureAnalyzer 并 spring.factories 注册(不能是 Bean 因为失败时容器可能没起来)」。

简化版

详细版