在Spring Boot中创建自定义故障分析器

1. 概述

Spring Boot中的故障分析器（FailureAnalyzer）提供了一种拦截应用启动过程中发生的异常的机制，这些异常会导致应用启动失败。

故障分析器会将异常的堆栈信息替换为更易读的故障分析（FailureAnalysis）对象，其中包含错误描述和修复建议。

Spring Boot内置了一系列常见启动异常的分析器，例如：

PortInUseException（端口占用异常）
NoUniqueBeanDefinitionException（非唯一Bean定义异常）
UnsatisfiedDependencyException（依赖注入失败异常）

这些内置分析器位于org.springframework.boot.diagnostics包中。

本教程将快速介绍如何添加自定义故障分析器到现有系统中。

2. 创建自定义故障分析器

创建自定义故障分析器只需继承抽象类AbstractFailureAnalyzer，该类会拦截指定类型的异常，并实现analyze()方法。

⚠️ 框架已提供BeanNotOfRequiredTypeFailureAnalyzer实现，但仅处理动态代理类注入时的BeanNotOfRequiredTypeException异常。

下面我们创建一个处理所有BeanNotOfRequiredTypeException类型的自定义分析器：

public class MyBeanNotOfRequiredTypeFailureAnalyzer 
  extends AbstractFailureAnalyzer<BeanNotOfRequiredTypeException> {

    @Override
    protected FailureAnalysis analyze(Throwable rootFailure, 
      BeanNotOfRequiredTypeException cause) {
        return new FailureAnalysis(getDescription(cause), getAction(cause), cause);
    }

    private String getDescription(BeanNotOfRequiredTypeException ex) {
        return String.format("Bean %s 无法注入为 %s 类型，"
          + "其实际类型为 %s",
          ex.getBeanName(),
          ex.getRequiredType().getName(),
          ex.getActualType().getName());
    }

    private String getAction(BeanNotOfRequiredTypeException ex) {
        return String.format("建议创建名称为 %s 且类型为 %s 的Bean",
          ex.getBeanName(),
          ex.getRequiredType().getName());
    }
}

✅ 关键点：

继承AbstractFailureAnalyzer<异常类型>
实现analyze()方法返回FailureAnalysis
提供清晰的错误描述和修复建议

3. 注册自定义故障分析器

要让Spring Boot识别自定义分析器，必须在resources/META-INF/spring.factories文件中注册：

org.springframework.boot.diagnostics.FailureAnalyzer=\
  com.baeldung.failureanalyzer.MyBeanNotOfRequiredTypeFailureAnalyzer

❌ 常见错误：

忘记在spring.factories中注册
类路径错误或包名不匹配

4. 自定义故障分析器实战

我们创建一个简单案例：注入错误类型的Bean，观察自定义分析器的行为。

4.1 创建Bean类

public class MyDAO { }

@Repository("myDAO")
public class MySecondDAO { }

4.2 创建服务类（故意注入错误类型）

@Service
public class MyService {

    @Resource(name = "myDAO")
    private MyDAO myDAO; // 实际注入的是MySecondDAO类型
}

4.3 启动应用时的控制台输出

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

Description:

Bean myDAO 无法注入为 com.baeldung.failureanalyzer.MyDAO 类型，
其实际类型为 com.baeldung.failureanalyzer.MySecondDAO$$EnhancerBySpringCGLIB$$d902559e

Action:

建议创建名称为 myDAO 且类型为 com.baeldung.failureanalyzer.MyDAO 的Bean

💡 输出显示：

清晰的错误描述（Bean类型不匹配）

具体的修复建议（创建正确类型的Bean）

隐藏了冗长的堆栈信息

5. 总结

本教程快速演示了在Spring Boot中实现自定义故障分析器的完整流程：

继承AbstractFailureAnalyzer 指定目标异常类型
实现analyze()方法 生成诊断信息
在spring.factories注册 使其生效
验证效果 获得更友好的错误提示

这种机制特别适合：

封装项目特定的启动错误
提供团队统一的错误处理规范
简化复杂异常的排查过程

完整示例代码可在GitHub仓库获取。

Persistence

REST

Security