JAVA Spring Boot 自定义 Starter 不生效？META-INF/spring.factories 注册错误 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

好的，我们开始。

Spring Boot 自定义 Starter 不生效？META-INF/spring.factories 注册错误深入剖析

今天我们来深入探讨一个在 Spring Boot 开发中经常遇到的问题：自定义 Starter 不生效，尤其是在 META-INF/spring.factories 注册方面出现错误的情况。这个问题看似简单，但往往涉及多个层面的理解，包括 Spring Boot 的自动配置机制、spring.factories 文件的作用、类加载机制以及依赖管理等。

一、Spring Boot 自动配置机制概述

Spring Boot 的核心特性之一就是自动配置（Auto-Configuration）。它通过预先配置好的 Bean 和配置类，简化了应用程序的启动和配置过程。自动配置避免了大量的 XML 配置，极大地提高了开发效率。

自动配置的流程大致如下：

依赖分析： Spring Boot 会扫描 classpath 下的 JAR 包，分析是否存在包含自动配置类的 JAR 包。
spring.factories 加载： 如果找到包含自动配置类的 JAR 包，Spring Boot 会读取该 JAR 包 META-INF/spring.factories 文件。
自动配置类加载： spring.factories 文件中定义了需要自动配置的类，Spring Boot 会根据配置条件（例如是否存在特定的类、属性等）决定是否加载这些自动配置类。
Bean 注册： 加载的自动配置类会创建并注册相应的 Bean 到 Spring 容器中。
条件判断： 自动配置类通常会使用 @Conditional 注解进行条件判断，只有满足特定条件时，才会进行自动配置。

关键注解：

@Configuration: 标识一个类作为配置类，用于定义 Bean。
@EnableAutoConfiguration: 启用 Spring Boot 的自动配置机制。通常不需要显式使用，因为 @SpringBootApplication 注解包含了它。
@Conditional: 条件注解，用于控制 Bean 的创建和注册。
- @ConditionalOnClass: 当 classpath 下存在指定的类时，才进行配置。
- @ConditionalOnMissingClass: 当 classpath 下不存在指定的类时，才进行配置。
- @ConditionalOnProperty: 当配置文件中存在指定的属性时，才进行配置。
- @ConditionalOnBean: 当容器中存在指定的 Bean 时，才进行配置。
- @ConditionalOnMissingBean: 当容器中不存在指定的 Bean 时，才进行配置。

二、`META-INF/spring.factories` 文件详解

META-INF/spring.factories 文件是 Spring Boot 自动配置机制的核心组成部分。它是一个简单的属性文件，用于声明需要自动配置的类。

作用：

声明自动配置类：指示 Spring Boot 哪些类是自动配置类。
声明 ApplicationContextInitializer：用于在 Spring 容器启动之前执行一些初始化操作。
声明 ApplicationListener：用于监听 Spring 容器的事件。

格式：

spring.factories 文件采用 key-value 的格式，key 是接口或抽象类的全限定名，value 是实现了该接口或继承了该抽象类的类的全限定名，多个类之间用逗号分隔。

常见的 Key 值：

Key	作用
`org.springframework.boot.autoconfigure.EnableAutoConfiguration`	指定自动配置类，这些类会在应用程序启动时被自动配置。
`org.springframework.context.ApplicationContextInitializer`	指定 `ApplicationContextInitializer` 接口的实现类，用于在 Spring 容器启动之前执行一些初始化操作，例如设置环境变量、修改配置属性等。
`org.springframework.context.ApplicationListener`	指定 `ApplicationListener` 接口的实现类，用于监听 Spring 容器的事件，例如 `ContextRefreshedEvent`、`ContextClosedEvent` 等。
`org.springframework.boot.autoconfigure.AutoConfigurationImportSelector`	允许更细粒度地控制自动配置类的导入。可以通过实现 `AutoConfigurationImportSelector` 接口，自定义选择哪些自动配置类应该被导入。这在需要动态地根据环境或条件选择自动配置类时非常有用。

示例：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=
com.example.demo.autoconfigure.DemoAutoConfiguration,
com.example.demo.autoconfigure.AnotherAutoConfiguration

org.springframework.context.ApplicationContextInitializer=
com.example.demo.initializer.DemoApplicationContextInitializer

org.springframework.context.ApplicationListener=
com.example.demo.listener.DemoApplicationListener

三、自定义 Starter 的基本步骤

创建 Maven 项目： 创建一个新的 Maven 项目，作为 Starter 项目。
定义 Auto-Configuration 类： 创建一个或多个配置类，使用 @Configuration 注解标识，并使用 @Conditional 注解进行条件判断。
创建 spring.factories 文件： 在 src/main/resources/META-INF 目录下创建 spring.factories 文件，并将 Auto-Configuration 类的全限定名添加到 org.springframework.boot.autoconfigure.EnableAutoConfiguration 属性中。
定义 Configuration Properties (可选)： 如果需要自定义配置属性，可以创建一个类，使用 @ConfigurationProperties 注解标识，并定义相关的属性。
发布到 Maven 仓库： 将 Starter 项目发布到 Maven 仓库，以便其他项目可以使用。

示例代码：

1. 定义 Configuration Properties (可选):

package com.example.demo.properties;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("demo")
public class DemoProperties {

    private String message = "Hello, World!";
    private boolean enabled = true;

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public boolean isEnabled() {
        return enabled;
    }

    public void setEnabled(boolean enabled) {
        this.enabled = enabled;
    }
}

2. 定义 Auto-Configuration 类:

package com.example.demo.autoconfigure;

import com.example.demo.properties.DemoProperties;
import com.example.demo.service.DemoService;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@ConditionalOnClass(DemoService.class)
@EnableConfigurationProperties(DemoProperties.class)
@ConditionalOnProperty(prefix = "demo", value = "enabled", havingValue = "true", matchIfMissing = true)
public class DemoAutoConfiguration {

    private final DemoProperties properties;

    public DemoAutoConfiguration(DemoProperties properties) {
        this.properties = properties;
    }

    @Bean
    @ConditionalOnMissingBean
    public DemoService demoService() {
        return new DemoService(properties.getMessage());
    }
}

3. 定义 Service 类:

package com.example.demo.service;

public class DemoService {

    private final String message;

    public DemoService(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }

    public void printMessage() {
        System.out.println(message);
    }
}

4. 创建 spring.factories 文件:

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.example.demo.autoconfigure.DemoAutoConfiguration

四、常见问题及解决方案

spring.factories 文件路径错误：
- 问题： spring.factories 文件必须位于 src/main/resources/META-INF 目录下。如果路径错误，Spring Boot 将无法找到该文件。
- 解决方案： 确保 spring.factories 文件位于正确的目录下。检查 Maven 项目的结构是否正确。
spring.factories 文件内容错误：
- 问题： spring.factories 文件中的 key 或 value 错误，例如类名拼写错误、缺少逗号分隔符等。
- 解决方案： 仔细检查 spring.factories 文件的内容，确保 key 和 value 的拼写正确，并且使用逗号正确分隔多个类名。可以使用反斜杠进行换行，提高可读性。
Auto-Configuration 类未被扫描：
- 问题： Auto-Configuration 类所在的包未被 Spring Boot 扫描到。
- 解决方案： 确保 Auto-Configuration 类所在的包位于 Spring Boot 的扫描范围内。可以在主应用程序类上使用 @SpringBootApplication(scanBasePackages = {"com.example.demo"}) 注解指定要扫描的包。如果没有指定 scanBasePackages, 默认扫描启动类所在的包及其子包。
依赖冲突：
- 问题： Starter 项目依赖的 JAR 包与应用程序本身依赖的 JAR 包版本冲突。
- 解决方案： 使用 Maven 的 dependencyManagement 机制管理依赖版本，确保所有依赖的版本一致。在 Starter 项目的 POM 文件中，使用 <dependencyManagement> 标签定义依赖版本，并在应用程序的 POM 文件中引用相同的版本。
条件注解未满足：
- 问题： Auto-Configuration 类使用了 @Conditional 注解进行条件判断，但条件未满足，导致 Auto-Configuration 类未被加载。
- 解决方案： 检查 @Conditional 注解的条件是否满足。例如，如果使用了 @ConditionalOnClass 注解，确保 classpath 下存在指定的类；如果使用了 @ConditionalOnProperty 注解，确保配置文件中存在指定的属性，并且属性值符合要求。
类加载问题：
- 问题： 在某些情况下，类加载器可能无法正确加载 Auto-Configuration 类。
- 解决方案： 确保 Starter 项目的 JAR 包已正确添加到 classpath 中。检查 Maven 依赖是否正确配置。可以使用Maven Helper插件或者IDE自带的依赖分析工具来查看依赖关系以及是否存在冲突。
循环依赖：
- 问题： 自动配置类之间存在循环依赖，导致 Spring 容器无法启动。
- 解决方案： 尽量避免自动配置类之间的循环依赖。可以通过调整 Bean 的创建顺序、使用 @Lazy 注解或重构代码来解决循环依赖问题。
缓存问题:
- 问题: IDE或者构建工具（如Maven）可能会缓存旧的spring.factories文件或者编译结果。即使你已经修改了代码，旧的版本仍然被使用。
- 解决方案:
  - 清理并重新构建项目：在IDE中执行 "Clean Project" 或使用 Maven 命令 mvn clean install。
  - 刷新IDE缓存：在IDE中查找 "Invalidate Caches / Restart" 选项 (不同IDE的名称可能不同)。
  - 检查Maven仓库：确保你本地Maven仓库中的starter库是最新的。如果你不确定，可以删除本地仓库中对应的starter库，Maven会自动重新下载。

表格总结常见问题及解决方案：

问题	解决方案
`spring.factories` 文件路径错误	确保 `spring.factories` 文件位于 `src/main/resources/META-INF` 目录下。
`spring.factories` 文件内容错误	仔细检查 `spring.factories` 文件的内容，确保 key 和 value 的拼写正确，并且使用逗号正确分隔多个类名。
Auto-Configuration 类未被扫描	确保 Auto-Configuration 类所在的包位于 Spring Boot 的扫描范围内。使用 `@SpringBootApplication(scanBasePackages = {"com.example.demo"})` 指定要扫描的包。
依赖冲突	使用 Maven 的 dependencyManagement 机制管理依赖版本，确保所有依赖的版本一致。
条件注解未满足	检查 `@Conditional` 注解的条件是否满足。确保 classpath 下存在指定的类，配置文件中存在指定的属性，并且属性值符合要求。
类加载问题	确保 Starter 项目的 JAR 包已正确添加到 classpath 中。检查 Maven 依赖是否正确配置。
循环依赖	尽量避免自动配置类之间的循环依赖。可以通过调整 Bean 的创建顺序、使用 `@Lazy` 注解或重构代码来解决循环依赖问题。
缓存问题	清理并重新构建项目。刷新IDE缓存。检查Maven仓库，确保你本地Maven仓库中的starter库是最新的。

五、调试技巧

启用 debug 日志： 在 application.properties 或 application.yml 文件中设置 logging.level.org.springframework.boot.autoconfigure=DEBUG，可以查看 Spring Boot 自动配置的详细日志信息。
断点调试： 在 Auto-Configuration 类的构造函数或 Bean 的创建方法中设置断点，可以跟踪代码的执行过程，了解 Bean 的创建和属性注入情况。
查看自动配置报告： 启动应用程序后，可以在控制台中查看自动配置报告，了解哪些 Auto-Configuration 类被加载，哪些 Auto-Configuration 类未被加载，以及未被加载的原因。自动配置报告在debug级别日志中可以看到。

六、案例分析：一个不生效的 Starter

假设我们创建了一个名为 my-starter 的 Starter 项目，其中包含一个 Auto-Configuration 类 MyAutoConfiguration。我们按照上述步骤创建了项目，并发布到了 Maven 仓库。

但是，当我们在另一个应用程序中使用 my-starter 时，发现 MyAutoConfiguration 类并没有生效。通过查看 debug 日志，我们发现以下信息：

2023-10-27 10:00:00.000 DEBUG [main] o.s.b.a.AutoConfigurationImportSelector : Auto-configuration import filter results:
    - MyAutoConfiguration: Did not match due to:
      - AutoConfiguration classes are nested;

从日志中可以看出，MyAutoConfiguration 类未被加载的原因是 "AutoConfiguration classes are nested"。这意味着 MyAutoConfiguration 类位于一个内部类中，Spring Boot 无法正确加载。

解决方案： 将 MyAutoConfiguration 类移动到一个独立的类文件中，重新编译并发布 Starter 项目，问题即可解决。

七、总结与最佳实践

Spring Boot 自定义 Starter 的核心在于理解自动配置机制和 spring.factories 文件的作用。确保 spring.factories 文件路径和内容正确，Auto-Configuration 类位于正确的包中，依赖版本一致，并且条件注解满足要求，是确保 Starter 生效的关键。同时，熟悉调试技巧可以帮助快速定位问题，提高开发效率。

最佳实践：

保持 Starter 项目的简洁性，只包含必要的依赖和配置。
使用 Maven 的 dependencyManagement 机制管理依赖版本。
编写清晰的文档，说明 Starter 的使用方法和配置选项。
提供示例应用程序，演示 Starter 的功能。
定期更新 Starter 项目，修复 bug 并添加新功能。

掌握这些知识点，你就可以更好地创建和使用 Spring Boot 自定义 Starter，提高应用程序的开发效率和可维护性。

希望以上讲解能够帮助你解决 Spring Boot 自定义 Starter 不生效的问题。

Spring Boot 自定义 Starter 不生效？META-INF/spring.factories 注册错误 深入剖析