Spring 条件装配演进之路：从配置文件到 @Conditional 体系_Java

spring 的条件装配经历了从配置文件时代到 @conditional 注解体系的演进，核心是从“手动区分环境”走向“按需自动决策”。演进脉络大致分三个阶段：spring 3.1 之前用 spel 表达式在 xml 里做条件判断；spring 3.1 引入 @profile 按环境切换；spring 4.0 正式推出 @conditional 注解，spring boot 又在其上扩展出 @conditionalonxxx 全家桶，实现自动装配。

1 为什么需要条件装配：多环境下的配置爆炸

假设你在开发一个订单系统，本地用 h2 内存数据库，测试环境用 mysql，生产环境用云数据库。过去，你可能会把三种数据源配置写进三个 properties 文件，然后每次部署时手工修改配置文件。这种方式有三个明显痛点：

改配置容易出错：部署时忘了切换，本地代码连着生产库，可能出现脏数据甚至故障。
jar 包无法通用：一个 jar 只能对应一种环境，维护多个 jar 包成本高。
逻辑与配置纠缠：某些功能只在特定环境启用，比如本地打印 sql、生产开启缓存，都靠硬编码 flag 控制。

条件装配要解决的核心问题就是：由容器根据运行时的条件，决定装配哪些 bean，让同一份代码能被不同环境复用。spring boot 的自动配置更是把条件判断应用到极致，比如你引入了 mysql 驱动，容器才自动创建 datasource。

先记住一个最小模型：“如果条件成立，就创建这个 bean；否则跳过。”” 条件可以是配置文件里的值、类的存在、环境变量、系统属性等。

2 条件装配的整体框架

我们可以把条件装配体系拆成三层：

条件声明层：告诉容器“什么时候才能创建这个 bean”。
bean 定义层：描述 bean 的样子，如类型、初始化参数、依赖。
容器求值层：spring 容器解析配置时，先检查条件，再决定是否注册或处理该 bean。

这三层通过 @profile、@conditional、条件注解和 condition 接口连接。

下面用一个流程图展示 spring 启动时的条件求值顺序：

[容器启动] -> 解析配置类/组件扫描 -> 遇到 @conditional 或 @profile
    -> 调用 condition.matches(conditioncontext, annotatedtypemetadata)
        -> 结果: true? 继续注册 bean : 跳过
    -> 完成注册 -> 实例化和初始化

所有条件都在 bean 定义阶段求值，而不是在实例化时。这意味着一旦容器已启动，改变配置文件里的值不会影响已创建的 bean。

3 配置文件的局限：从 spring.profiles.active 到 @profile

在 spring 3.1 之前，人们普遍使用 propertyplaceholderconfigurer 加多个 properties 文件，通过替换占位符实现环境切换。这种方式必须打包多个配置文件，且容易出错。

@profile 注解在 spring 3.1 中引入，它允许你声明一个 bean 属于哪个“环境”。环境由 spring.profiles.active 属性或 springapplication.setadditionalprofiles() 确定。

我们来看一个完整示例：

示例一：基于 @profile 切换数据源环境

目标：演示如何用 @profile 为不同环境装配不同数据源，理解环境激活前后容器行为。

前置环境：jdk 1.8+，maven 3.6+，spring boot 2.5+，ide。

步骤：创建 maven 工程，加入依赖。

<parent>
    <groupid>org.springframework.boot</groupid>
    <artifactid>spring-boot-starter-parent</artifactid>
    <version>2.5.4</version>
</parent>
<dependencies>
    <dependency>
        <groupid>org.springframework.boot</groupid>
        <artifactid>spring-boot-starter-web</artifactid>
    </dependency>
</dependencies>

创建配置类：

import org.springframework.context.annotation.bean;
import org.springframework.context.annotation.configuration;
import org.springframework.context.annotation.profile;
@configuration
public class datasourceconfig {
    @bean
    @profile("dev")
    public datasource devdatasource() {
        return new embeddeddatasource();
    }
    @bean
    @profile("prod")
    public datasource proddatasource() {
        return new clouddatasource();
    }
}

为了演示，定义一个接口和两个实现：

public interface datasource { string connect(); }
public class embeddeddatasource implements datasource {
    @override public string connect() { return "h2 内存库"; }
}
public class clouddatasource implements datasource {
    @override public string connect() { return "云数据库"; }
}

主应用：

import org.springframework.boot.springapplication;
import org.springframework.boot.autoconfigure.springbootapplication;
import org.springframework.context.configurableapplicationcontext;
@springbootapplication
public class demoapplication {
    public static void main(string[] args) {
        configurableapplicationcontext ctx = springapplication.run(demoapplication.class);
        datasource ds = ctx.getbean(datasource.class);
        system.out.println("当前数据源: " + ds.connect());
        ctx.close();
    }
}

先不设 profile，运行会报错，因为有两个候选 bean，容器无法确定。此时指定 profile 运行：

mvn spring-boot:run -dspring-boot.run.profiles=dev
# 或
java -jar target/demo.jar --spring.profiles.active=prod

预期输出：dev 下输出“当前数据源: h2 内存库”；prod 下输出“当前数据源: 云数据库”。

说明：@profile 本质上也是一个 @conditional，它通过 profilecondition 检查环境是否匹配。这个例子的优点是把装配逻辑从代码中抽离，但缺点是不能表达更复杂的条件，比如“当存在某个类时才创建”。

4 @conditional：更精细的条件判断

@profile 只解决环境维度的问题，如果想根据“某 jar 是否在 classpath”“某配置属性是否被设置”“某 bean 是否存在”来决定装配，就需要 @conditional 注解。它是 spring 4 引入的，为更通用的条件判断打开大门。

4.1 @conditional 的核心角色

@conditional 是方法级或类型级的注解，可以标注在配置类的@bean方法上或类上。它接收一个或多个 condition 类作为参数。

@bean
@conditional(memorycondition.class)
public cachemanager cachemanager() {
    return new concurrentmapcachemanager();
}

condition 接口只有一个方法：

public interface condition {
    boolean matches(conditioncontext context, annotatedtypemetadata metadata);
}

conditioncontext 提供了访问环境、类加载器、beanfactory 的能力，annotatedtypemetadata 能拿到该 bean 定义上的其他注解。

4.2 自定义条件处理环境变量

现在，环境变量是常见的触发条件，比如通过 my_custom_cache_size 控制缓存大小。

示例二：根据环境变量和配置属性自定义条件

目标：演示一个业务场景：当配置了 cache.enabled=true 或存在环境变量 cache_enabled（值为 true）时，才创建 cachemanager。

前置：同上，spring boot 项目。

代码步骤：先定义条件类。

import org.springframework.context.annotation.condition;
import org.springframework.context.annotation.conditioncontext;
import org.springframework.core.type.annotatedtypemetadata;
public class cachecondition implements condition {
    @override
    public boolean matches(conditioncontext context, annotatedtypemetadata metadata) {
        string fromenv = context.getenvironment().getproperty("cache_enabled");
        if (boolean.parseboolean(fromenv)) {
            return true;
        }
        string prop = context.getenvironment().getproperty("cache.enabled");
        return boolean.parseboolean(prop);
    }
}

配置类：

import org.springframework.context.annotation.bean;
import org.springframework.context.annotation.conditional;
import org.springframework.context.annotation.configuration;
import java.util.concurrent.concurrenthashmap;
@configuration
public class cacheconfig {
    @bean
    @conditional(cachecondition.class)
    public cachemanager cachemanager() {
        return new cachemanager(); // 自定义类
    }
    static class cachemanager {
        private final concurrenthashmap<string, string> store = new concurrenthashmap<>();
        void put(string k, string v) { store.put(k, v); }
        string get(string k) { return store.get(k); }
    }
}

主类中注入这个 bean 并尝试使用：

@springbootapplication
public class app {
    @autowired(required = false)
    private cacheconfig.cachemanager cachemanager;
    public static void main(string[] args) {
        configurableapplicationcontext ctx = springapplication.run(app.class, args);
        app app = ctx.getbean(app.class);
        if (app.cachemanager != null) {
            app.cachemanager.put("hello", "world");
            system.out.println("缓存值: " + app.cachemanager.get("hello"));
        } else {
            system.out.println("缓存未启用，cachemanager 为 null");
        }
        ctx.close();
    }
}

运行方式：

设置环境变量：cache_enabled=true，然后运行，输出“缓存值: world”。
不设置任何属性，运行输出“缓存未启用”。
在 application.properties 中添加 cache.enabled=true，也同样启用。

解释：条件类在容器刷新早期被调用，此时环境已经解析。关键在于 conditioncontext 能从 environment 中读取系统环境变量、application.properties 等。这个例子展示了 @conditional 可以组合多种条件来源，而 @profile 无法做到。

常见错误：不要在条件里进行高开销操作如网络io，因为每个工厂方法都可能执行多次。

5 spring boot 自动配置中的条件评估

spring boot 大量使用条件注解来实现他的“自动配置”。它的核心是 spring-boot-autoconfigure 中的一堆 @conditionalonxxx，这些注解都是由 @conditional 派生出来的组合注解。

几个常见的条件注解：

注解	作用	位置
`@conditionalonclass`	当 classpath 存在指定类时生效	类或方法
`@conditionalonmissingbean`	当容器中没有指定类型的 bean 时生效	方法
`@conditionalonproperty`	当配置属性匹配时生效	类或方法
`@conditionalonexpression`	根据 spel 表达式结果生效	类或方法

这些注解为什么重要？因为自动配置类往往放在一个大的配置类中，如果无条件控制，那么启动一个非 web 应用也会装上 web 相关的 bean，导致冲突或浪费。spring boot 通过条件让每个自动配置只在合适的情况下入手。

来看几个源码入口（节选）：

// 源码节选：@conditionalonproperty
@target({ elementtype.type, elementtype.method })
@retention(retentionpolicy.runtime)
@documented
@conditional(onpropertycondition.class)
public @interface conditionalonproperty {
    string prefix() default "";
    string name() default "";
    string havingvalue() default "";
    boolean matchifmissing() default false;
}

正是因为 onpropertycondition 内部实现了条件逻辑，用户只需写明属性名和期望值。

示例三：模拟 spring boot 自动配置，通过条件控制独立 sdk 是否加载

目标：模拟一个支付 sdk 仅在存在 api key 时才自动创建客户端。这与 spring boot 自动配置的思维一致。

背景：我们有一个第三方支付库，他的客户端对象只有当你提供 pay.api-key 属性才能初始化。

步骤：创建 maven 工程，加入 spring boot starter。我们不需要真的引入支付 sdk，而是创建一个模拟类。

首先定义接口和模拟客户端：

public interface paymentclient {
    void pay(double amount);
}
public class mockpaymentclient implements paymentclient {
    private string apikey;
    public mockpaymentclient(string apikey) { this.apikey = apikey; }
    @override public void pay(double amount) {
        system.out.println("使用 api key " + apikey + " 支付 " + amount);
    }
}

自动配置类（模仿真正的自动配置）：

import org.springframework.boot.autoconfigure.condition.conditionalonclass;
import org.springframework.boot.autoconfigure.condition.conditionalonmissingbean;
import org.springframework.boot.autoconfigure.condition.conditionalonproperty;
import org.springframework.context.annotation.bean;
import org.springframework.context.annotation.configuration;
@configuration
@conditionalonclass(paymentclient.class)
public class paymentautoconfiguration {
    @bean
    @conditionalonmissingbean
    @conditionalonproperty(prefix = "pay", name = "api-key")
    public paymentclient paymentclient() {
        return new mockpaymentclient(environment.getproperty("pay.api-key"));
    }
}

这里 environment 可通过构造器注入，但为了简化，我们直接这样写（实际要注入）：

@configuration
public class paymentautoconfiguration {
    @bean
    @conditionalonmissingbean
    @conditionalonproperty(prefix = "pay", name = "api-key")
    public paymentclient paymentclient(@value("${pay.api-key}") string apikey) {
        return new mockpaymentclient(apikey);
    }
}

在实际工程中，你需要用 @configuration 注册该类到自动配置列表。这里简单用 @import 演示：

主应用：

@springbootapplication
@import(paymentautoconfiguration.class)
public class paymentapp {
    @autowired(required = false)
    private paymentclient paymentclient;
    public static void main(string[] args) {
        configurableapplicationcontext ctx = springapplication.run(paymentapp.class);
        paymentapp app = ctx.getbean(paymentapp.class);
        if (app.paymentclient != null) {
            app.paymentclient.pay(100.0);
        } else {
            system.out.println("支付客户端未配置");
        }
        ctx.close();
    }
}

在 application.properties 中设置：

pay.api-key=sk_test_123

运行：启动后输出“使用 api key sk_test_123 支付 100.0”。删除该属性，则输出“支付客户端未配置”。

说明：这里展示了自动配置的典型模式：先用 @conditionalonclass 判断基础库存在，再用 @conditionalonproperty 判断配置项，再用 @conditionalonmissingbean 允许用户覆盖。这个过程对 jar 是否在 classpath 的评估发生在类加载时，顺序为系统条件 > 自定义条件。

6 条件求值的内部机制与顺序

spring 容器处理条件时，有多种模式：configurationcondition 可以控制是 parse_configuration（解析类定义时）还是 register_bean（注册 bean 定义时）阶段。spring boot 也引入 autoconfigurationimportfilter 和 autoconfigurationimportselector 提前过滤一部分自动配置类。

一般我们不需要关心太底层，但要掌握求值顺序对结果的影响：

[解析配置类] -> 判断配置类上的 @profile/@conditional
    -> 如果类被跳过，整个配置类不处理
    -> 如果类保留，再解析每个 @bean/@import 上的条件
    -> 注册 beandefinition
    -> 实例化前，如果方法级条件为 false，则跳过该 bean

条件求值是一个“短路”过程，一旦发现不匹配，就不再继续检查后面的条件。这能帮助避免创建不必要的依赖。

7 常见误区与边界

误区一：认为 @profile 和 @conditional 可以互相替代。

实际上 @profile 只能基于环境，而 @conditional 更为通用。spring 内部也把 @profile 变成一个条件。

误区二：在条件里注入 bean 或依赖。

条件在 bean 定义阶段运行，此时很多 bean 还未创建，因此你不能在 matches() 方法中通过 context.getbeanfactory().getbean() 获取业务 bean，一般只能读取元数据、环境或类加载器。

误区三：条件能操作运行时动态变化。

条件只在启动时评估一次，如果配置文件后改，不会生效。

误区四：忽略 matchifmissing。

这个选项决定属性未提供时的默认行为，很多异常就是因为没有设置它而产生。

8 生产实践建议

在大型项目中，优先使用 spring boot 的组合条件注解，而不是直接使用 @conditional，代码更清晰。
自定义条件时放入单独的包，便于测试。
条件逻辑要保持纯函数，不要有副作用。
组合条件时，要小心求值顺序，尽量用 @conditionalonmissingbean 放在最后。
多环境配置建议用 application-{profile}.properties 加上 @profile，通用条件用 @conditionalonproperty 控制功能开关。

9 排障清单

启动报错“no qualifying bean of type”可能是因为条件不满足。常见排查步骤：

先确认 spring.profiles.active 已设置。
检查 @conditional 的 condition 类是否被正确扫描。
若使用环境变量，检查大小写和是否传入了 boolean.parseboolean。
查看启动日志中的“conditionevaluationreport”，它能列出每个条件是否匹配。开启 debug 日志：debug=true。

10 面试/复盘问题

@profile 的实现原理是什么？它和 @conditional 有什么关系？
自定义一个条件来处理多环境或功能开关。
spring boot 的自动配置是如何依赖条件实现的？
条件求值发生在什么阶段？这有什么限制？
如何在运行时动态改变条件？如果真有必要怎么做？

11 总结：条件装配演进脉络

从最开始的配置文件切换，到 @profile 按环境选择，再到 @conditional 实现任意条件，最后 spring boot 自动配置将条件组合成百宝箱。

下面对比表可以帮助你决策：

方案	表达力	适用场景	缺点
多配置文件	低	简单静态划分	易错，需手工切换
@profile	中	环境分组	只有环境维度
@conditional	高	任意条件下按需装配	代码量大，需自己实现 condition
boot 条件注解	很高	自动配置与功能开关	依赖 boot，不易移植

回顾最开始的数据源切换：现在只需设置一个环境变量 spring_profiles_active=dev，就能让容器选择正确的 bean，而无需修改代码或打包多个 jar。

如果遇到更复杂的场景，比如“当 redis 在 classpath 且配置了 host 时才创建缓存”，你可以毫不犹豫地使用 @conditionalonclass 和 @conditionalonproperty。

记住核心模型：先判断，后装配。

参考资料

spring framework 官方文档: core features – profiles (docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-definition-profiles)
spring framework javadoc: @conditional, condition, conditioncontext (docs.spring.io/spring-framework/docs/current/javadoc-api/)
spring boot 官方文档: auto-configuration (docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.developing-auto-configuration)

到此这篇关于spring 条件装配演进之路：从配置文件到 @conditional 体系的文章就介绍到这了,更多相关spring 条件装配@conditional内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！