跳到主要内容

属性与配置

DeepSeek V3 中英对照 Properties and Configuration

属性与配置​

本节包含有关设置和读取属性与配置设置及其与 Spring Boot 应用程序交互的主题。

在构建时自动扩展属性​

与其硬编码一些已经在项目构建配置中指定的属性，不如通过使用现有的构建配置来自动扩展它们。这在 Maven 和 Gradle 中都是可行的。

使用 Maven 自动扩展属性​

你可以通过使用资源过滤来自动扩展 Maven 项目中的属性。如果你使用了 spring-boot-starter-parent，那么你可以使用 @..@ 占位符来引用你的 Maven "项目属性"，如下例所示：

app.encoding=@project.build.sourceEncoding@
app.java.version=@java.version@
properties
备注

仅生产配置会以这种方式进行过滤（换句话说，不会对 src/test/resources 进行过滤）。

提示

如果启用了 addResources 标志，spring-boot:run 目标可以直接将 src/main/resources 添加到类路径中（用于热重载目的）。这样做会绕过资源过滤和此功能。相反，您可以使用 exec:java 目标或自定义插件的配置。更多详细信息请参阅插件使用页面。

如果你不使用 starter parent，你需要在 pom.xml 的 <build/> 元素中包含以下内容：

<resources>
    <resource>
        <directory>src/main/resources</directory>
        <filtering>true</filtering>
    </resource>
</resources>
xml

你还需要在 <plugins/> 中包含以下元素：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <version>2.7</version>
    <configuration>
        <delimiters>
            <delimiter>@</delimiter>
        </delimiters>
        <useDefaultDelimiters>false</useDefaultDelimiters>
    </configuration>
</plugin>
xml
备注

如果您的配置中使用了标准的 Spring 占位符（例如 ${placeholder}），那么 useDefaultDelimiters 属性非常重要。如果该属性未设置为 false，这些占位符可能会在构建过程中被展开。

使用 Gradle 自动扩展属性​

你可以通过配置 Java 插件的 processResources 任务来自动扩展 Gradle 项目的属性，如下例所示：

tasks.named('processResources') {
    expand(project.properties)
}
gradle

然后，你可以通过使用占位符来引用你的 Gradle 项目的属性，如下例所示：

app.name=${name}
app.description=${description}
properties
备注

Gradle 的 expand 方法使用了 Groovy 的 SimpleTemplateEngine，它会转换 ${..} 标记。${..} 这种风格与 Spring 自身的属性占位符机制存在冲突。为了在使用自动扩展的同时使用 Spring 属性占位符，可以按如下方式对 Spring 属性占位符进行转义：\${..}。

外部化 SpringApplication 的配置​

SpringApplication 提供了 bean 属性的 setter 方法，因此你可以在创建应用程序时使用其 Java API 来修改其行为。或者，你也可以通过在 spring.main.* 中设置属性来将配置外部化。例如，在 application.properties 中，你可能会看到以下设置：

spring.main.web-application-type=none
spring.main.banner-mode=off
properties

然后，Spring Boot 启动时的横幅不会打印，并且应用程序不会启动嵌入式 Web 服务器。

在外部配置中定义的属性会覆盖并替换通过 Java API 指定的值，但有一个显著的例外，即主要来源。主要来源是指提供给 SpringApplication 构造函数的那些配置：

import org.springframework.boot.Banner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication application = new SpringApplication(MyApplication.class);
        application.setBannerMode(Banner.Mode.OFF);
        application.run(args);
    }

}
java

或者使用 SpringApplicationBuilder 的 sources(…​) 方法：

import org.springframework.boot.Banner;
import org.springframework.boot.builder.SpringApplicationBuilder;

public class MyApplication {

    public static void main(String[] args) {
        new SpringApplicationBuilder()
            .bannerMode(Banner.Mode.OFF)
            .sources(MyApplication.class)
            .run(args);
    }

}
java

根据上面的示例，如果我们有以下配置：

spring.main.sources=com.example.MyDatabaseConfig,com.example.MyJmsConfig
spring.main.banner-mode=console
properties

实际应用将显示横幅（根据配置覆盖），并使用三个来源的 ApplicationContext。应用的来源包括：

  1. MyApplication（来自代码）

  2. MyDatabaseConfig（来自外部配置）

  3. MyJmsConfig（来自外部配置）

更改应用程序外部属性的位置​

默认情况下，来自不同源的属性会按照定义的顺序添加到 Spring Environment 中（有关确切的顺序，请参阅“Spring Boot Features”部分中的外部化配置）。

你还可以提供以下系统属性（或环境变量）来改变其行为：

  • spring.config.name (SPRING_CONFIG_NAME): 默认值为 application，作为文件名的根。

  • spring.config.location (SPRING_CONFIG_LOCATION): 要加载的文件（例如类路径资源或 URL）。为此文档设置了一个单独的 Environment 属性源，并且它可以通过系统属性、环境变量或命令行进行覆盖。

无论你在环境中设置了什么，Spring Boot 都会按照上述描述加载 application.properties。默认情况下，如果使用了 YAML，那么扩展名为 .yaml 和 .yml 的文件也会被添加到列表中。

提示

如果你想了解正在加载文件的详细信息，可以将 org.springframework.boot.context.config 的日志级别设置为 trace。

使用‘Short’命令行参数​

有些人喜欢使用（例如）--port=9000 而不是 --server.port=9000 来在命令行中设置配置属性。你可以通过在 application.properties 中使用占位符来启用这种行为，如下例所示：

server.port=${port:8080}
properties
提示

如果你继承了 spring-boot-starter-parent POM，maven-resources-plugins 的默认过滤标记已从 ${*} 更改为 @（即 @maven.token@ 而不是 ${maven.token}），以防止与 Spring 风格的占位符发生冲突。如果你直接为 application.properties 启用了 Maven 过滤，你可能还需要将默认的过滤标记更改为使用其他分隔符。

备注

在这种特定情况下，端口绑定适用于 PaaS 环境，例如 Heroku 或 Cloud Foundry。在这两个平台上，PORT 环境变量会自动设置，并且 Spring 可以绑定到 Environment 属性的大写同义词。

使用 YAML 作为外部属性​

YAML 是 JSON 的超集，因此它是一种便捷的语法，用于以层次结构格式存储外部属性，如下例所示：

spring:
  application:
    name: "cruncher"
  datasource:
    driver-class-name: "com.mysql.jdbc.Driver"
    url: "jdbc:mysql://localhost/test"
server:
  port: 9000
yaml

创建一个名为 application.yaml 的文件并将其放在类路径的根目录下。然后将 snakeyaml 添加到你的依赖中（Maven 坐标为 org.yaml:snakeyaml，如果你使用 spring-boot-starter，则已经包含）。YAML 文件会被解析为一个 Java Map<String,Object>（类似于 JSON 对象），Spring Boot 会将其展平，使其变为一层深度，并使用点号分隔的键，就像许多人在 Java 中使用 Properties 文件时所习惯的那样。

前面的 YAML 示例对应于以下 application.properties 文件：

spring.application.name=cruncher
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://localhost/test
server.port=9000
properties

有关 YAML 的更多信息，请参阅 使用 YAML 在“Spring Boot 特性”部分中的内容。

设置激活的 Spring Profiles​

Spring 的 Environment 提供了相应的 API，但你通常可以设置一个系统属性（spring.profiles.active）或一个操作系统环境变量（SPRING_PROFILES_ACTIVE）。此外，你还可以使用 -D 参数启动你的应用程序（记得将其放在主类或 jar 文件之前），如下所示：

$ java -jar -Dspring.profiles.active=production demo-0.0.1-SNAPSHOT.jar
shell

在 Spring Boot 中，你也可以在 application.properties 中设置激活的配置文件，如下例所示：

spring.profiles.active=production
properties

以这种方式设置的值会被系统属性或环境变量设置所替换，但不会被 SpringApplicationBuilder.profiles() 方法替换。因此，可以使用后者的 Java API 来增强 profiles 而不会更改默认值。

有关更多信息，请参阅 Profiles 中的“Spring Boot 特性”部分。

设置默认的配置文件名称​

默认配置文件是在没有激活任何配置文件时启用的配置文件。默认情况下，默认配置文件的名称是 default，但可以通过系统属性（spring.profiles.default）或操作系统环境变量（SPRING_PROFILES_DEFAULT）来更改。

在 Spring Boot 中，你也可以在 application.properties 中设置默认的配置文件名称，如下例所示：

spring.profiles.default=dev
properties

更多信息请参阅“Spring Boot 特性”部分中的Profiles。

根据环境更改配置​

Spring Boot 支持多文档的 YAML 和 Properties 文件（详见 使用多文档文件），这些文件可以根据激活的配置文件进行条件激活。

如果文档中包含 spring.config.activate.on-profile 键，那么 profiles 值（一个以逗号分隔的 profiles 列表或一个 profile 表达式）会被传递给 Spring 的 Environment.acceptsProfiles() 方法。如果 profile 表达式匹配，则该文档会被包含在最终的合并中（否则，不会被包含），如下例所示：

server.port=9000
#---
spring.config.activate.on-profile=development
server.port=9001
#---
spring.config.activate.on-profile=production
server.port=0
properties

在前面的示例中，默认端口为 9000。然而，如果名为 development 的 Spring 配置文件处于激活状态，则端口为 9001。如果 production 处于激活状态，则端口为 0。

备注

文档按照它们被遇到的顺序进行合并。后面的值会覆盖前面的值。

发现外部属性的内置选项​

Spring Boot 在运行时将外部属性从 application.properties（或 YAML 文件和其他位置）绑定到应用程序中。在单个位置中无法（技术上也不可能）列出所有支持的属性的详尽列表，因为贡献可能来自类路径上的其他 jar 文件。

一个启用了 Actuator 功能的运行中的应用程序拥有一个 configprops 端点，该端点展示了通过 @ConfigurationProperties 所有已绑定和可绑定的属性。

附录中包含了一个 application.properties 示例，列出了 Spring Boot 支持的最常见属性。完整的属性列表是通过搜索源代码中的 @ConfigurationProperties 和 @Value 注解以及偶尔使用的 Binder 获得的。有关加载属性的确切顺序的更多信息，请参阅 外部化配置。