跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客GitHub 精选镜像工具UI配色美学隐私政策关于联系
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
Javajava

Spring Boot 中的 @ConditionalOnBean 注解详解

Spring Boot 的 @ConditionalOnBean 注解用于在容器中指定 Bean 存在时注册当前 Bean。支持通过 value/type 指定类型，name 指定名称，annotation 指定注解，search 指定搜索范围。常用于按需加载数据库 Bean、启用自动配置及处理可选依赖。与 @ConditionalOnMissingBean 相反，后者用于 Bean 不存在时注册。

奇形怪状发布于 2026/3/25更新于 2026/5/2526 浏览
Spring Boot 中的 @ConditionalOnBean 注解详解

Spring Boot 中的 @ConditionalOnBean 注解详解

1. 前言

在 Spring Boot 中，条件注解（Conditional 注解）是一种强大的功能，允许我们根据某些条件动态地注册或跳过特定的 Bean。其中，@ConditionalOnBean 是最常用的条件注解之一，它的作用是：当 Spring 容器中存在指定的 Bean 时，当前 Bean 才会被注册。

2. @ConditionalOnBean 作用与基本用法

2.1 @ConditionalOnBean 的作用

@ConditionalOnBean 主要用于以下场景：

  • 按需加载 Bean：只有在某个 Bean 存在时，另一个 Bean 才会被创建。
  • 模块化设计：某些功能模块需要依赖特定 Bean 才能启用，例如仅当某个组件存在时，自动配置才会生效。
  • 避免 Bean 冲突：如果某个 Bean 依赖其他 Bean，则可使用 @ConditionalOnBean 确保它不会因缺少依赖而加载失败。

2.2 基本用法

示例：当 DataSource Bean 存在时，才创建 MyService Bean
import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import javax.sql.DataSource;

@Configuration
public class MyConfig {
    @Bean
    public DataSource dataSource() {
        // 这里模拟 DataSource 实例，实际可用 HikariDataSource、Druid 等
        return new FakeDataSource();
    }

    @Bean
    @ConditionalOnBean(DataSource.class)
    // 仅当 DataSource 存在时，才创建 MyService
    public MyService myService() {
        return new MyService();
    }
}

  {
      {
        System.out.println();
    }
}

    {
    
}
class
MyService
public
MyService
()
"MyService 被创建"
class
FakeDataSource
implements
DataSource
// 这里可以模拟 DataSource 方法

执行结果：

MyService 被创建

如果 dataSource() 方法被注释掉，则 MyService 不会被创建。

3. @ConditionalOnBean 详解

@ConditionalOnBean 提供了多个属性，可以更加灵活地控制 Bean 的创建。

3.1 value 和 type 属性（指定 Bean 类型）

用于指定某种类型的 Bean 存在时，当前 Bean 才会被注册。

@Bean
@ConditionalOnBean(value = DataSource.class)
// 仅当 DataSource 存在时生效
public MyRepository myRepository() {
    return new MyRepository();
}

等效于：

@Bean
@ConditionalOnBean(type = "javax.sql.DataSource")
// 使用全限定类名
public MyRepository myRepository() {
    return new MyRepository();
}

区别：

  • value：直接使用 Class 类型，编译时检查更安全。
  • type：使用字符串，可用于避免某些类找不到（如可选依赖）。

3.2 name 属性（指定 Bean 名称）

用于 指定某个 Bean 名称是否存在 来决定当前 Bean 是否加载。

@Bean
@ConditionalOnBean(name = "customBean")
// 仅当名为 customBean 的 Bean 存在时注册
public MyComponent myComponent() {
    return new MyComponent();
}

3.3 annotation 属性（指定 Bean 需要标注的注解）

可以指定某些 Bean 是否包含特定注解，如果包含，则当前 Bean 才会被注册。

@Bean
@ConditionalOnBean(annotation = Repository.class)
// 仅当存在 @Repository 注解的 Bean 时生效
public MyService myService() {
    return new MyService();
}

3.4 search 属性（搜索范围）

默认情况下，@ConditionalOnBean 只会在 当前应用上下文 中查找 Bean，而不会查找 父上下文（即 Spring Boot 的 ApplicationContext 层级）。

search 选项可以指定搜索范围：

  • ALL：在所有父子 ApplicationContext 中搜索。
  • CURRENT（默认）：仅搜索当前 ApplicationContext。
@Bean
@ConditionalOnBean(value = DataSource.class, search = SearchStrategy.ALL)
// 在所有上下文中搜索
public MyService myService() {
    return new MyService();
}

4. @ConditionalOnBean 使用场景

场景 1：按需加载数据库相关 Bean

如果应用程序中 使用了数据库，则提供一个 DatabaseService，否则不创建：

@Bean
@ConditionalOnBean(DataSource.class)
public DatabaseService databaseService() {
    return new DatabaseService();
}

场景 2：启用某些自动配置

Spring Boot 的 spring-boot-autoconfigure 模块大量使用 @ConditionalOnBean 来控制自动配置。例如：

  • 只有当 DispatcherServlet 存在时，Spring MVC 相关的自动配置才会生效。
@Configuration
@ConditionalOnBean(DispatcherServlet.class)
public class MvcAutoConfiguration {
    // 仅当 DispatcherServlet 存在时，Spring MVC 配置生效
}

场景 3：可选依赖的组件

有时，某些功能是可选的，比如当 Redis 组件存在时，才创建缓存管理器：

@Bean
@ConditionalOnBean(name = "redisTemplate")
// 只有当 redisTemplate 存在时才加载
public CacheManager cacheManager() {
    return new RedisCacheManager();
}

5. @ConditionalOnBean vs @ConditionalOnMissingBean

注解作用
@ConditionalOnBean当指定 Bean 存在时，才注册当前 Bean
@ConditionalOnMissingBean当指定 Bean 不存在时，才注册当前 Bean

示例：

@Bean
@ConditionalOnMissingBean(DataSource.class)
// 仅当 DataSource 不存在时才创建
public DataSource defaultDataSource() {
    return new DefaultDataSource();
}

6. 结论

在 Spring Boot 中，@ConditionalOnBean 可以帮助我们根据 是否存在特定 Bean 来 动态注册 Bean，广泛用于 按需加载、自动配置 等场景。

总结：

✅ 指定 Bean 类型：@ConditionalOnBean(DataSource.class)
✅ 指定 Bean 名称：@ConditionalOnBean(name = "customBean")
✅ 指定 Bean 注解：@ConditionalOnBean(annotation = Repository.class)
✅ 搜索范围：@ConditionalOnBean(search = SearchStrategy.ALL)

目录

  1. Spring Boot 中的 @ConditionalOnBean 注解详解
  2. 1. 前言
  3. 2. @ConditionalOnBean 作用与基本用法
  4. 2.1 @ConditionalOnBean 的作用
  5. 2.2 基本用法
  6. 示例：当 DataSource Bean 存在时，才创建 MyService Bean
  7. 3. @ConditionalOnBean 详解
  8. 3.1 value 和 type 属性（指定 Bean 类型）
  9. 3.2 name 属性（指定 Bean 名称）
  10. 3.3 annotation 属性（指定 Bean 需要标注的注解）
  11. 3.4 search 属性（搜索范围）
  12. 4. @ConditionalOnBean 使用场景
  13. 场景 1：按需加载数据库相关 Bean
  14. 场景 2：启用某些自动配置
  15. 场景 3：可选依赖的组件
  16. 5. @ConditionalOnBean vs @ConditionalOnMissingBean
  17. 6. 结论
  18. 总结：
  • 💰 8折买阿里云服务器限时8折了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 🤖 一键搭建Deepseek满血版了解详情
  • 一键打造专属AI 智能体了解详情
极客日志微信公众号二维码

微信扫一扫，关注极客日志

微信公众号「极客日志V2」，在微信中扫描左侧二维码关注。展示文案：极客日志V2 zeeklog

更多推荐文章

查看全部
  • 前端视角 | 从零搭建并启动若依后端(环境配置)
  • 基于 Next.js 和 Wagmi 构建支持 TokenP 钱包登录的 DApp 前端
  • 前端框架选型指南：React、Vue 与 Angular 对比分析
  • C++ 核心知识点解析（九）
  • LLaMA-Factory 详细安装与配置指南
  • PX4+ROS 无人机 Offboard 控制：模式解析与实战
  • KingbaseES 内核级 SQL 防火墙：白名单机制与性能实测
  • Spring AI 1.1.2 集成 MCP（Model Context Protocol）实战：以 Tavily 搜索为例
  • 使用 Python 和 WinRM 远程控制 Windows 服务器
  • 人工智能：自然语言处理在法律领域的应用与实战
  • Python EXE 解包工具实战：py2exe 与 pyinstaller 逆向
  • 2025年12月电子学会青少年软件编程Python三级等级考试真题
  • Qwen3Guard-Gen-WEB 全球多语言内容合规部署实测
  • HTML input 类型全解析与实战避坑指南
  • GLM-4.7-Flash 本地 Copilot 工具构建实战教程
  • FPGA 原型验证平台中 Vivado 许可证的动态加载方法
  • 基于Python的轻量级上位机开发流程解析
  • 低空无人机 AI 算法全景：74 种行业场景应用解析
  • 使用 VibeThinker 解决动态规划典型题例
  • 基于 CSANMT 的实时中英对照翻译服务实战

相关免费在线工具

  • Keycode 信息

    查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online

  • Escape 与 Native 编解码

    JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online

  • JavaScript / HTML 格式化

    使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online

  • JavaScript 压缩与混淆

    Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online