好的，阿杰，我给你整理一份 Spring Boot 中 @ConditionalOnProperty 使用详解，包含概念、语法、示例以及常见应用场景。

🌟 Spring Boot @ConditionalOnProperty 详解

1. 什么是 @ConditionalOnProperty？

@ConditionalOnProperty 是 Spring Boot 提供的条件注解之一，用于 根据配置文件中的属性值决定 Bean 是否加载。

特点：

  • 典型场景：根据 application.properties/yml 配置来动态启用或禁用某个 Bean
  • 可以与 自动配置（@Configuration） 搭配使用
  • 属于 Spring Boot 的 条件化注解，其他类似注解还有：
    • @ConditionalOnClass
    • @ConditionalOnMissingBean
    • @ConditionalOnBean
    • @ConditionalOnExpression

2. 基本语法

@ConditionalOnProperty(
    prefix = "配置前缀",
    name = "属性名",
    havingValue = "属性值",
    matchIfMissing = false
)
属性说明
prefix属性前缀，例如 app.feature
name属性名，例如 enabled
havingValue当属性值等于此值时，Bean 才会加载（默认为空，即属性存在即可）
matchIfMissing当属性不存在时是否匹配，true 表示 Bean 会被创建

3. 示例

3.1 简单示例

application.properties

feature.enabled=true

配置类

@Configuration
@ConditionalOnProperty(prefix = "feature", name = "enabled", havingValue = "true")
public class FeatureConfig {

    @Bean
    public MyFeatureService myFeatureService() {
        return new MyFeatureService();
    }
}
  • 当 feature.enabled=true 时，MyFeatureService 会被创建
  • 当 feature.enabled=false 或不存在时，Bean 不会加载

3.2 使用 matchIfMissing

@Configuration
@ConditionalOnProperty(prefix = "feature", name = "enabled", havingValue = "true", matchIfMissing = true)
public class DefaultFeatureConfig {
    @Bean
    public MyDefaultFeatureService defaultFeatureService() {
        return new MyDefaultFeatureService();
    }
}
  • 即使配置文件没有 feature.enabled，Bean 也会被创建
  • matchIfMissing = true 常用于默认启用功能

3.3 结合多个属性

@Configuration
@ConditionalOnProperty(
    prefix = "feature",
    name = {"enabled", "type"},
    havingValue = "true"
)
public class MultiFeatureConfig {
    @Bean
    public MultiFeatureService multiFeatureService() {
        return new MultiFeatureService();
    }
}
  • 多个属性都满足条件时，Bean 才会加载
  • havingValue 会应用到所有属性（全部匹配）

4. 常见应用场景

  1. 功能开关（Feature Toggle）
    • 可以在配置文件中控制功能模块是否启用
    • 例如：支付模块、日志模块、消息队列模块
  2. 动态选择不同实现
    • 根据配置加载不同的 Bean 实现
    • 例如：开发环境使用 Mock 服务，生产环境使用真实服务
  3. 与 Spring Boot 自动配置结合
    • Spring Boot 核心自动配置也广泛使用 @ConditionalOnProperty
    • 例如：spring.autoconfigure.exclude 配置可以禁用某些自动配置

5. 注意事项

  • 属性类型：havingValue 默认为字符串比较，如果属性是布尔类型 true/false，需用字符串表示 "true"
  • matchIfMissing：默认 false，意味着属性不存在时 Bean 不会创建
  • 与 @ConditionalOnMissingBean 配合：可以实现 属性开启 + Bean 不存在 时才创建 Bean

6. 小结

  • @ConditionalOnProperty 是 基于配置文件控制 Bean 加载的条件注解
  • 核心用途：功能开关、动态配置、自动配置控制
  • 配合 prefix、name、havingValue 和 matchIfMissing 可以实现灵活控制