FailureAnalyzer 与错误分析

概述

Spring Boot 在启动过程中会执行大量的自动配置和 Bean 初始化操作，这个阶段可能发生各种异常。Spring Boot 提供了 FailureAnalyzer 机制——一种 SPI 驱动的启动失败分析框架，能将原始异常转化为人类可读的诊断报告，包含问题描述、根本原因和修复建议。

启动失败与应用上下文的关系

失败阶段

环境准备：加载配置文件、激活 Profile 等
ApplicationContext 刷新：执行 refresh() 方法
自动配置类加载：通过 AutoConfigurationImportSelector 加载自动配置
Bean 实例化与依赖注入：创建 Bean 实例，执行初始化方法

refresh() 的异常处理

java

// AbstractApplicationContext.java
@Override
public void refresh() throws BeansException, IllegalStateException {
    synchronized (this.startupShutdownMonitor) {
        try {
            // 各刷新步骤
        } catch (BeansException ex) {
            logger.warn("Exception encountered during context initialization - " +
                "cancelling refresh attempt: " + ex);
            destroyBeans();   // 销毁已创建的单例 Bean
            cancelRefresh(ex);
            throw ex;
        }
    }
}

Spring Boot 在外层捕获该异常后运行所有注册的 FailureAnalyzer 生成诊断报告。

失败后资源清理

应用上下文处于不可用状态，无法获取任何 Bean
已打开的 Spring 管理资源（如数据库连接）会被正常关闭
非 Spring 管理资源可能泄漏，需开发者自行处理

FailureAnalyzer SPI 机制原理

核心接口

java

// org.springframework.boot.diagnostics.FailureAnalyzer
@FunctionalInterface
public interface FailureAnalyzer {
    FailureAnalysis analyze(Throwable failure);
}

FailureAnalysis 包含三个核心信息：

java

public class FailureAnalysis {
    private final String description;   // 问题描述
    private final String action;        // 修复建议
    private final Throwable cause;      // 根本原因
}

SPI 加载机制

通过 SpringFactoriesLoader 加载，入口在 FailureAnalyzers 类：

java

final class FailureAnalyzers {
    private final List<FailureAnalyzer> analyzers;

    FailureAnalyzers(ClassLoader classLoader) {
        // 从 spring.factories 加载 FailureAnalyzer 实现
        List<String> classNames = SpringFactoriesLoader
            .loadFactoryNames(FailureAnalyzer.class, classLoader);
        List<FailureAnalyzer> analyzers = new ArrayList<>();
        for (String className : classNames) {
            try {
                analyzers.add((FailureAnalyzer) InstantiationUtil
                    .instantiate(className, classLoader));
            } catch (Throwable ex) {
                // 单个加载失败不影响其他
            }
        }
        AnnotationAwareOrderComparator.sort(analyzers);
        this.analyzers = Collections.unmodifiableList(analyzers);
    }

    FailureAnalysis analyze(Throwable failure, Throwable rootCause) {
        for (FailureAnalyzer analyzer : this.analyzers) {
            try {
                FailureAnalysis analysis = analyzer.analyze(failure, rootCause);
                if (analysis != null) return analysis;
            } catch (Throwable ex) { /* 忽略单个 Analyzer 异常 */ }
        }
        return null;
    }
}

配置位置

Spring Boot 2.x 在 META-INF/spring.factories 注册，Spring Boot 3.x 改用 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。

AbstractFailureAnalyzer 基类

封装了异常链查找逻辑，子类只需关注分析：

java

public abstract class AbstractFailureAnalyzer<T extends Throwable>
        implements FailureAnalyzer {

    @Override
    public FailureAnalysis analyze(Throwable failure) {
        T cause = findCause(failure, getCauseType()); // 遍历异常链查找目标类型
        if (cause != null) {
            return analyze(failure, cause);
        }
        return null;
    }

    protected abstract FailureAnalysis analyze(Throwable rootFailure, T cause);
}

内置 FailureAnalyzer 一览

FailureAnalyzer	关联异常	诊断场景
`DataSourceBeanCreationFailureAnalyzer`	`DataSourceCreationException`	数据源创建失败，URL 格式错误、驱动类找不到
`HikariDriverConfigurationFailureAnalyzer`	`HikariConfigurationException`	HikariCP 配置错误，驱动类与 URL 不匹配
`R2dbcFailureAnalyzer`	`R2dbcException`	R2DBC 响应式数据库连接失败
`RedisFailureAnalyzer`	`RedisConnectionFailureException`	Redis 连接失败，网络不可达或认证失败
`MongoDBFailureAnalyzer`	`MongoException`	MongoDB 连接或认证失败
`ElasticSearchFailureAnalyzer`	`ElasticsearchException`	Elasticsearch 客户端初始化失败
`RabbitListenerEndpointRegistryFailureAnalyzer`	`BeanInstantiationException`	RabbitMQ 监听器端点注册失败
`KafkaFailureAnalyzer`	`KafkaException`	Kafka 连接失败
`WebClientFailureAnalyzer`	`WebClientRequestException`	WebClient HTTP 请求失败
`BindFailureAnalyzer`	`BindException`	配置属性绑定失败
`NoSuchMethodFailureAnalyzer`	`NoSuchMethodError`	jar 包版本冲突导致方法找不到
`ConnectorStartFailureAnalyzer`	`ConnectorStartFailedException`	Web 服务器端口被占用
`ValidationExceptionFailureAnalyzer`	`ValidationException`	Bean Validation 初始化失败
`JpaFailureAnalyzer`	`JPAException`	JPA/Hibernate 实体映射错误
`AutoConfigurationFailureAnalyzer`	`AutoConfigurationImportException`	自动配置类内部异常

重点实现分析

DataSourceBeanCreationFailureAnalyzer

java

class DataSourceBeanCreationFailureAnalyzer
        extends AbstractFailureAnalyzer<DataSourceCreationException> {

    @Override
    protected FailureAnalysis analyze(Throwable rootFailure, DataSourceCreationException cause) {
        String url = extractUrl(cause);
        return new FailureAnalysis(
            "数据源创建失败，连接 URL：" + url,
            "请检查数据库连接配置：\n  1. 确认数据库服务是否启动\n" +
            "  2. 确认连接 URL 格式正确\n  3. 确认用户名和密码正确",
            cause);
    }
}

ConnectorStartFailureAnalyzer

java

class ConnectorStartFailureAnalyzer
        extends AbstractFailureAnalyzer<ConnectorStartFailedException> {

    @Override
    protected FailureAnalysis analyze(Throwable rootFailure, ConnectorStartFailedException cause) {
        int port = cause.getPort();
        return new FailureAnalysis(
            "嵌入式 Tomcat 启动失败，端口 " + port + " 已被占用",
            "解决方案：\n  1. 停止占用端口 " + port + " 的进程\n" +
            "  2. 修改端口：server.port=新端口号\n  3. 使用随机端口：server.port=0",
            cause);
    }
}

FailureAnalysisReporter 接口

FailureAnalysisReporter 负责输出分析结果：

java

@FunctionalInterface
public interface FailureAnalysisReporter {
    void report(FailureAnalysis analysis);
}

默认实现：LoggingFailureAnalysisReporter

java

public final class LoggingFailureAnalysisReporter implements FailureAnalysisReporter {

    @Override
    public void report(FailureAnalysis analysis) {
        if (logger.isErrorEnabled()) {
            StringBuilder builder = new StringBuilder();
            builder.append("\n***************************\n");
            builder.append("APPLICATION FAILED TO START\n");
            builder.append("***************************\n\n");
            builder.append("Description:\n---\n");
            builder.append(analysis.getDescription()).append("\n\n");
            builder.append("Action:\n---\n");
            builder.append(analysis.getAction()).append("\n");
            logger.error(builder.toString(), analysis.getCause());
        }
    }
}

醒目错误提示的格式化原理

控制台以 *************************** 包围的错误信息设计目的：

视觉突出：在大量启动日志中立即引起注意
结构清晰：Description / Action 两部分区分问题和解决方案
根本原因关联：logger.error() 的第二个参数传入 cause

输出示例：

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

Description:
---
Failed to configure a DataSource: 'url' attribute is not specified.

Action:
---
If you want an embedded database (H2, HSQL, Derby), please put it on the classpath.

自定义 FailureAnalyzer 的开发步骤

步骤一：继承 AbstractFailureAnalyzer

创建类继承 AbstractFailureAnalyzer<T>，泛型参数 T 指定处理的异常类型。

步骤二：实现 analyze 方法

返回 FailureAnalysis 对象，包含 description 和 action。

步骤三：注册到 spring.factories

在 META-INF/spring.factories（Boot 2.x）或 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports（Boot 3.x）中注册。

实战：自定义数据库连接失败诊断

开发一个能够精细化诊断数据库连接失败原因的自定义 FailureAnalyzer。

场景分析

失败场景	异常现象	诊断标志
网络不通	`ConnectException`	无法建立 TCP 连接
密码错误	`SQLException(sqlstate=28000)`	用户认证失败
权限不足	`SQLException(sqlstate=42000)`	无库表访问权限

实现代码

java

package com.example.diagnostics;

import java.net.ConnectException;
import java.sql.SQLException;
import org.springframework.boot.diagnostics.AbstractFailureAnalyzer;
import org.springframework.boot.diagnostics.FailureAnalysis;
import org.springframework.dao.DataAccessResourceFailureException;

public class EnhancedDataSourceFailureAnalyzer
        extends AbstractFailureAnalyzer<DataAccessResourceFailureException> {

    private static final String SQLSTATE_INVALID_PASSWORD = "28000";
    private static final String SQLSTATE_INSUFFICIENT_PRIVILEGE = "42000";

    @Override
    protected FailureAnalysis analyze(Throwable rootFailure,
            DataAccessResourceFailureException cause) {
        Throwable chain = rootFailure;
        while (chain != null) {
            // 网络不通
            if (chain instanceof ConnectException) {
                return new FailureAnalysis(
                    "数据库连接失败：无法建立网络连接。\n" +
                    "  可能原因：数据库未启动 / 防火墙阻止 / URL 主机名端口错误",
                    "排查建议：\n" +
                    "  1. telnet <主机> <端口> 测试连通性\n" +
                    "  2. 确认数据库服务状态\n" +
                    "  3. 检查 spring.datasource.url 配置\n" +
                    "  4. 检查安全组规则是否放通端口",
                    chain);
            }
            // SQL 异常：检查 SQLState
            if (chain instanceof SQLException sqlEx) {
                String state = sqlEx.getSQLState();
                if (SQLSTATE_INVALID_PASSWORD.equals(state)) {
                    return new FailureAnalysis(
                        "数据库连接失败：用户名或密码错误（SQLState: 28000）",
                        "排查建议：\n" +
                        "  1. 检查 spring.datasource.username/password 配置\n" +
                        "  2. 确认特殊字符（#、!、%）在 .properties 中转义\n" +
                        "  3. 用数据库客户端手动登录验证",
                        chain);
                }
                if (SQLSTATE_INSUFFICIENT_PRIVILEGE.equals(state)) {
                    return new FailureAnalysis(
                        "数据库连接失败：用户权限不足（SQLState: 42000）",
                        "排查建议：\n" +
                        "  1. SHOW GRANTS FOR 'username'@'host' 检查权限\n" +
                        "  2. GRANT ALL PRIVILEGES ON db.* TO 'username'@'host'\n" +
                        "  3. 确认数据库名称（DATABASE）是否正确",
                        chain);
                }
            }
            chain = chain.getCause();
        }
        // 通用诊断
        return new FailureAnalysis(
            "数据库连接失败，无法自动诊断具体原因",
            "通用排查：\n  1. 确认数据库已启动\n" +
            "  2. 检查 URL/用户名/密码\n  3. 检查网络和防火墙\n" +
            "  4. 查看完整堆栈跟踪",
            rootFailure);
    }
}

注册 spring.factories

text

org.springframework.boot.diagnostics.FailureAnalyzer=\
com.example.diagnostics.EnhancedDataSourceFailureAnalyzer

自定义 Reporter：输出到文件

java

package com.example.diagnostics;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.diagnostics.FailureAnalysis;
import org.springframework.boot.diagnostics.FailureAnalysisReporter;

public class FileAndConsoleFailureReporter implements FailureAnalysisReporter {
    private static final Logger log = LoggerFactory.getLogger(
        FileAndConsoleFailureReporter.class);

    @Override
    public void report(FailureAnalysis analysis) {
        log.error("=== 应用启动失败诊断报告 ===");
        log.error("描述：{}", analysis.getDescription());
        log.error("建议：{}", analysis.getAction());
        if (analysis.getCause() != null) {
            log.error("根本原因：", analysis.getCause());
        }
    }
}

text

org.springframework.boot.diagnostics.FailureAnalysisReporter=\
com.example.diagnostics.FileAndConsoleFailureReporter

启动效果验证

密码错误场景下的输出：

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

Description:
---
数据库连接失败：用户名或密码错误（SQLState: 28000）

Action:
---
排查建议：
  1. 检查 spring.datasource.username/password 配置
  2. 确认特殊字符（#、!、%）在 .properties 中转义
  3. 用数据库客户端手动登录验证

FailureAnalyzer 执行流程

Application Starting
        │
        ▼
AbstractApplicationContext.refresh()
        │
        ▼  (异常发生)
catch BeansException / RuntimeException
        │
        ▼
SpringApplication.handleRunFailure()
        │
        ├──→ FailureAnalyzers.analyze(exception)
        │       │  for each FailureAnalyzer (SPI loaded, sorted):
        │       │    └─ findCause(exception) → analyze() → FailureAnalysis
        │
        ├──→ FailureAnalysisReporter.report(analysis)
        │       │  LoggingFailureAnalysisReporter 格式化输出
        │
        └──→ 退出 JVM / 返回失败状态

最佳实践

单一职责

每个 FailureAnalyzer 只处理一种异常类型，通过泛型参数精确匹配。

优先使用 AbstractFailureAnalyzer

继承 AbstractFailureAnalyzer<T> 利用其内置的异常链遍历逻辑，避免自行 instanceof 判断。

提供可操作建议

好："使用 telnet <host> <port> 检查网络连通性"
差："请检查网络"

优雅降级

无法精确识别原因时返回通用诊断而非 null，保证开发者至少获得指引。

性能注意

FailureAnalyzer 仅在启动失败时调用，不影响运行时性能。但加载阶段应避免耗时操作。

覆盖范围

自定义分析器可覆盖内置分析器无法处理的场景：

公司内部框架特有的异常
特定中间件的专有异常
包含敏感信息剥离的包装诊断

总结

Spring Boot 的 FailureAnalyzer 机制通过 SPI 加载、异常链匹配和结构化报告三步，将堆栈跟踪转化为开发友好的诊断信息。本文介绍了：

FailureAnalyzer 的 SPI 加载机制和 AbstractFailureAnalyzer 基类设计
15 种内置 FailureAnalyzer 及其诊断场景
FailureAnalysisReporter 默认实现和格式化原理
实战案例：区分数据库连接失败的三种场景（网络不通 / 密码错误 / 权限不足）并给出具体排查建议
开发自定义分析器及 Reporter 的完整步骤

掌握 FailureAnalyzer 机制能帮助开发者快速定位启动问题，并为团队打造定制化的故障诊断能力。

FailureAnalyzer 与错误分析 ​

概述 ​

启动失败与应用上下文的关系 ​

失败阶段 ​

refresh() 的异常处理 ​

失败后资源清理 ​

FailureAnalyzer SPI 机制原理 ​

核心接口 ​

SPI 加载机制 ​

配置位置 ​

AbstractFailureAnalyzer 基类 ​

内置 FailureAnalyzer 一览 ​

重点实现分析 ​

DataSourceBeanCreationFailureAnalyzer ​

ConnectorStartFailureAnalyzer ​

FailureAnalysisReporter 接口 ​

默认实现：LoggingFailureAnalysisReporter ​

醒目错误提示的格式化原理 ​

自定义 FailureAnalyzer 的开发步骤 ​

步骤一：继承 AbstractFailureAnalyzer ​

步骤二：实现 analyze 方法 ​

步骤三：注册到 spring.factories ​

实战：自定义数据库连接失败诊断 ​

场景分析 ​

实现代码 ​

注册 spring.factories ​

自定义 Reporter：输出到文件 ​

启动效果验证 ​

FailureAnalyzer 执行流程 ​

最佳实践 ​

单一职责 ​

优先使用 AbstractFailureAnalyzer ​

提供可操作建议 ​

优雅降级 ​

性能注意 ​

覆盖范围 ​

总结 ​

FailureAnalyzer 与错误分析

概述

启动失败与应用上下文的关系

失败阶段

refresh() 的异常处理

失败后资源清理

FailureAnalyzer SPI 机制原理

核心接口

SPI 加载机制

配置位置

AbstractFailureAnalyzer 基类

内置 FailureAnalyzer 一览

重点实现分析

DataSourceBeanCreationFailureAnalyzer

ConnectorStartFailureAnalyzer

FailureAnalysisReporter 接口

默认实现：LoggingFailureAnalysisReporter

醒目错误提示的格式化原理

自定义 FailureAnalyzer 的开发步骤

步骤一：继承 AbstractFailureAnalyzer

步骤二：实现 analyze 方法

步骤三：注册到 spring.factories

实战：自定义数据库连接失败诊断

场景分析

实现代码

注册 spring.factories

自定义 Reporter：输出到文件

启动效果验证

FailureAnalyzer 执行流程

最佳实践

单一职责

优先使用 AbstractFailureAnalyzer

提供可操作建议

优雅降级

性能注意

覆盖范围

总结