条件装配 on pipo's site

@ConditionalOnMissingBean 注解

Sat, 17 Jan 2026 20:52:00 +0800

`@ConditionalOnMissingBean` 注解详解

核心概念

@ConditionalOnMissingBean 是 Spring Boot 提供的条件注解，用于控制 Bean 的创建条件。

总结：如果没有就用我的，有了就用你的。

语法格式

    @Bean
    @ConditionalOnMissingBean(需要检查的类.class)  // 注意：不需要引号
    public BeanType beanName() {
        return new BeanType();
    }

主要属性

属性	说明	示例
`value`	按类型指定要检查的 Bean 类	`@ConditionalOnMissingBean(DataSource.class)`
`name`	按名称指定要检查的 Bean	`@ConditionalOnMissingBean(name = "myService")`
`search`	限制搜索的 ApplicationContext 层级	`@ConditionalOnMissingBean(search = SearchStrategy.CURRENT)`

工作原理

┌─────────────────────────────────────────────────────────────┐
│                     @ConditionalOnMissingBean                 │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   检查容器中是否存在目标 Bean                                  │
│                                                              │
│   ┌─────────────┐    存在?    ┌──────────────┐              │
│   │ 目标 Bean   │ ─────────>  │  不创建当前Bean│              │
│   └─────────────┘    是      └──────────────┘              │
│                                                              │
│   ┌─────────────┐    不存在   ┌──────────────┐              │
│   │ 目标 Bean   │ ─────────>  │  创建当前 Bean│              │
│   └─────────────┘            └──────────────┘              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

使用场景

提供默认实现：当用户没有自定义 Bean 时提供默认值
避免 Bean 冲突：防止创建重复的 Bean
可扩展的自动配置：允许用户覆盖默认配置
按需加载：只在需要时才创建 Bean

代码示例

1. 基本用法（按类型检查）

@Configuration
public class DefaultDataSourceAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean(DataSource.class)
    public DataSource defaultDataSource() {
        System.out.println("创建默认数据源");
        return new HikariDataSource();
    }
}

2. 按名称检查

@Bean
@ConditionalOnMissingBean(name = "myCustomService")
public MyService myService() {
    return new MyService();
}

3. 默认返回类型检查

@Bean
@ConditionalOnMissingBean  // 等价于 @ConditionalOnMissingBean(CacheService.class)
public CacheService cacheService(CacheManager cacheManager) {
    return new CacheService(cacheManager);
}

4. 完整示例：用户可覆盖的自动配置

@Configuration
@EnableConfigurationProperties(CacheProperties.class)
public class CacheAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnProperty(prefix = "app.cache", name = "enabled", havingValue = "true")
    public CacheManager cacheManager(CacheProperties properties) {
        RedisCacheManager manager = new RedisCacheManager();
        manager.setHost(properties.getHost());
        manager.setPort(properties.getPort());
        manager.setTtl(properties.getTtl());
        return manager;
    }
}

不加注解会出现什么问题？

问题：Bean 冲突导致启动失败

不加注解的情况：

// 框架自动配置
@Configuration
public class DefaultConfig {

    @Bean  // ❌ 没有加 @ConditionalOnMissingBean
    public DataSource dataSource() {
        return new HikariDataSource();
    }
}

// 用户自定义配置
@Configuration
public class MyConfig {

    @Bean
    public DataSource dataSource() {
        return new MysqlDataSource();
    }
}

运行结果：报错！

***************************
APPLICATION FAILED TO START
***************************

The bean 'dataSource', defined in DefaultConfig,
could not be registered. A bean with that name has already been defined
and overriding is disabled.

加注解的情况

// 框架自动配置
@Configuration
public class DefaultConfig {

    @Bean
    @ConditionalOnMissingBean(DataSource.class)  // ✅ 加上这个注解
    public DataSource dataSource() {
        System.out.println("创建默认数据源");
        return new HikariDataSource();
    }
}

// 用户自定义配置
@Configuration
public class MyConfig {

    @Bean
    public DataSource dataSource() {
        System.out.println("创建自定义数据源");
        return new MysqlDataSource();
    }
}

运行结果：

用户定义了 DataSource → 使用用户的，默认的不会创建
用户没定义 DataSource → 使用默认的

// 用户定义了 DataSource，控制台输出：
创建自定义数据源

// 用户没定义 DataSource，控制台输出：
创建默认数据源

对比总结

情况	不加注解	加注解
用户定义了 Bean	❌ Bean 冲突，启动失败	✅ 使用用户的 Bean
用户没定义 Bean	✅ 创建默认 Bean	✅ 创建默认 Bean

类级别 vs 方法级别

// 方法级别：只阻止该Bean的注册
@Configuration
public class MyConfig {
    @Bean
    @ConditionalOnMissingBean
    public MyBean myBean() { ... }  // 只影响这个Bean

    @Bean
    public OtherBean otherBean() { ... }  // 不受影响
}

// 类级别：阻止整个配置类作为Bean注册
@Configuration
@ConditionalOnMissingBean
public class MyConfig {
    @Bean
    public MyBean myBean() { ... }  // 条件不匹配时整个类都不会注册

    @Bean
    public OtherBean otherBean() { ... }
}

与 `@ConditionalOnBean` 的对比

@ConditionalOnBean(DataSource.class)        // 容器中存在DataSource时创建
@ConditionalOnMissingBean(DataSource.class)  // 容器中不存在DataSource时创建

这两个注解互为相反的条件，常用于实现"可选依赖"或"默认回退"的配置模式。

核心要点

使用场景：方便被替换 - 完全正确
效果：如果用户自己实现了这个类就不会注入了 - 完全正确
语法：@ConditionalOnMissingBean(类.class) - 不需要引号

Reference

@ConditionalOnProperty 注解

Sat, 17 Jan 2026 20:33:00 +0800

@ConditionalOnProperty 注解详解

@ConditionalOnProperty 是 Spring Boot 的条件注解，用于根据配置文件中的属性值控制 Bean 是否被创建。它检查指定属性是否存在、值是否匹配，从而决定是否启用相关配置。（符合条件就创建Bean）

工作原理

检查逻辑：注解会检查配置文件（如 application.yaml 或 application.properties）中的属性值。
条件判断：
- 如果属性值(name| value) 等于 havingValue（或默认匹配），则条件为真，Bean 被创建。
- 否则为假，Bean 不被创建。
结果影响：
- 为真：Bean 被实例化，配置生效。
- 为假：Bean 被跳过，配置无效。

主要参数

参数	说明	默认值
`name` / `value`	配置文件中的属性名（从 `application.yml` 读取）	-
`havingValue`	期望的属性值，只有匹配时才创建 Bean	`""`（空字符串，表示只要属性存在即可）
`matchIfMissing`	属性不存在时是否默认匹配（`true` = 创建，`false` = 不创建）	`false`
`prefix`	属性名前缀，用于简化配置（如 `prefix="app"` + `name="enabled"` → `app.enabled`）	`""`

参数组合示例：

// 场景1: 属性必须存在且值为 "true"
@ConditionalOnProperty(name = "feature.enabled", havingValue = "true")
// 配置: feature.enabled=true ✅ | feature.enabled=false ❌ | 不存在 ❌

// 场景2: 属性存在即可（值不限）
@ConditionalOnProperty(name = "feature.enabled")
// 配置: feature.enabled=true ✅ | feature.enabled=false ✅ | 不存在 ❌

// 场景3: 属性不存在时默认创建
@ConditionalOnProperty(name = "feature.enabled", matchIfMissing = true)
// 配置: feature.enabled=true ✅ | feature.enabled=false ❌ | 不存在 ✅

基础示例

假设 application.yaml 配置如下：

app:
  logging:
    enabled: true  # 可改为 false 或删除测试

@Configuration
public class AppConfig {

    @Bean
    @ConditionalOnProperty(name = "app.logging.enabled", havingValue = "true")
    public LoggingService loggingService() {
        return new LoggingService();
    }
}
// 如果 app.logging.enabled=true → LoggingService 被创建
// 如果为 false 或不存在 → 不创建

实际业务场景

场景1：短信服务降级开关

需求：生产环境关闭短信发送功能，或切换到模拟实现（避免扣费）。

配置文件 application.yml：

service:
  sms:
    enabled: false
    mock: false          # true 则使用模拟实现（不实际发送）

实现代码：

@Configuration
public class SmsConfig {

    // 真实短信服务（阿里云/腾讯云）
    @Bean
    @ConditionalOnProperty(name = "service.sms.enabled", havingValue = "true", matchIfMissing = false)
    public SmsService realSmsService() {
        return new AliyunSmsService(); // 或 TencentSmsService
    }

    // 模拟短信服务（开发/测试用）
    @Bean
    @ConditionalOnProperty(name = "service.sms.enabled", havingValue = "false", matchIfMissing = true)
    public SmsService mockSmsService() {
        return new MockSmsService(); // 只打印日志，不发送
    }
}

效果：

生产环境关闭 enabled → 自动切换到模拟实现，避免意外扣费
开发/测试环境开启 → 真实发送

场景2：多数据源动态切换（读写分离）

需求：根据配置选择使用主库（写）或从库（读）的数据源。

配置文件：

datasource:
  mode: master  # master=主库 | slave=从库 | cluster=集群模式

实现代码：

@Configuration
public class DataSourceConfig {

    // 主数据源（写库）
    @Bean
    @ConfigurationProperties(prefix = "spring.datasource.master")
    @ConditionalOnProperty(name = "datasource.mode", havingValue = "master", matchIfMissing = true)
    public DataSource masterDataSource() {
        return DataSourceBuilder.create().build();
    }

    // 从数据源（读库）
    @Bean
    @ConfigurationProperties(prefix = "spring.datasource.slave")
    @ConditionalOnProperty(name = "datasource.mode", havingValue = "slave")
    public DataSource slaveDataSource() {
        return DataSourceBuilder.create().build();
    }

    // 集群模式（负载均衡）
    @Bean
    @ConditionalOnProperty(name = "datasource.mode", havingValue = "cluster")
    public DataSource clusterDataSource() {
        return new ClusterDataSource(); // 自定义实现
    }
}

效果：

开发环境使用 mode: master → 单库开发
生产环境使用 mode: slave → 读写分离
高并发场景使用 mode: cluster → 多库负载均衡

场景3：功能灰度发布（新功能开关）

需求：新功能上线时先对部分用户开放，通过配置控制是否启用。

配置文件：

feature:
  new-ui:
    enabled: true      # 是否启用新UI
    whitelist: "user1,user2,admin"  # 白名单用户

实现代码：

@Configuration
public class FeatureConfig {

    // 新版UI服务
    @Bean
    @ConditionalOnProperty(name = "feature.new-ui.enabled", havingValue = "true")
    public UiService newUiService() {
        return new NewUiService();
    }

    // 旧版UI服务（降级方案）
    @Bean
    @ConditionalOnProperty(name = "feature.new-ui.enabled", havingValue = "false", matchIfMissing = true)
    public UiService legacyUiService() {
        return new LegacyUiService();
    }
}

// 使用示例
@Service
public class UserService {

    @Autowired
    private UiService uiService;  // 根据配置自动注入新旧实现

    public String getHomePage(String userId) {
        return uiService.renderHomePage(userId);
    }
}

效果：

灰度期间 enabled: false → 所有用户用旧版
逐步放开 enabled: true → 部分用户用新版
出问题立即回滚 → 改为 false 即可

常见问题

Q1: `matchIfMissing` 的使用场景？

设为 true：默认启用的功能（如开发环境默认开启日志）
设为 false：需要显式配置才能启用（如生产环境的监控功能）

Q2: 与 `@Value` 注解的区别？

特性	`@ConditionalOnProperty`	`@Value`
作用范围	类/方法级别（控制 Bean 创建）	字段/参数/方法级别（注入值）
决策时机	应用启动时（只判断一次）	每次访问时（动态读取）
典型场景	功能开关、数据源切换	配置参数注入

Q3: 如何实现多条件组合？

使用 @ConditionalOnExpression（SpEL 表达式）：

@ConditionalOnExpression("'${service.sms.enabled}' == 'true' and '${service.sms.mock}' == 'false'")
public SmsService realSmsService() { ... }

条件装配 on pipo's site

@ConditionalOnMissingBean 注解

@ConditionalOnMissingBean 注解详解

核心概念

语法格式

主要属性

工作原理

使用场景

代码示例

1. 基本用法（按类型检查）

2. 按名称检查

3. 默认返回类型检查

4. 完整示例：用户可覆盖的自动配置

不加注解会出现什么问题？

问题：Bean 冲突导致启动失败

加注解的情况

对比总结

类级别 vs 方法级别

与 @ConditionalOnBean 的对比

核心要点

Reference

@ConditionalOnProperty 注解

@ConditionalOnProperty 注解详解

工作原理

主要参数

基础示例

实际业务场景

场景1：短信服务降级开关

场景2：多数据源动态切换（读写分离）

场景3：功能灰度发布（新功能开关）

常见问题

Q1: matchIfMissing 的使用场景？

Q2: 与 @Value 注解的区别？

Q3: 如何实现多条件组合？

Reference

`@ConditionalOnMissingBean` 注解详解

与 `@ConditionalOnBean` 的对比

Q1: `matchIfMissing` 的使用场景？

Q2: 与 `@Value` 注解的区别？