注:本系列教程花了三个星期的业余时间来翻译,虽然尽心尽力,但水平有限,难免有失误或表达不太好,请尽力地骂,骂完,可以打赏安慰我,我才有动力改。
源文档地址:https://docs.spring.io/spring-boot/docs/2.2.x/reference/html/howto.html#howto
2. Properties and Configuration 属性和配置
本节包括有关设置和读取属性、配置设置及其与Springboot 的交互的主题。
2.1. 在生成时自动设置属性
与其硬编码项目时指定的一些属性,还不如使用现有的生成配置自动设置它们。通过Maven和Gradle都是可以的。
2.1.1. 使用maven自动扩展属性
通过使用资源筛选,可以从Maven项目自动展开属性。如果使用spring-boot-starter-parent
,则可以使用@..@占位符引用Maven的“project properties
”,如下例所示:
app.encoding=@project.build.sourceEncoding@
app.java.version=@java.version@
只有生产环境配置用这种方式进行过滤(换句话说,src/test/resources
环境上不应用任何过滤)。
如果启用addResources标志,spring-boot:run
目标可以直接将src/main/resources
添加到类路径中(用于热重载目的)。这样做可以绕过资源过滤和这个特性。相反,您可以使用 exec:java目标或自定义插件的配置。有关详细信息,请参阅plugin usage page 。
如果不使用starter父级,则需要在pom.xml
的 <build/>
元素中包含以下元素:
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
</resource>
</resources>
您还需要在
<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>
如果在配置中使用标准Spring占位符(如${placeholder}
),则useDefaultDelimiters
属性非常重要。如果该属性未设置为false,则可以通过生成扩展这些属性。
2.1.2. 使用Gradle自动扩展属性(和maven类似,有空再翻译)
You can automatically expand properties from the Gradle project by configuring the Java plugin’s processResources task to do so, as shown in the following example:
processResources {
expand(project.properties)
}
You can then refer to your Gradle project’s properties by using placeholders, as shown in the following example:
app.name=${name}
app.description=${description}
Gradle’s expand method uses Groovy’s SimpleTemplateEngine, which transforms ${..} tokens. The ${..} style conflicts with Spring’s own property placeholder mechanism. To use Spring property placeholders together with automatic expansion, escape the Spring property placeholders as follows: \${..}.
2.2. SpringApplication的外部配置
一个SpringApplication应用程序具有Bean属性(主要是setters),因此您可以在创建应用程序时使用Java API来修改其行为。或者,您可以通过在spring.main.*
中设置属性从外部配置。例如,在application.properties
中,您可能具有以下设置:
spring.main.web-application-type=none
spring.main.banner-mode=off
这样,启动时不会打印Spring引导banner,应用程序也不会启动嵌入式Web服务器。
在外部配置中定义的属性重写了用Java API指定的值,除了用于创建applicationContext
的源之外,还有一个值得注意的例外。考虑以下应用程序:
new SpringApplicationBuilder()
.bannerMode(Banner.Mode.OFF)
.sources(demo.MyApp.class)
.run(args);
现在看一下以下配置:
spring.main.sources=com.acme.Config,com.acme.ExtraConfig
spring.main.banner-mode=console
现在实际应用程序显示 banner(被配置覆盖),并使用ApplicationContext的三个源(顺序如下): demo.MyApp, com.acme.Config
, 和com.acme.ExtraConfig
.
2.3. 修改外面配置的路径
默认情况下,来自不同源的属性按定义的顺序添加到Spring环境中(有关确切顺序,请参阅“spring-boot-features.html” 部分中的“Spring Boot Features.html”)。
增加和修改此顺序的一个好方法是向应用程序添加@PropertySource
注释。检查传递给SpringApplication静态方法的类以及使用setSources()
添加的类,以查看它们是否具有@PropertySources。如果是这样的话,这些属性会尽早添加到环境中,以便在应用程序上下文生命周期的所有阶段中使用。以这种方式添加的属性的优先级低于使用默认位置(如application.properties
)、系统属性、环境变量或命令行添加的任何属性。
您还可以提供以下系统属性(或环境变量)来更改行为:
spring.config.name (SPRING_CONFIG_NAME)
: 默认为应用程序作为文件名的根。
spring.config.location (SPRING_CONFIG_LOCATION)
: 要加载的文件(例如类路径资源或URL)。为此文档设置了单独的环境属性源,它可以被系统属性、环境变量或命令行覆盖。
不管您在环境中设置了什么,SpringBoot总是按照上面的描述加载application.properties
。默认情况下,如果使用yaml,则扩展名为“.yml”的文件也会添加到列表中。
Spring Boot会记录在调试级别加载的配置文件以及在跟踪级别未找到的候选文件。
查看 ConfigFileApplicationListener
获得更多信息
2.4.在命令行参数用短命令
有些人喜欢使用(例如)--port=9000
而不是--server.port=9000
在命令行上设置配置属性。可以通过在application.properties
中使用占位符来启用此行为,如下例所示:
server.port=${port:8080}
如果继承自spring-boot-starter-parent
POM,则maven-resources-plugin
s 的默认筛选标记已从${*}
改为@
(即,@maven.token@
而不是${maven.token}
),以防止与Spring-style的占位符发生冲突。如果已直接为application.properties
启用了maven筛选,则可能还需要更改默认筛选标记以使用其他分隔符。
在这种特定的情况下,像Heroku或CloudFoundry这样的PaaS环境中需要端口绑定。在这两个平台中,port环境变量是自动设置的,spring可以绑定到环境属性的大写同义词。
2.5.使用 YAML文件做为外部属性
yaml是json的超集,因此是以分层格式存储外部属性的方便语法,如下例所示:
spring:
application:
name: cruncher
datasource:
driverClassName: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost/test
server:
port: 9000
创建一个名为application.yml
的文件,并将其放到类路径的根目录中。然后将snakeyaml添加到您的依赖项中(maven org.yaml:snakeyaml
,如果您使用Springboot启动程序,就已经包含在内)。YAML文件被解析为Java Map<String,Object>
(像JSON对象),Spring Boot做映射,使其为一个级别深且具有独立的键,像许多人习惯的Java中的属性文件。
前面的示例yaml对应于以下application.properties
文件:
spring.application.name=cruncher
spring.datasource.driverClassName=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://localhost/test
server.port=9000
查看 “spring-boot-features.html” in ‘Spring Boot features’获得更多YAML的信息
2.6. 设置活动Spring配置文件
Spring环境对此有一个API,但是您通常会设置一个系统属性(spring.profiles.active
)或一个OS环境变量(spring_profiles_active
)。此外,还可以使用-d参数启动应用程序(记住要将其放在主类或JAR存档之前),如下所示:
$ java -jar -Dspring.profiles.active=production demo-0.0.1-SNAPSHOT.jar
在Springboot中,还可以在application.properties
中设置活动配置文件,如下例所示:
spring.profiles.active=production
以这种方式设置的值被系统属性或环境变量设置替换,但不被springApplicationBuilder.profiles()
方法替换。因此,后一个Java API可以用来增加配置文件而不改变默认值。
查看 “spring-boot-features.html”“Spring Boot features” 获得更多的信息
2.7. 根据环境更改配置
yaml文件实际上是由---行分隔的文档序列,每个文档都被单独解析为的平滑映射。
如果yaml文档包含 spring.profiles
键,那么profiles值(以逗号分隔的profiles列表)将被送入spring Environment.acceptsProfiles()
方法。如果这些配置文件中的任何一个处于活动状态,则该文档将包含在最终合并中(否则,它将不包含在内),如下例所示:
server:
port: 9000
---
spring:
profiles: development
server:
port: 9001
---
spring:
profiles: production
server:
port: 0
在前面的示例中,默认端口为9000。但是,如果称为“development”的Spring配置文件处于活动状态,则端口为9001。如果“production”处于活动状态,则端口为0。
yaml文档按遇到它们的顺序合并。后面的值会覆盖前面的值。
要对属性文件执行相同的操作,可以使用应用程序-$profile.properties
指定特定于配置文件的值。
2.8. 发现外部属性的内置选项
Springboot在运行时将application.properties
(或.yml文件和其他位置)的外部属性绑定到应用程序中。在一个位置上没有(技术上也不可能)所有受支持属性的详尽列表,因为这些属性可以来自类路径上的其他JAR文件。
一个具有执行器功能的正在运行的应用程序具有configprops端点,该端点显示通过@configurationproperties可用的所有绑定和可绑定属性。
附录包括application.properties
示例,其中列出了SpringBoot支持的最常见的属性。最终列表来自于在源代码中搜索@ConfigurationProperties
和@Value注释以及偶尔使用binder。有关加载属性的确切顺序的详细信息,请参阅"spring-boot-features.html"。