【翻译】Spring Boot 条件注解

本文翻译自 https://codingnconcepts.com/spring-boot/conditional-annotations-in-spring-boot

翻译过程中会对文中英语语序和不甚明确的地方进行微调，如有谬误欢迎评论指正。

在这篇教程中，我们将通过一些示例带你了解 Spring Boot 条件注解

概述

Spring Boot 是自以为是的，当 Spring Boot 在classpath中找到相关依赖项时，它会为模块提供默认（自动）配置。

举例，Spring Boot 提供了：

  1. 如 classpath 中未提供服务器组件依赖，则默认启用内嵌Tomcat作为服务端依赖。你也可以把它改成 Jetty 或 Undertow，仅需要添加相应的依赖到 classpath 中（译者注：常见的方式就是添加Maven或Gradle依赖）
  2. 当它在classpath找到 spring-cloud-starter-openfeign 依赖会提供默认的 HttpClient 配置，你可以通过在classpath中添加 OkHttpClient 或 ApacheHttpClient 依赖来改变HttpClient
  3. 当classpath中包含 spring-boot-starter-web 的依赖，则使用 Jackson 框架作为默认的 JSON 序列化传输请求和响应
  4. 当classpath中包含 spring-boot-starter-data-jpa 则会创建默认的数据源配置

Spring Boot 是如何做到这一切的呢？

Spring Boot 使用 @Conditional 注解实现了这一点。Spring Boot 大量使用 @Conditional 注解基于条件方式来加载默认配置、Bean对象的。

这些条件可以是：

  • classpath中可用的依赖、配置文件内容 或 类
  • 定义在 application.yml 或 application.properties 文件、系统配置、环境变量中的配置
  • Java的版本、操作系统、云平台、web应用 等。

它对我们有什么用处呢？

类似于Spring如何神奇地读取默认的配置，有些时候我们想基于自定义的条件来读取 Bean对象、模块 到Spring应用上下文中。

我们可以通过 @Conditional 注解+自定义的条件实现这个目标。

@Conditional

@Conditional 注解是用来匹配只有满足所有指定条件才能将Bean注册到Spring上下文中。

@Conditional 注解有以下三种使用方式：

1、作为方法级的注解

我们可以在 @Bean 注解下添加 @Conditional 注解来达到满足条件注册Bean。

@Configuration
class ConditionalBeanConfiguration {
 
  @Bean
  @Conditional(CustomCondition.class) //<- method level condition
  ConditionalBean conditionalBean(){
    return new ConditionalBean();
  };
}

2、作为类级别注解

我们可以在有 @Component, @Service, @Repository, @Controller, @RestController, 或 @Configuration 注解的类上标注 @Conditional，仅当满足条件才能将这个类型的 bean 注册到 Spring 上下文中。

@Component
@Conditional(CustomCondition.class) //<- class level condition
class ConditionalComponent {
}

带@Conditional注解的@Configuration类

如果一个 @Configuration 注解标识的类头包含 @Conditional 则这个类所有的 @Bean 方法、@Import 注解 和 @ComponentScan 注解都会被类头上的 @Conditional 影响，仅当条件满足时才会被加载。

@Configuration
@Conditional(CustomCondition.class) //<- class level condition
class ConditionalConfiguration {
  
  @Bean //<- will be loaded only if class level condition is met
  Bean bean(){
    // Code for bean definition
  };
  
}

3、作为源注解

我们可以创建一个自定义的注解，在注解上添加 @Conditional 作为新的条件注解

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Conditional(CustomCondition.class) //<- meta annotation condition
public @interface CustomConditionAnnotation {
}

现在我们可在方法和类上使用自定义的 @CustomConditionAnnotation 注解代替@Conditional 就像这样：

@Configuration
class ConditionalBeanConfiguration {
 
  @Bean
  @CustomConditionAnnotation  //<- custom annotation at method level
  ConditionalBean conditionalBean(){
    return new ConditionalBean();
  };
}
@Component
@CustomConditionAnnotation //<- custom annotation at class level
class ConditionalComponent {
}

自定义条件

在之前的例子中，我们使用 CustomCondition.class 中的 @Conditional 注解实现了条件匹配的逻辑。

让我们通过实现 Spring 的 Condition 接口的 matches 方法创建自定义条件吧：

public class CustomCondition implements Condition {
 
    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        return context.getEnvironment().getProperty("custom.condition.enabled", Boolean.class, false);
    }
}
application.yml
 
custom.condition.enabled: true

我们可以看到当 custom.condition.enabled 设为 true 时，CustomCondition 可匹配到。

组合条件-任一条件成立匹配

我们可组合多个条件，实现任一条件符合，换句话讲：类似于实现 OR 的逻辑操作。

再创建一个注解来组合

我们已经创建了一个自定义注解CustomCondition，让我们快速创建一个AnotherCustomCondition注解：

public class AnotherCustomCondition implements Condition {
 
    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        return context.getEnvironment().getProperty("another-custom.condition.enabled", Boolean.class, false);
    }
}
application.yml
 
another-custom.condition.enabled: true

我们看到 another-custom.condition.enabled 条件为 true 时， AnotherCustomCondition 能匹配到。

AnyNestedCondition（任意嵌套条件）

现在让我们通过扩展 Spring 的 AnyNestedCondition 类来组合上边两个注解，做到任一匹配：

public class CombinedConditionsWithAnyMatch extends AnyNestedCondition {
 
    public CombinedConditionsWithAnyMatch() {
        super(ConfigurationPhase.PARSE_CONFIGURATION);
        // super(ConfigurationPhase.REGISTER_BEAN);
    }
 
    @Conditional(CustomCondition.class)
    static class OnCustomCondition {}
 
    @Conditional(AnotherCustomCondition.class)
    static class OnAnotherCustomCondition {}
}

ConfigurationPhase（配置阶段）

注意 ConfigurationPhase 参数被传递到了构建方法：

  • 如果你想组合的条件到一个 @Configuration 类，使用 ConfigurationPhase.PARSE_CONFIGURATION；

  • 如果你想把条件应用到 @Bean 对象上，使用 ConfigurationPhase.REGISTER_BEAN

Spring Boot 需要区分这以上两种作用域以便在合适的时间应用这些条件。

使用任一条件匹配

让我们来应用组合条件到一个配置类吧：

@Configuration
@Conditional(CombinedConditionsWithAnyMatch.class)
class ConditionalConfiguration {
  
  @Bean
  Bean bean(){
    // TODO
  };
  
}

当任一条件满足时，这个配置类对象将被加载到Spring应用上下文中

application.yml
 
custom.condition.enabled: true
another-custom.condition.enabled: false

组合条件-所有条件成立匹配

我们可以组合多个条件来达到仅当所有条件都满足时才匹配的目的，类似于 AND 的逻辑操作。

AllNestedConditions

这次我们组合 CustomCondition、AnotherCustomCondition 这两个注解，通过扩展Spring的 AllNestedConditions 创建 匹配所有 （完全匹配）的条件类

public class CombinedConditionsWithAllMatch extends AllNestedConditions {
 
    public CombinedConditionsWithAllMatch() {
        // super(ConfigurationPhase.PARSE_CONFIGURATION);
        super(ConfigurationPhase.REGISTER_BEAN);
    }
 
    @Conditional(CustomCondition.class)
    static class OnCustomCondition {}
 
    @Conditional(AnotherCustomCondition.class)
    static class OnAnotherCustomCondition {}
}

使用完全匹配条件

这次我们将 ConfigurationPhase.REGISTER_BEAN 传入构造方法，我们就能使用这个组合条件放到 @Bean 对象，就像下边这样：

@Configuration
class ConditionalBeanConfiguration {
 
  @Bean
  @Conditional(CombinedConditionsWithAllMatch.class) //<- as method level annotation
  ConditionalBean conditionalBean(){
    return new ConditionalBean();
  };
}

这个Bean仅当所有条件都满足时才会加载到Spring应用上下文中：

application.yml
 
custom.condition.enabled: true
another-custom.condition.enabled: true

组合条件-所有条件不成立匹配

我们可以通过扩展 Spring 的 NoneNestedCondition 类来组合出所有条件都不成立的条件：

public class CombinedConditionsWithNoneMatch extends NoneNestedConditions {
 
    public CombinedConditionsWithNoneMatch() {
        super(ConfigurationPhase.PARSE_CONFIGURATION);
        // or super(ConfigurationPhase.REGISTER_BEAN);
    }
 
    @Conditional(CustomCondition.class)
    static class OnCustomCondition {}
 
    @Conditional(AnotherCustomCondition.class)
    static class OnAnotherCustomCondition {}
}

以上组合条件将会成功匹配如下配置：

application.yml
 
custom.condition.enabled: false
another-custom.condition.enabled: false

预定义的条件注解

Spring Boot 提供了一系列预定义的 @ConditionalOn... 便利注解供我们使用。让我们看看有哪些：

@ConditionalOnProperty

这个是Spring Boot中最常用的注解，它允许通过指定的配置来条件式加载类或Bean：

@Configuration
@ConditionalOnProperty(
    value="api.doc.enabled", 
    havingValue = "true", 
    matchIfMissing = true)
class ApiDocConfig {
  // TODO
}

ApiDocConfig 仅当 api.doc.enabled: true 时才会加载，如果没有配置这个参数，它也会被加载，因为定义了 matchIfMissing = true，通过这种方式，我们可以在没配置指定参数时创建默认配置，设置为false时才禁用。

一个常见的例子是当我们想去在开发环境开启一个指定配置，而生产环境禁用，反之亦然：

application-dev.yml
 
api.doc.enabled: true
 
application-prod.yml
 
api.doc.enabled: false

（译者注：通过不同配置文件区分环境，由条件注解判断是否加载类或对象到Spring上下文）

另一个常见的例子是定义了一个公共组件，通过不同项目的配置文件可以在开启或禁用这个功能，配置示例如下：

Project A -> application.yml
api.doc.enabled: true
 
Project B -> application.yml
api.doc.enabled: false

@ConditionalOnExpression

如果我们需要多个配置项组合更复杂的条件，我们可以使用 @ConditionalOnExpression （译者注：表达式条件注解）：

@Configuration
@ConditionalOnExpression(
  "${api.doc.enabled:true} and '${spring.profile.active}'.equalsIgnoreCase('DEV')"
)
class ApiDocConfig {
  // TODO
}

这个 ApiDocConfig 仅当 api.doc.enabled: true 并且 spring.profile.active: dev 时才会启用。我们告诉 Spring Boot 使用 true作为默认值适用于参数未设置的场景。

我们可以在这个注解中更充分地发挥 Spring Expression Language 的作用。

@ConditionalOnBean

我们可能需要仅当某个Bean依赖的Bean存在应用上下文中才创建这个Bean：

@Service
@ConditionalOnBean(ApiDocConfig.class)
class ApiDocService {
    // TODO
}

这个ApiDocService 仅当 ApiDocConfig 这个类的对象在应用上下文中才会加载。这个方法使我们可以定义依赖其他Bean的对象。（译者注：依赖对象存在则创建，否则不创建）

@ConditionalOnMissingBean

类似于上边的例子，可以使用 @ConditionalOnMissingBean 来确保应用上下文中没有某个对象才创建：

@Configuration
class DatabaseConfig {
 
  @Bean
  @ConditionalOnMissingBean
  DataSource dataSource() {
    return new InMemoryDataSource();
  }
}

这个例子演示了当应用上下文中没有其他 DataSource 对象时，创建 InMemoryDataSource这个对象，这和Spring Boot 在测试上下文创建内存数据源是类似的。

@ConditionalOnResource

这个注解仅当指定资源文件在 classpath 中是能找到的，才会加载这个配置

@Configuration
@ConditionalOnResource(resources = "/logback.xml")
class LoggingConfig {
  // TODO
}

这个 LoggingConfig 仅当 logback.xml 配置文件存在于 classpath 时才会加载。这样一来，我们能创建相似配置类，仅当它们的配置文件存在配置类才可用。

上面描述的条件注解是我们在 Spring Boot 项目中通常使用的最常见的注解。 Spring Boot 提供了许多其他的条件注解。 然而，它们并不常见，更适合框架开发而不是应用程序开发（Spring Boot 在后台大量使用其中的一些）。 所以，让我们在这里简单地看一下它们。

@ConditionalOnClass

仅当指定类在classpath下才会加载这个bean，我们可指定类的全路径或这个类的名称

@Service
@ConditionalOnClass(name = "com.example.config.LoggingConfig")
class LoggingService {
  // Code runs when class in available in classpath
}
 
@Service
@ConditionalOnClass(LoggingConfig.class)
class LoggingService {
  // Code runs when class in available in classpath
}

相似的，我们也可以用 @ConditionalOnMissingClass 注解来加载一个需要某个类不在classpath 下时才加载的bean。

@ConditionalOnWebApplication

仅当此应用是一个web应用时加载这个bean，默认只要是web容器都会匹配，也可以使用type 属性来缩小范围。（译者注：type 共有3种，ANY 表示任何 web 容器，范围最大；SERVLET 表示仅 servlet 容器；``REACTIVE` 表示仅响应式容器）

@Configuration
@ConditionalOnWebApplication
class RunsOnAnyWebApplication {
  // Code runs on web application
}
 
@Configuration
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
class RunsOnServletBasedWebApplication {
  // Code runs on Servlet based web application
}

类似地，也可以用 @ConditionalOnNotWebApplication 来达到非 Web 容器才加载 bean 的目的。

@ConditionalOnJava

仅在等于或高于指定JVM版本时才加载某个 bean。默认是等于或高于指定版本，也可以设置为 range 属性表示一个版本区间。

@Configuration
@ConditionalOnJava(JavaVersion.EIGHT)
class RunsOnJavaEightAndAbove {
  // Code runs on Java-8 and above versions
}
 
@Configuration
@ConditionalOnJava(value = JavaVersion.ELEVEN, range = ConditionalOnJava.Range.OLDER_THAN)
class RunsOnBelowJavaEleven {
  // Code runs below Java-11. 
  // Code doesn't run on Java-11 and above versions
}

@ConditionalOnCloudPlatform

仅在指定云平台上运行应用时才会加载此注解标记的 bean

@Configuration
@ConditionalOnCloudPlatform(CloudPlatform.KUBERNETES)
class RunsOnKubernetesCloudPlatform {
  // Code runs on application running on Kubernetes
}

@ConditionalOnWarDeployment

仅在传统 War 包打包部署时加载该注解标记的 bean。在应用以内嵌服务器运行时这个条件返回false。

@Configuration
@ConditionalOnWarDeployment
class RunsWithWarPackages {
  // Code runs with WAR package deployment
}

@ConditionalOnJndi

仅在指定的 JNDI 路径存在时加载该注解标记的 bean。如果没有路径指定，则条件匹配仅基于 javax.naming.InitialContext 的存在。

@Configuration
@ConditionalOnJndi("java:comp/env/ejb/myEJB")
class RunsWithJndiLocationAvailability {
  // Code runs when JNDI location is available
}

@ConditionalOnSingleCandidate

与 @ConditionalOnBean 类似，但它是仅在这个 bean 是唯一的候选时启用。如果 BeanFactory 中已包含多个匹配的 bean 实例但已定义主 @Primary 候选者，则条件也将匹配；本质上，如果自动装配具有定义类型的 bean，则条件匹配将成功。 强烈建议仅在自动配置类上使用此条件。（译者注：有一个或多个中有主候选的 bean 将匹配成功）

@Configuration
@ConditionalOnSingleCandidate(DataSource.class)
class RunsWithSingleDataSourceBean {
  // Code runs when single data source bean is determined
}

@ConditionalOnManagementPort

仅当 management.server.port 条件与 server.port 具体某种关系时加载bean。

有三种关系类型：

  • ManagementPortType.DISABLED：禁用或没定义管理端口
  • ManagementPortType.SAME：服务端口与管理端口相同
  • ManagementPortType.DIFFERENT：服务与管理端口不同
@Configuration
@ConditionalOnManagementPort(ManagementPortType.DISABLED)
class ManagementPortIsDisabled {
  // Code runs when management port is disabled
}
 
@Configuration
@ConditionalOnManagementPort(ManagementPortType.SAME)
class ManagementPortIsSameAsServerPort {
  // Code runs when management port is same as server port
}
 
@Configuration
@ConditionalOnManagementPort(ManagementPortType.DIFFERENT)
class ManagementPortIsDifferentFromServerPort {
  // Code runs when management port is different from server port
}

@ConditionalOnAvailableEndpoint

当指定的管理端点（译者注：接口地址）可用时加载 bean。如果一个端点被单独启用或使用 management.endpoints.web.exposure.include 暴露出来，都视为可用。

@Configuration
@ConditionalOnAvailableEndpoint(endpoint = InfoEndpoint.class)
class InfoEndpointIsAvailable {
  // Code runs when info management endpoint in enabled and exposed
}

端点是由 @Endpoint 或 @EndpointExtension 标记的bean。info 端点由 Spring Boot 提供，开箱即用。

Custom Management Endpoint

你也可以创建自定义的管理端点，就像这个例子：

@Component
@Endpoint(id = "custom-endpoint")
public class CustomEndpoint {
 
    @ReadOperation
    public String print() {
        return "This is custom management endpoint";
    }
}

现在让我们写一个仅当自定义端点可用时加载的配置类：

@Configuration
@ConditionalOnAvailableEndpoint(endpoint = CustomEndpoint.class)
class CustomEndpointConfiguration {
  // Configuration for custom endpoint
}

@ConditionalOnEnabledHealthIndicator

仅当健康指示器配置 management.health.<name>.enabled 启用时才加载此健康检测指示器类，<name> 需要指定为具体的值。

@Configuration
@ConditionalOnEnabledHealthIndicator(value = "heartbeat")
class HeatbeatHealthIndicator {
  // Code runs when management.health.heartbeat.enabled property is set to true.
}

总结

Conditional 注解给了 Spring Boot 提供了自以为是的配置（译者注：默认配置），给我们提供基于 @Conditional 自定义条件加载类的灵活性，以及非常便捷的 @ConditionalOn... 注解。

我们也可通过 AllNestedConditions、AnyNestedCondition、NoneNestedCondition 组合自定义的条件，它们为我们提供了基于环境和其他条件的模块化编码方式。

我们应该谨慎地使用 Conditional 注解，因为过度使用他们会导致难于调试与管理。

本文中代码的示例在github/springboot-config

本文作者：东北小狐狸

本文链接：https://www.cnblogs.com/hellxz/p/16253857.html

版权声明：本作品采用自由转载-非商用-非衍生-保持署名 (CC BY-NC-ND 3.0)许可协议进行许可。

posted @   东北小狐狸  阅读(460)  评论(0)  编辑  收藏  举报
点击右上角即可分享
微信分享提示
💬
评论
📌
收藏
💗
关注
👍
推荐
🚀
回顶
➖
收起