Spring Boot（04）创建自己的自动配置

创建自己的自动配置

当你的应用需要以jar包的形式提供给其它应用使用时，可以考虑把它们封装为一个Spring Boot Starter。即该jar包是可以自动添加需要引用的依赖项，也能够对核心功能进行自动配置。自动配置的核心类是一个标注了@Configuration的类，然后在自动配置类中可以定义相应的bean。比如下面的配置类中定义了一个HelloBean类型的bean。

@Configuration
public class HelloAutoConfiguration {

    @Bean
    public HelloBean helloBean() {
        return new HelloBean();
    }
    
}

然后需要在Classpath下的META-INF/spring.factories中以org.springframework.boot.autoconfigure.EnableAutoConfiguration为Key，以对应的自动配置类为Value进行配置，如果有多个自动配置类，多个自动配置类之间可以以英文逗号分隔。

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.elim.autoconfigure.HelloAutoConfiguration

Spring Boot在启动时将读取Classpath下META-INF/spring.factories中Key为org.springframework.boot.autoconfigure.EnableAutoConfiguration的配置类，将它们进行实例化。所以经过上述配置后，系统启动后将自动创建HelloBean类型的bean。

自动配置类通常不会像上面那样直接进行定义，而是会添加一些附加条件，比如在Classpath中拥有某些Class才生效，或者需要bean容器中不存在指定bean时才生效等等。Spring Boot为它们提供了一系列的@ConditionalXXX，常用的如下：

• ConditionalOnClass ：用于指定在Classpath下拥有某些Class时才生效
• ConditionalOnMissingClass ：用于指定在Classpath下不存在某些Class时才生效
• ConditionalOnBean ：用于指定在bean容器中存在某些bean时生效
• ConditionalOnMissingBean ：用于指定在bean容器中不存在某些bean时生效
• ConditionalOnWebApplication ：用于指定当应用是Web应用时生效
• ConditionalOnNotWebApplication ：用于指定当应用是非Web应用时生效
• ConditionalOnProperty ：用于指定当配置了某些特定的参数时生效
• ConditionalOnExpression ：用于根据SpEl表达式控制是否生效
• ConditionalOnSingleCandidate ：用于指定当bean容器中只存在唯一的指定类型的bean时才生效；当bean容器中存在多个指定类型的bean，但是使用@Primary指定了主候选者也是可以匹配的，即也是生效的

更多可用的Conditional注解可以参考API文档的org.springframework.boot.autoconfigure.condition包。

下面的代码中指定了当Classpath下存在Hello.class，且bean容器中不存在HelloBean类型的bean时下面的配置类将生效。

@Configuration
@ConditionalOnClass(Hello.class)
@ConditionalOnMissingBean(HelloBean.class)
public class HelloAutoConfiguration {

    @Bean
    public HelloBean helloBean() {
        return new HelloBean();
    }
    
}

这些条件配置注解也是可以添加到bean上的。比如下面代码中指定了当Environment中存在Key为autoconfigure.hello.enabled属性且其值为true时将创建HelloBean类型的bean，或者当Environment中不存在Key为autoconfigure.hello.enabled属性时也将创建HelloBean类型的bean（由matchIfMissing控制）。所以针对下面的配置，默认情况下是会创建HelloBean类型的bean的，如果不期望创建该类型的bean，可以在application.properties文件中指定autoconfigure.hello.enabled=false。

@Configuration
@ConditionalOnClass(Hello.class)
@ConditionalOnMissingBean(HelloBean.class)
public class HelloAutoConfiguration {

    @Bean
    @ConditionalOnProperty(prefix = "autoconfigure.hello", name = "enabled", havingValue = "true", matchIfMissing = true)
    public HelloBean helloBean() {
        return new HelloBean();
    }

}

当使用@ConditionalOnProperty时如果对应的值的可选值是true/false，可以不指定havingValue属性，此时只要值不为false，都会认为是true。

绑定参数

通常自定义的Starter会需要依靠外部配置的属性进行一些自动配置。此时可以使用@ConfigurationProperties标注在用来接收属性的Class上，它可以指定一个前缀，然后将在application.properties中寻找指定前缀和字段名称组合起来的属性进行绑定。比如下面的属性类中的name属性将绑定application.properties中定义的autoconfigure.hello.name属性的值。

@Data
@ConfigurationProperties("autoconfigure.hello")
public class HelloProperties {

    private String name;
    
    private String message;
    
}

@ConfigurationProperties标注的Class需要通过在配置类上使用@EnableConfigurationProperties进行启用。@EnableConfigurationProperties指定的配置类会自动注册为Spring bean容器中的一个bean，然后可以在配置类中自动注入对应的属性类。比如下面的代码中在HelloAutoConfiguration类上通过@EnableConfigurationProperties(HelloProperties.class)指定了启用HelloProperties这个属性配置类，然后把它定义为HelloAutoConfiguration类中的一个属性，并标注为自动注入，然后在定义HelloBean类型的bean时从HelloProperties中获取属性值进行配置。

@Configuration
@ConditionalOnClass(Hello.class)
@ConditionalOnMissingBean(HelloBean.class)
@EnableConfigurationProperties(HelloProperties.class)
public class HelloAutoConfiguration {

    @Autowired
    private HelloProperties helloProperties;
    
    @Bean
    @ConditionalOnProperty(prefix = "autoconfigure.hello", name = "enabled", matchIfMissing = true)
    public HelloBean helloBean() {
        HelloBean helloBean = new HelloBean();
        helloBean.setName(helloProperties.getName());
        return helloBean;
    }

}

上面的代码中定义HelloBean时从HelloProperties中获取name属性赋值给了HelloBean对象的name属性。这样的需求其实可以直接通过@ConfigurationProperties给HelloBean的name属性赋值，而不必添加多余的HelloProperties类。把@ConfigurationProperties定义在HelloBean定义的方法上可以拥有相同的效果，比如下面这样。

@Configuration
@ConditionalOnClass(Hello.class)
@ConditionalOnMissingBean(HelloBean.class)
public class HelloAutoConfiguration {

    @Bean
    @ConditionalOnProperty(prefix = "autoconfigure.hello", name = "enabled", matchIfMissing = true)
    @ConfigurationProperties("autoconfigure.hello")
    public HelloBean helloBean() {
        return new HelloBean();
    }

}

使用@ConfigurationProperties定义属性配置类时最好定义的前缀不要以spring开头，以免跟未来Spring官方提供的属性配置类存在冲突。

自定义的Starter在命名时不要命名为spring-boot-starter-xxx，可以命名为xxx-spring-boot-starter。spring-boot-starter-xxx留给官方使用。

参考文档

https://docs.spring.io/spring-boot/docs/2.0.3.RELEASE/reference/html/boot-features-developing-auto-configuration.html

（注：本文基于Spring Boot 2.0.3所写）