SpringBoot实战 - 创建自己的auto-configuration

本文已收录在Github，关注我，紧跟本系列专栏文章，咱们下篇再续！

• 🚀 魔都架构师 | 全网30W技术追随者
• 🔧 大厂分布式系统/数据中台实战专家
• 🏆 主导交易系统百万级流量调优 & 车联网平台架构
• 🧠 AIGC应用开发先行者 | 区块链落地实践者
• 🌍 以技术驱动创新，我们的征途是改变世界！
• 👉 实战干货：编程严选网

0 前言

如果你在公司里开发共享libraries，或者正在开发一个开源或商业library，想开发自己的自动配置（auto-configuration）。自动配置类可打包到外部jars，且依旧被Spring Boot识别。

自动配置可关联一个"starter"，用于提供auto-configuration的代码及需要引用的libraries。

本文先讲解构建自己的auto-configuration需知内容，然后讲解创建自定义starter常见步骤。

1 理解自动配置的beans

从底层看，自动配置（auto-configuration）是通过标准的@Configuration类实现的。@Conditional注解约束自动配置生效的条件，通常自动配置类需用:

• @ConditionalOnClass
• @ConditionalOnMissingBean

这是为确保，只有在相关类被发现及没有声明自定义@Configuration时，才应用自动配置，具体查看spring-boot-autoconfigure源码中的@Configuration类（META-INF/spring.factories文件）。

2 定位自动配置候选者

Spring Boot检查你发布的jar中是否存在META-INF/spring.factories文件，该文件中以EnableAutoConfiguration为K的属性，应该列出你的配置类：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.mycorp.libx.autoconfigure.LibXAutoConfiguration,\
com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration

可用@AutoConfigureAfter或@AutoConfigureBefore为配置类指定顺序。

也可用@AutoconfigureOrder注解为那些相互不知道存在的自动配置类提供排序，语义和@Order注解相同，但专为自动配置类提供顺序。

自动配置类只能通过这种方式加载，确保它们定义在一个特殊的package中，特别是不能成为组件扫描的目标。

3 条件注解

你几乎总要在自己的自动配置类里加很多@Conditional，如@ConditionalOnMissingBean，用它覆盖自动配置类的默认行为。

Spring Boot包含很多@Conditional注解，可通过@Configuration类或单独@Bean方法重用它们。

3.1 Class条件

@ConditionalOnClass和@ConditionalOnMissingClass注解可根据特定类是否出现来决定配置的包含，由于注解元数据是使用ASM来解析的，可用value属性引用真正的类，即使该类没有出现在运行应用的classpath下，也可以使用name属性如果你倾向于使用字符串作为类名。

3.2 Bean条件

@ConditionalOnBean和@ConditionalOnMissingBean注解可以根据特定类是否存在决定bean的包含，你可以使用value属性指定beans（by type），也可以使用name定义beans（by name），search属性用于限制搜索beans时需要考虑的ApplicationContext层次。

注 你需要注意bean定义添加的顺序，因为这些条件的计算是基于目前处理内容的。出于这个原因，我们推荐在自动配置类上只使用@ConditionalOnBean和@ConditionalOnMissingBean注解（即使保证它们在其他用户定义的beans后加载）。

注 @ConditionalOnBean和@ConditionalOnMissingBean不会阻止@Configuration类的创建，在类级别使用那些conditions跟使用注解标记每个@Bean方法是等价的。

3.3 Property条件

@ConditionalOnProperty注解可以根据一个Spring Environment属性来决定是否包含配置，使用prefix和name属性指定要检查的配置。默认情况下，任何存在的只要不是false的属性都会匹配，你也可以使用havingValue和matchIfMissing属性创建更高级的检测。

3.4 Resource条件

@ConditionalOnResource注解只在特定资源出现时才会包含配置，可以使用常见的Spring约定命名资源，例如file:/home/user/test.dat。

3.5 Web Application条件

@ConditionalOnWebApplication和@ConditionalOnNotWebApplication注解可以根据应用是否为'web应用'来决定是否包含配置，web应用是任何使用Spring WebApplicationContext，定义一个session作用域，或有一个StandardServletEnvironment的应用。

3.6 SpEL表达式条件

@ConditionalOnExpression注解可以根据SpEL表达式结果来决定是否包含配置。

4 创建自己的starter

一个完整的Spring Boot starter包含以下组件：

• autoconfigure模块，包含自动配置类的代码
• starter模块，提供自动配置模块及其他有用的依赖，简而言之，添加本starter就能开始使用该library

如不需要将它们分离开来，你可以将自动配置代码和依赖管理放到一个单一模块中。

4.1 命名

为你的starter提供合适的命名空间（namespace），模块名不要以spring-boot作为开头，使用一个不同的Maven groupId，未来可能会为你正在做的自动配置提供官方支持。

假设你正在为“acme”创建一个starter，命名自动配置模块为acme-spring-boot-autoconfigure，命名starter为acme-spring-boot-starter，如果只有一个模块结合它们，通常会使用acme-spring-boot-starter。

如果你的starter提供配置keys，要为它们提供一个合适的命名空间，特别是不要使用Spring Boot命名空间（如server，management，spring等），这些属于Spring Boot。

确保触发meta-data生成，这样IDE辅助也就可以用于你的keys了，你可能想检查生成的元数据（META-INF/spring-configuration-metadata.json）以确保keys被正确的文档化。

4.2 自动配置模块

自动配置模块包含了使用该library需要的任何东西，它可能还包含配置的keys定义（@ConfigurationProperties）和用于定义组件如何初始化的回调接口。

注 你需要将对该library的依赖标记为可选的，这样在项目中添加该自动配置模块就更容易了。如果你这样做，该library将不会提供，Spring Boot会回退到默认设置。

4.3 Starter模块

starter模块实际是一个空jar，提供使用该library所需的必要依赖。不要对添加你的starter的项目做任何假设，如你正在自动配置的library需要其他starters，一定要提到它。提供一个合适的默认依赖集可能比较困难，特别是存在大量可选依赖时，你应该避免引入任何非必需的依赖。