29. 创建自己的自动配置（-）

如果您在开发共享库的公司中工作，或者在开源或商业库中工作，则可能需要开发自己的自动配置。自动配置类可以捆绑在外部jar中，并且仍由Spring Boot拾取。
自动配置可以与“启动器”相关联，该“启动器”提供自动配置代码以及您将使用的典型库。我们首先介绍您构建自己的自动配置所需的知识，然后继续进行创建自定义启动器所需的典型步骤。

29.1 了解自动配置的Bean

在后台，自动配置是通过标准@Configuration类实现的。其他@Conditional注释用于约束何时应应用自动配置。通常，自动配置类使用@ConditionalOnClass和@ConditionalOnMissingBean注释。这样可以确保仅当找到相关的类并且尚未声明自己的类时，自动配置才适用@Configuration。
您可以浏览的源代码spring-boot-autoconfigure以查看@ConfigurationSpring提供的类（请参见META-INF/spring.factories文件）。

29.2 查找自动配置候选人

Spring Boot检查META-INF/spring.factories发布的jar中是否存在文件。该文件应在EnableAutoConfiguration键下列出您的配置类，如以下示例所示：
org.springframework.boot.autoconfigure.EnableAutoConfiguration = \
com.mycorp.libx.autoconfigure.LibXAutoConfiguration，\
com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration

如果需要按特定顺序应用配置，则可以使用@AutoConfigureAfter或@AutoConfigureBefore注释。例如，如果您提供特定于Web的配置，则可能需要在之后应用类WebMvcAutoConfiguration。
如果您要订购某些彼此之间不具有直接了解的自动配置，则也可以使用@AutoConfigureOrder。该注释与常规注释具有相同的语义，@Order但为自动配置类提供了专用顺序。
与标准@Configuration类一样，自动配置类的应用顺序仅会影响其bean的定义顺序。随后创建这些bean的顺序不受影响，并由每个bean的依赖关系和任何@DependsOn关系确定。

29.3 条件注释

您几乎总是希望@Conditional在自动配置类中包含一个或多个注释。该@ConditionalOnMissingBean注释是用来让开发者重写自动配置，如果他们不满意自己的缺省值一个常见的例子。
Spring Boot包含许多@Conditional注释，您可以通过注释@Configuration类或单个@Bean方法在自己的代码中重用它们。这些注释包括：

• 上课条件
• 豆条件
• 物业条件
• 资源条件
• Web应用条件
• SpEL表达条件

  29.3.1 上课条件

  的@ConditionalOnClass和@ConditionalOnMissingClass注解让@Configuration类基于特定类的存在或不存在被包括在内。由于注释元数据是使用ASM进行解析的value，因此即使该类实际上未真正出现在正在运行的应用程序类路径上，您也可以使用该属性来引用真实的类。name如果您更喜欢通过使用String值来指定类名称，则也可以使用该属性。
  这种机制不适用于@Bean通常以返回类型为条件的目标的方法：在方法的条件适用之前，JVM将加载该类和可能处理的方法引用，如果该类不是当下。
  要处理这种情况，@Configuration可以使用一个单独的类来隔离条件，如以下示例所示：

  @Configuration(proxyBeanMethods = false)
  // Some conditions
  public class MyAutoConfiguration {
    // Auto-configured beans
    @Configuration(proxyBeanMethods = false)
    @ConditionalOnClass(EmbeddedAcmeService.class)
    static class EmbeddedConfiguration {
        @Bean
        @ConditionalOnMissingBean
        public EmbeddedAcmeService embeddedAcmeService() { ... }
    }
  }

  | | 如果您使用元批注@ConditionalOnClass或@ConditionalOnMissingClass作为元批注的一部分来组成自己的组合批注，name则在不处理这种情况下，必须使用引用类。 | | :—-: | —- |

29.3.2 豆条件

的@ConditionalOnBean和@ConditionalOnMissingBean注解让豆基于特定豆的存在或不存在被包括在内。您可以使用该value属性按类型name指定bean或按名称指定bean。该search属性使您可以限制ApplicationContext搜索bean时应考虑的层次结构。
当放置在@Bean方法上时，目标类型默认为方法的返回类型，如以下示例所示：

@Configuration(proxyBeanMethods = false)
public class MyAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean
    public MyService myService() { ... }
}

在前面的例子中，myService豆将被创建如果没有类型的豆MyService已经包含在所述ApplicationContext。

29.3.3 物业条件

该@ConditionalOnProperty注解让基于Spring的环境属性配置包括在内。使用prefix和name属性来指定应检查的属性。默认情况下，false匹配存在且不等于的任何属性。您还可以使用havingValue和matchIfMissing属性创建更高级的检查。

29.3.4 资源条件

该@ConditionalOnResource注解让配置被包括仅当特定资源是否存在。资源可通过使用通常的弹簧约定来指定，如显示在下面的例子：file:/home/user/test.dat。

29.3.5 Web应用条件

在@ConditionalOnWebApplication和@ConditionalOnNotWebApplication注释，让配置包含依赖于应用程序是否是一个“Web应用程序”。基于Servlet的Web应用程序是使用Spring WebApplicationContext，定义session范围或具有的任何应用程序ConfigurableWebEnvironment。响应式Web应用程序是使用ReactiveWebApplicationContext或具有的任何应用程序ConfigurableReactiveWebEnvironment。
该@ConditionalOnWarDeployment注解让配置取决于应用是否是被部署到一个容器中的传统WAR应用程序被包括在内。对于嵌入式服务器运行的应用程序，此条件将不匹配。

29.3.6 SpEL表达条件

该@ConditionalOnExpression注解让基于一个的结果配置被包括使用SpEL表达。

29.4 测试您的自动配置

自动配置可能受到许多因素的影响：用户配置（@Bean定义和Environment自定义），条件评估（特定库的存在）以及其他因素。具体而言，每个测试都应创建定义良好的定义ApplicationContext，以代表这些定制的组合。 ApplicationContextRunner提供了实现此目标的好方法。
ApplicationContextRunner通常定义为测试类的一个字段，以收集基本的通用配置。以下示例确保UserServiceAutoConfiguration始终调用该示例：

private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
        .withConfiguration(AutoConfigurations.of(UserServiceAutoConfiguration.class));

每个测试都可以使用运行器来表示特定的用例。例如，下面的示例调用一个用户配置（UserConfiguration），并检查自动配置是否正确退出。调用run提供了可与一起使用的回调上下文AssertJ。

@Test
void defaultServiceBacksOff() {
    this.contextRunner.withUserConfiguration(UserConfiguration.class).run((context) -> {
        assertThat(context).hasSingleBean(UserService.class);
        assertThat(context).getBean("myUserService").isSameAs(context.getBean(UserService.class));
    });
}
@Configuration(proxyBeanMethods = false)
static class UserConfiguration {
    @Bean
    UserService myUserService() {
        return new UserService("mine");
    }
}

也可以轻松自定义Environment，如以下示例所示：

@Test
void serviceNameCanBeConfigured() {
    this.contextRunner.withPropertyValues("user.name=test123").run((context) -> {
        assertThat(context).hasSingleBean(UserService.class);
        assertThat(context.getBean(UserService.class).getName()).isEqualTo("test123");
    });
}

跑步者也可以用来显示ConditionEvaluationReport。可以按级别INFO或DEBUG水平打印报告。以下示例显示了如何ConditionEvaluationReportLoggingListener在自动配置测试中使用来打印报告。

@Test
public void autoConfigTest {
    ConditionEvaluationReportLoggingListener initializer = new ConditionEvaluationReportLoggingListener(
            LogLevel.INFO);
    ApplicationContextRunner contextRunner = new ApplicationContextRunner()
            .withInitializer(initializer).run((context) -> {
                    // Do something...
            });
}

29.4.1 模拟Web上下文

如果您需要测试仅在Servlet或Reactive Web应用程序上下文中运行的自动配置，请分别使用WebApplicationContextRunner或ReactiveWebApplicationContextRunner。

29.4.2 覆盖类路径

还可以测试在运行时不存在特定的类和/或程序包时发生的情况。Spring Boot附带了一个FilteredClassLoader跑步者可以轻松使用的。在以下示例中，我们断言如果UserService不存在，则将自动禁用自动配置：

@Test
void serviceIsIgnoredIfLibraryIsNotPresent() {
    this.contextRunner.withClassLoader(new FilteredClassLoader(UserService.class))
            .run((context) -> assertThat(context).doesNotHaveBean("userService"));
}

29.5 创建自己的入门

一个典型的Spring Boot启动器包含用于自动配置和自定义给定技术的基础结构的代码，我们称其为“ acme”。为了使其易于扩展，可以将专用命名空间中的许多配置密钥公开给环境。最后，提供了一个“启动程序”依赖项，以帮助用户尽可能轻松地入门。
具体而言，自定义启动器可以包含以下内容：

• autoconfigure包含“ acme”的自动配置代码的模块。
• 将starter其提供给一个依赖模块autoconfigure模块以及“ACME”，并且通常是有用的任何附加的依赖性。简而言之，添加启动程序应提供开始使用该库所需的一切。

完全没有必要将这两个模块分开。如果“ acme”具有多种功能，选项或可选功能，则最好将自动配置分开，因为您可以清楚地表示某些功能是可选的。此外，您还可以制作一个入门程序，以提供有关那些可选依赖项的意见。同时，其他人只能依靠该autoconfigure模块，并以不同的观点来设计自己的启动器。
如果自动配置相对简单并且不具有可选功能，则将两个模块合并在启动器中绝对是一种选择。

29.5.1 命名

您应该确保为启动器提供适当的名称空间。spring-boot即使使用其他Maven，也不要以模块名称开头groupId。将来，我们可能会为您自动配置的内容提供官方支持。
根据经验，您应该在启动器后命名一个组合模块。例如，假设您要为“ acme”创建启动器，并命名自动配置模块acme-spring-boot和启动器acme-spring-boot-starter。如果您只有一个将两者结合的模块，请命名为acme-spring-boot-starter。

29.5.2 配置键

如果您的入门者提供了配置密钥，请为其使用唯一的名称空间。特别是，不包括你的名字空间去春Boot使用键（如server，management，spring，等）。如果使用相同的名称空间，将来我们可能会以破坏模块的方式修改这些名称空间。根据经验，所有键都以您拥有的名称空间（例如acme）为前缀。
通过为每个属性添加字段javadoc来确保记录了配置键，如以下示例所示：

@ConfigurationProperties("acme")
public class AcmeProperties {
    /**
     * Whether to check the location of acme resources.
     */
    private boolean checkLocation = true;
    /**
     * Timeout for establishing a connection to the acme server.
     */
    private Duration loginTimeout = Duration.ofSeconds(3);
    // getters & setters
}

以下是我们内部遵循的一些规则，以确保描述一致：

• 请勿以“ The”或“ A”开头描述。
• 对于boolean类型，请从“是否”或“启用”开始描述。
• 对于基于集合的类型，请以“以逗号分隔的列表”开始描述
• 如果默认单位与毫秒不同，请使用java.time.Duration而不是long并描述默认单位，例如“如果未指定持续时间后缀，将使用秒”。
• 除非必须在运行时确定默认值，否则请不要在描述中提供默认值。

确保触发元数据生成，以便IDE协助也可用于您的密钥。您可能需要查看生成的元数据（META-INF/spring-configuration-metadata.json），以确保正确记录了您的密钥。在兼容的IDE中使用自己的启动程序也是验证元数据质量的好主意。

29.5.3 “自动配置”模块

该autoconfigure模块包含开始使用该库所需的所有内容。它还可能包含配置键定义（例如@ConfigurationProperties）和可用于进一步自定义组件初始化方式的任何回调接口。

Spring Boot使用注释处理器来收集元数据文件（META-INF/spring-autoconfigure-metadata.properties）中自动配置的条件。如果存在该文件，它将用于急切过滤不匹配的自动配置，这将缩短启动时间。建议在包含自动配置的模块中添加以下依赖项：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-autoconfigure-processor</artifactId>
    <optional>true</optional>
</dependency>

如果您直接在应用程序中定义了自动配置，请确保配置，spring-boot-maven-plugin以防止repackage目标将依赖项添加到胖罐中：

<project>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.springframework.boot</groupId>
                            <artifactId>spring-boot-autoconfigure-processor</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

对于Gradle 4.5及更早版本，应在compileOnly配置中声明依赖项，如以下示例所示：

dependencies {
    compileOnly "org.springframework.boot:spring-boot-autoconfigure-processor"
}

对于Gradle 4.6和更高版本，应在annotationProcessor配置中声明依赖项，如以下示例所示：

dependencies {
    annotationProcessor "org.springframework.boot:spring-boot-autoconfigure-processor"
}

29.5.4 启动模块

起动器确实是一个空罐子。其唯一目的是提供必要的依赖关系以使用库。您可以将其视为对入门所需的看法。
不要对添加了启动器的项目做任何假设。如果您要自动配置的库通常需要其他启动器，请同时提及它们。如果可选依赖项的数量很高，则很难提供一组适当的默认依赖项，因为您应避免包括对于库的典型用法而言不必要的依赖项。换句话说，您不应包括可选的依赖项。