17.2 多环境配置与 Profile 机制

实际项目从开发到上线，至少会经历开发（dev）、测试（test）、预发布（staging）、生产（prod）等多个环境。各环境的数据库连接、缓存地址、外部服务密钥等配置必然不同。Spring 提供的 Profile 机制 正是为解决“一套代码，多套配置”的问题而设计的，它允许你为不同环境定义独立的配置，并在启动时动态切换。

17.2.1 Profile 的核心概念

Profile 本质上是一个 逻辑分组标签。你可以将某些 Bean 或整个配置文件标记为属于特定的 Profile，Spring 容器在启动时只会加载那些与当前激活的 Profile 匹配的组件和配置。未激活的 Profile 所对应的 Bean 不会被实例化，对应的配置文件也不会被加载。

这种机制带来的直接好处是：

• 配置隔离：生产环境的数据库密码不会出现在开发配置中。
• 按需加载：避免加载无关环境的组件，比如开发时不需要的消息队列消费者。
• 一键切换：仅需一个参数即可切换整套运行环境。

17.2.2 定义 Profile 配置的几种方式

Spring Boot 提供了多种方式来组织与 Profile 相关的配置，最常用的是 多环境配置文件 和 代码中的 @Profile 注解。

1. 使用 application-{profile}.properties / .yml

这是最简单、最推荐的方式。你可以在 src/main/resources 下创建多个配置文件，格式为 application-{profile}.properties 或 application-{profile}.yml。Spring Boot 会先加载 application.properties（公共配置），再加载与激活 Profile 对应的文件，后者中的属性会覆盖前者中的同名属性。

示例：三个环境的配置

application.yml（公共配置 + 默认值）：

spring:
  application:
    name: order-service
server:
  port: 8080

application-dev.yml（开发环境）：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/order_dev
    username: dev_user
    password: dev_pass
  redis:
    host: localhost
logging:
  level:
    com.example: DEBUG

application-prod.yml（生产环境）：

spring:
  datasource:
    url: jdbc:mysql://prod-db.example.com:3306/order_prod
    username: prod_user
    password: ${DB_PASSWORD}   # 敏感信息从环境变量注入
  redis:
    host: redis-cluster.prod.internal
logging:
  level:
    com.example: WARN

在这种结构下，所有环境共享的配置放在 application.yml 中，差异化的配置放在各自的 -{profile} 文件中。切换环境时只需改变激活的 Profile，无需修改任何文件。

2. 使用 @Profile 注解限定 Bean

有时不仅仅是配置不同，连 Bean 的实现或存在性也需要根据环境变化。例如，开发环境使用一个打印日志的通知服务，而生产环境要真正发送短信。此时可以使用 @Profile 注解：

@Service
@Profile("dev")
public class ConsoleNotificationService implements NotificationService {
    @Override
    public void send(String message) {
        System.out.println("DEV 通知: " + message);
    }
}

@Service
@Profile("prod")
public class SmsNotificationService implements NotificationService {
    @Override
    public void send(String message) {
        // 调用第三方短信接口
    }
}

Spring 容器会根据激活的 Profile 决定实例化哪一个实现。同一个接口在不同环境下有不同实现，业务代码无须做任何判断。

@Profile 也可以用在配置类上，控制整个配置类的加载：

@Configuration
@Profile("dev")
public class DevDataInitConfig {
    @Bean
    public CommandLineRunner initDevData(UserRepository repo) {
        return args -> {
            // 开发环境初始化一些测试数据
        };
    }
}

3. 在单个 YAML 文件中使用多文档分隔

如果项目较小，不想创建多个文件，也可以在单个 application.yml 中使用 --- 分隔符定义多个文档，并为每个文档指定 spring.config.activate.on-profile：

# 公共配置
server:
  port: 8080

---
# 开发环境
spring:
  config:
    activate:
      on-profile: dev
  datasource:
    url: jdbc:mysql://localhost:3306/dev_db

---
# 生产环境
spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: jdbc:mysql://prod-db.example.com:3306/prod_db

这种方式将所有配置集中在一个文件中，但不易于维护，推荐仅在配置项很少时使用。

17.2.3 激活 Profile 的方法

有几种方式告诉 Spring 应当激活哪些 Profile，优先级从低到高如下：

1. 在 application.properties 中设置（低优先级）

spring.profiles.active=dev

这种方式的缺点在于写死在配置文件中，每次切换需要修改文件重新打包。通常仅用于设置默认值。

2. 通过命令行参数

java -jar order-service.jar --spring.profiles.active=prod

这是部署时最常用的方式，打包好的 jar 包无需修改，通过启动参数即可切换。

3. 通过环境变量

export SPRING_PROFILES_ACTIVE=prod
java -jar order-service.jar

在 Docker 或 Kubernetes 等容器化环境中，通过环境变量注入配置是最标准、最安全的实践。

4. 在 IDE 中设置

开发调试时，可以直接在 IDE 的运行配置中指定 spring.profiles.active=dev，无需每次手动输入。

5. 编程方式（较少使用）

在 SpringApplication.run() 之前设置：

public static void main(String[] args) {
    SpringApplication app = new SpringApplication(MyApplication.class);
    app.setAdditionalProfiles("dev");
    app.run(args);
}

实际使用中，环境变量 + 命令行参数 是主流方案，既能保证灵活性，又可避免将敏感 Profile 信息提交到代码仓库。

17.2.4 默认 Profile 与多 Profile 组合

如果应用启动时没有显式指定 spring.profiles.active，Spring 将不会激活任何额外的 Profile，仅加载 application.properties / .yml 中的公共配置。你也可以通过 spring.profiles.default 指定一个后备值：

spring.profiles.default=dev

当外部未指定 active 时，default 将生效。这适合本地开发场景——无需任何额外参数即可启动。

Spring 也支持同时激活多个 Profile，例如：

--spring.profiles.active=dev,local

多个 Profile 用逗号分隔。此时，容器会加载所有匹配的配置，后面的配置会覆盖前面的同名属性。这种组合方式可以构建更灵活的配置层次，比如 dev 提供开发环境基础配置，local 可叠加一些个人本地偏好（如端口、日志级别）。

17.2.5 结合配置中心的动态 Profile 切换

在微服务架构中，多环境配置往往与配置中心（Nacos、Apollo、Spring Cloud Config 等）结合使用。例如，将各环境的配置托管在 Nacos 中，通过 spring.cloud.nacos.config 的相关属性指定 namespace 或 group，而这些属性本身可以通过 Profile 区分：

application-dev.yml：

spring:
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        namespace: dev-namespace-id
        group: DEFAULT_GROUP

application-prod.yml：

spring:
  cloud:
    nacos:
      config:
        server-addr: nacos-prod.example.com:8848
        namespace: prod-namespace-id
        group: DEFAULT_GROUP

这样，当激活 dev Profile 时，应用会自动连接到开发环境的 Nacos 并拉取对应命名空间下的配置；激活 prod 时则切换到生产环境的配置中心。整个过程由 Profile 驱动，无需手动修改代码。

17.2.6 实用建议与避坑指南

• 敏感信息不入库：生产环境的数据库密码、API 密钥等不应直接写在 application-prod.yml 中并提交到 Git。应该通过环境变量、Kubernetes Secret 或配置中心的加密功能注入，然后使用 ${DB_PASSWORD} 占位符引用。
• Profile 命名规范：团队内约定统一的命名，如 dev、test、staging、prod，避免出现 dev1、my-test 等随意命名。
• 尽量使用 YAML 的多文件模式：与 --- 单文件多文档相比，application-{profile}.yml 更清晰，便于维护和版本对比。
• 测试验证：在 CI/CD 管道中对每个环境的构建包进行验证，确保 Profile 切换生效。可在测试阶段通过 @ActiveProfiles("test") 指定测试专用 Profile。
• 避免 Bean 意外缺失：当使用 @Profile 限定 Bean 时，确保在其他环境下有替代实现或通过 @ConditionalOnMissingBean 提供回退策略，否则容器启动时可能因缺少依赖而失败。

通过 Profile 机制，Spring 给予了开发团队在多环境间平滑切换的能力。只需一个简单的激活参数，就能让同一份部署包运行在完全不同的基础设施之上，这是现代持续交付流水线中不可或缺的一环。