Externalized Configuration (Externalized Configuration) _ Spring Boot3.4.0-SNAPSHOT中文文档(官方文档中文翻译)|Spring 教程 —

This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Boot 3.3.4!spring-doc.cn

Spring Boot lets you externalize your configuration so that you can work with the same application code in different environments. You can use a variety of external configuration sources including Java properties files, YAML files, environment variables, and command-line arguments.spring-doc.cn

Property values can be injected directly into your beans by using the @Value annotation, accessed through Spring’s Environment abstraction, or be bound to structured objects through @ConfigurationProperties.spring-doc.cn

Spring Boot uses a very particular PropertySource order that is designed to allow sensible overriding of values. Later property sources can override the values defined in earlier ones. Sources are considered in the following order:spring-doc.cn

Default properties (specified by setting SpringApplication.setDefaultProperties).spring-doc.cn
@PropertySource annotations on your @Configuration classes. Please note that such property sources are not added to the Environment until the application context is being refreshed. This is too late to configure certain properties such as logging.* and spring.main.* which are read before refresh begins.spring-doc.cn
Config data (such as application.properties files).spring-doc.cn
A RandomValuePropertySource that has properties only in random.*.spring-doc.cn
OS environment variables.spring-doc.cn
Java System properties (System.getProperties()).spring-doc.cn
JNDI attributes from java:comp/env.spring-doc.cn
ServletContext init parameters.spring-doc.cn
ServletConfig init parameters.spring-doc.cn
Properties from SPRING_APPLICATION_JSON (inline JSON embedded in an environment variable or system property).spring-doc.cn
Command line arguments.spring-doc.cn
properties attribute on your tests. Available on @SpringBootTest and the test annotations for testing a particular slice of your application.spring-doc.cn
@DynamicPropertySource annotations in your tests.spring-doc.cn
@TestPropertySource annotations on your tests.spring-doc.cn
Devtools global settings properties in the $HOME/.config/spring-boot directory when devtools is active.spring-doc.cn

Config data files are considered in the following order:spring-doc.cn

Application properties packaged inside your jar (application.properties and YAML variants).spring-doc.cn
Profile-specific application properties packaged inside your jar (application-{profile}.properties and YAML variants).spring-doc.cn
Application properties outside of your packaged jar (application.properties and YAML variants).spring-doc.cn
Profile-specific application properties outside of your packaged jar (application-{profile}.properties and YAML variants).spring-doc.cn

It is recommended to stick with one format for your entire application. If you have configuration files with both .properties and YAML format in the same location, .properties takes precedence.

If you use environment variables rather than system properties, most operating systems disallow period-separated key names, but you can use underscores instead (for example, SPRING_CONFIG_NAME instead of spring.config.name). See Binding From Environment Variables for details.

If your application runs in a servlet container or application server, then JNDI properties (in java:comp/env) or servlet context initialization parameters can be used instead of, or as well as, environment variables or system properties.

To provide a concrete example, suppose you develop a @Component that uses a name property, as shown in the following example:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

	@Value("${name}")
	private String name;

	// ...

}

import org.springframework.beans.factory.annotation.Value
import org.springframework.stereotype.Component

@Component
class MyBean {

	@Value("\${name}")
	private val name: String? = null

	// ...

}

On your application classpath (for example, inside your jar) you can have an application.properties file that provides a sensible default property value for name. When running in a new environment, an application.properties file can be provided outside of your jar that overrides the name. For one-off testing, you can launch with a specific command line switch (for example, java -jar app.jar --name="Spring").spring-doc.cn

The env and configprops endpoints can be useful in determining why a property has a particular value. You can use these two endpoints to diagnose unexpected property values. See the Production ready features section for details.

It is recommended to stick with one format for your entire application. If you have configuration files with both .properties and YAML format in the same location, .properties takes precedence.

Accessing Command Line Properties

By default, SpringApplication converts any command line option arguments (that is, arguments starting with --, such as --server.port=9000) to a property and adds them to the Spring Environment. As mentioned previously, command line properties always take precedence over file-based property sources.spring-doc.cn

If you do not want command line properties to be added to the Environment, you can disable them by using SpringApplication.setAddCommandLineProperties(false).spring-doc.cn

JSON Application Properties

Environment variables and system properties often have restrictions that mean some property names cannot be used. To help with this, Spring Boot allows you to encode a block of properties into a single JSON structure.spring-doc.cn

When your application starts, any spring.application.json or SPRING_APPLICATION_JSON properties will be parsed and added to the Environment.spring-doc.cn

For example, the SPRING_APPLICATION_JSON property can be supplied on the command line in a UN*X shell as an environment variable:spring-doc.cn

$ SPRING_APPLICATION_JSON='{"my":{"name":"test"}}' java -jar myapp.jar

In the preceding example, you end up with my.name=test in the Spring Environment.spring-doc.cn

The same JSON can also be provided as a system property:spring-doc.cn

$ java -Dspring.application.json='{"my":{"name":"test"}}' -jar myapp.jar

Or you could supply the JSON by using a command line argument:spring-doc.cn

$ java -jar myapp.jar --spring.application.json='{"my":{"name":"test"}}'

If you are deploying to a classic Application Server, you could also use a JNDI variable named java:comp/env/spring.application.json.spring-doc.cn

Although null values from the JSON will be added to the resulting property source, the PropertySourcesPropertyResolver treats null properties as missing values. This means that the JSON cannot override properties from lower order property sources with a null value.

External Application Properties

Spring Boot will automatically find and load application.properties and application.yaml files from the following locations when your application starts:spring-doc.cn

From the classpathspring-doc.cn
1. The classpath rootspring-doc.cn
2. The classpath /config packagespring-doc.cn
From the current directoryspring-doc.cn
1. The current directoryspring-doc.cn
2. The config/ subdirectory in the current directoryspring-doc.cn
3. Immediate child directories of the config/ subdirectoryspring-doc.cn

The list is ordered by precedence (with values from lower items overriding earlier ones). Documents from the loaded files are added as PropertySources to the Spring Environment.spring-doc.cn

If you do not like application as the configuration file name, you can switch to another file name by specifying a spring.config.name environment property. For example, to look for myproject.properties and myproject.yaml files you can run your application as follows:spring-doc.cn

$ java -jar myproject.jar --spring.config.name=myproject

You can also refer to an explicit location by using the spring.config.location environment property. This property accepts a comma-separated list of one or more locations to check.spring-doc.cn

The following example shows how to specify two distinct files:spring-doc.cn

$ java -jar myproject.jar --spring.config.location=\
	optional:classpath:/default.properties,\
	optional:classpath:/override.properties

Use the prefix optional: if the locations are optional and you do not mind if they do not exist.

spring.config.name, spring.config.location, and spring.config.additional-location are used very early to determine which files have to be loaded. They must be defined as an environment property (typically an OS environment variable, a system property, or a command-line argument).

If spring.config.location contains directories (as opposed to files), they should end in /. At runtime they will be appended with the names generated from spring.config.name before being loaded. Files specified in spring.config.location are imported directly.spring-doc.cn

Both directory and file location values are also expanded to check for profile-specific files. For example, if you have a spring.config.location of classpath:myconfig.properties, you will also find appropriate classpath:myconfig-<profile>.properties files are loaded.

In most situations, each spring.config.location item you add will reference a single file or directory. Locations are processed in the order that they are defined and later ones can override the values of earlier ones.spring-doc.cn

If you have a complex location setup, and you use profile-specific configuration files, you may need to provide further hints so that Spring Boot knows how they should be grouped. A location group is a collection of locations that are all considered at the same level. For example, you might want to group all classpath locations, then all external locations. Items within a location group should be separated with ;. See the example in the Profile Specific Files section for more details.spring-doc.cn

Locations configured by using spring.config.location replace the default locations. For example, if spring.config.location is configured with the value optional:classpath:/custom-config/,optional:file:./custom-config/, the complete set of locations considered is:spring-doc.cn

optional:classpath:custom-config/spring-doc.cn
optional:file:./custom-config/spring-doc.cn

If you prefer to add additional locations, rather than replacing them, you can use spring.config.additional-location. Properties loaded from additional locations can override those in the default locations. For example, if spring.config.additional-location is configured with the value optional:classpath:/custom-config/,optional:file:./custom-config/, the complete set of locations considered is:spring-doc.cn

optional:classpath:/;optional:classpath:/config/spring-doc.cn
optional:file:./;optional:file:./config/;optional:file:./config/*/spring-doc.cn
optional:classpath:custom-config/spring-doc.cn
optional:file:./custom-config/spring-doc.cn

This search ordering lets you specify default values in one configuration file and then selectively override those values in another. You can provide default values for your application in application.properties (or whatever other basename you choose with spring.config.name) in one of the default locations. These default values can then be overridden at runtime with a different file located in one of the custom locations.spring-doc.cn

Optional Locations

By default, when a specified config data location does not exist, Spring Boot will throw a ConfigDataLocationNotFoundException and your application will not start.spring-doc.cn

If you want to specify a location, but you do not mind if it does not always exist, you can use the optional: prefix. You can use this prefix with the spring.config.location and spring.config.additional-location properties, as well as with spring.config.import declarations.spring-doc.cn

For example, a spring.config.import value of optional:file:./myconfig.properties allows your application to start, even if the myconfig.properties file is missing.spring-doc.cn

If you want to ignore all ConfigDataLocationNotFoundExceptions and always continue to start your application, you can use the spring.config.on-not-found property. Set the value to ignore using SpringApplication.setDefaultProperties(…) or with a system/environment variable.spring-doc.cn

Wildcard Locations

If a config file location includes the * character for the last path segment, it is considered a wildcard location. Wildcards are expanded when the config is loaded so that immediate subdirectories are also checked. Wildcard locations are particularly useful in an environment such as Kubernetes when there are multiple sources of config properties.spring-doc.cn

For example, if you have some Redis configuration and some MySQL configuration, you might want to keep those two pieces of configuration separate, while requiring that both those are present in an application.properties file. This might result in two separate application.properties files mounted at different locations such as /config/redis/application.properties and /config/mysql/application.properties. In such a case, having a wildcard location of config/*/, will result in both files being processed.spring-doc.cn

By default, Spring Boot includes config/*/ in the default search locations. It means that all subdirectories of the /config directory outside of your jar will be searched.spring-doc.cn

You can use wildcard locations yourself with the spring.config.location and spring.config.additional-location properties.spring-doc.cn

A wildcard location must contain only one * and end with */ for search locations that are directories or */<filename> for search locations that are files. Locations with wildcards are sorted alphabetically based on the absolute path of the file names.

Wildcard locations only work with external directories. You cannot use a wildcard in a classpath: location.

Profile Specific Files

As well as application property files, Spring Boot will also attempt to load profile-specific files using the naming convention application-{profile}. For example, if your application activates a profile named prod and uses YAML files, then both application.yaml and application-prod.yaml will be considered.spring-doc.cn

Profile-specific properties are loaded from the same locations as standard application.properties, with profile-specific files always overriding the non-specific ones. If several profiles are specified, a last-wins strategy applies. For example, if profiles prod,live are specified by the spring.profiles.active property, values in application-prod.properties can be overridden by those in application-live.properties.spring-doc.cn

The last-wins strategy applies at the location group level. A spring.config.location of classpath:/cfg/,classpath:/ext/ will not have the same override rules as classpath:/cfg/;classpath:/ext/.spring-doc.cn

For example, continuing our prod,live example above, we might have the following files:spring-doc.cn

/cfg
  application-live.properties
/ext
  application-live.properties
  application-prod.properties

When we have a spring.config.location of classpath:/cfg/,classpath:/ext/ we process all /cfg files before all /ext files:spring-doc.cn

/cfg/application-live.propertiesspring-doc.cn
/ext/application-prod.propertiesspring-doc.cn
/ext/application-live.propertiesspring-doc.cn

When we have classpath:/cfg/;classpath:/ext/ instead (with a ; delimiter) we process /cfg and /ext at the same level:spring-doc.cn

/ext/application-prod.propertiesspring-doc.cn
/cfg/application-live.propertiesspring-doc.cn
/ext/application-live.propertiesspring-doc.cn

The Environment has a set of default profiles (by default, [default]) that are used if no active profiles are set. In other words, if no profiles are explicitly activated, then properties from application-default are considered.spring-doc.cn

Properties files are only ever loaded once. If you have already directly imported a profile specific property files then it will not be imported a second time.

Importing Additional Data

Application properties may import further config data from other locations using the spring.config.import property. Imports are processed as they are discovered, and are treated as additional documents inserted immediately below the one that declares the import.spring-doc.cn

For example, you might have the following in your classpath application.properties file:spring-doc.cn

Propertiesspring-doc.cn
YAMLspring-doc.cn

spring.application.name=myapp
spring.config.import=optional:file:./dev.properties

spring:
  application:
    name: "myapp"
  config:
    import: "optional:file:./dev.properties"

This will trigger the import of a dev.properties file in current directory (if such a file exists). Values from the imported dev.properties will take precedence over the file that triggered the import. In the above example, the dev.properties could redefine spring.application.name to a different value.spring-doc.cn

An import will only be imported once no matter how many times it is declared. The order an import is defined inside a single document within the properties/yaml file does not matter. For instance, the two examples below produce the same result:spring-doc.cn

Propertiesspring-doc.cn
YAMLspring-doc.cn

spring.config.import=my.properties
my.property=value

spring:
  config:
    import: "my.properties"
my:
  property: "value"

Propertiesspring-doc.cn
YAMLspring-doc.cn

my.property=value
spring.config.import=my.properties

my:
  property: "value"
spring:
  config:
    import: "my.properties"

In both of the above examples, the values from the my.properties file will take precedence over the file that triggered its import.spring-doc.cn

Several locations can be specified under a single spring.config.import key. Locations will be processed in the order that they are defined, with later imports taking precedence.spring-doc.cn

When appropriate, Profile-specific variants are also considered for import. The example above would import both my.properties as well as any my-<profile>.properties variants.

Spring Boot includes pluggable API that allows various different location addresses to be supported. By default you can import Java Properties, YAML and configuration trees.spring-doc.cn

Third-party jars can offer support for additional technologies (there is no requirement for files to be local). For example, you can imagine config data being from external stores such as Consul, Apache ZooKeeper or Netflix Archaius.spring-doc.cn

If you want to support your own locations, see the ConfigDataLocationResolver and ConfigDataLoader classes in the org.springframework.boot.context.config package.spring-doc.cn

Importing Extensionless Files

Some cloud platforms cannot add a file extension to volume mounted files. To import these extensionless files, you need to give Spring Boot a hint so that it knows how to load them. You can do this by putting an extension hint in square brackets.spring-doc.cn

For example, suppose you have a /etc/config/myconfig file that you wish to import as yaml. You can import it from your application.properties using the following:spring-doc.cn

Propertiesspring-doc.cn
YAMLspring-doc.cn

spring.config.import=file:/etc/config/myconfig[.yaml]

spring:
  config:
    import: "file:/etc/config/myconfig[.yaml]"

Using Configuration Trees

When running applications on a cloud platform (such as Kubernetes) you often need to read config values that the platform supplies. It is not uncommon to use environment variables for such purposes, but this can have drawbacks, especially if the value is supposed to be kept secret.spring-doc.cn

As an alternative to environment variables, many cloud platforms now allow you to map configuration into mounted data volumes. For example, Kubernetes can volume mount both ConfigMaps and Secrets.spring-doc.cn

There are two common volume mount patterns that can be used:spring-doc.cn

A single file contains a complete set of properties (usually written as YAML).spring-doc.cn
Multiple files are written to a directory tree, with the filename becoming the ‘key’ and the contents becoming the ‘value’.spring-doc.cn

For the first case, you can import the YAML or Properties file directly using spring.config.import as described above. For the second case, you need to use the configtree: prefix so that Spring Boot knows it needs to expose all the files as properties.spring-doc.cn

As an example, let’s imagine that Kubernetes has mounted the following volume:spring-doc.cn

etc/
  config/
    myapp/
      username
      password

The contents of the username file would be a config value, and the contents of password would be a secret.spring-doc.cn

To import these properties, you can add the following to your application.properties or application.yaml file:spring-doc.cn

Propertiesspring-doc.cn
YAMLspring-doc.cn

spring.config.import=optional:configtree:/etc/config/

spring:
  config:
    import: "optional:configtree:/etc/config/"

You can then access or inject myapp.username and myapp.password properties from the Environment in the usual way.spring-doc.cn

The names of the folders and files under the config tree form the property name. In the above example, to access the properties as username and password, you can set spring.config.import to optional:configtree:/etc/config/myapp.

Filenames with dot notation are also correctly mapped. For example, in the above example, a file named myapp.username in /etc/config would result in a myapp.username property in the Environment.

Configuration tree values can be bound to both string String and byte[] types depending on the contents expected.

If you have multiple config trees to import from the same parent folder you can use a wildcard shortcut. Any configtree: location that ends with /*/ will import all immediate children as config trees. As with a non-wildcard import, the names of the folders and files under each config tree form the property name.spring-doc.cn

For example, given the following volume:spring-doc.cn

etc/
  config/
    dbconfig/
      db/
        username
        password
    mqconfig/
      mq/
        username
        password

You can use configtree:/etc/config/*/ as the import location:spring-doc.cn

Propertiesspring-doc.cn
YAMLspring-doc.cn

spring.config.import=optional:configtree:/etc/config/*/

spring:
  config:
    import: "optional:configtree:/etc/config/*/"

This will add db.username, db.password, mq.username and mq.password properties.spring-doc.cn

Directories loaded using a wildcard are sorted alphabetically. If you need a different order, then you should list each location as a separate import

Configuration trees can also be used for Docker secrets. When a Docker swarm service is granted access to a secret, the secret gets mounted into the container. For example, if a secret named db.password is mounted at location /run/secrets/, you can make db.password available to the Spring environment using the following:spring-doc.cn

Propertiesspring-doc.cn
YAMLspring-doc.cn

spring.config.import=optional:configtree:/run/secrets/

spring:
  config:
    import: "optional:configtree:/run/secrets/"

Property Placeholders

The values in application.properties and application.yaml are filtered through the existing Environment when they are used, so you can refer back to previously defined values (for example, from System properties or environment variables). The standard ${name} property-placeholder syntax can be used anywhere within a value. Property placeholders can also specify a default value using a : to separate the default value from the property name, for example ${name:default}.spring-doc.cn

The use of placeholders with and without defaults is shown in the following example:spring-doc.cn

Propertiesspring-doc.cn
YAMLspring-doc.cn

app.name=MyApp
app.description=${app.name} is a Spring Boot application written by ${username:Unknown}

app:
  name: "MyApp"
  description: "${app.name} is a Spring Boot application written by ${username:Unknown}"

Assuming that the username property has not been set elsewhere, app.description will have the value MyApp is a Spring Boot application written by Unknown.spring-doc.cn

You should always refer to property names in the placeholder using their canonical form (kebab-case using only lowercase letters). This will allow Spring Boot to use the same logic as it does when relaxed binding @ConfigurationProperties.spring-doc.cn

For example, ${demo.item-price} will pick up demo.item-price and demo.itemPrice forms from the application.properties file, as well as DEMO_ITEMPRICE from the system environment. If you used ${demo.itemPrice} instead, demo.item-price and DEMO_ITEMPRICE would not be considered.spring-doc.cn

You can also use this technique to create “short” variants of existing Spring Boot properties. See the Use ‘Short’ Command Line Arguments section in “How-to Guides” for details.

Working With Multi-Document Files

Spring Boot allows you to split a single physical file into multiple logical documents which are each added independently. Documents are processed in order, from top to bottom. Later documents can override the properties defined in earlier ones.spring-doc.cn

For application.yaml files, the standard YAML multi-document syntax is used. Three consecutive hyphens represent the end of one document, and the start of the next.spring-doc.cn

For example, the following file has two logical documents:spring-doc.cn

spring:
  application:
    name: "MyApp"
---
spring:
  application:
    name: "MyCloudApp"
  config:
    activate:
      on-cloud-platform: "kubernetes"

For application.properties files a special #--- or !--- comment is used to mark the document splits:spring-doc.cn

spring.application.name=MyApp
#---
spring.application.name=MyCloudApp
spring.config.activate.on-cloud-platform=kubernetes

Property file separators must not have any leading whitespace and must have exactly three hyphen characters. The lines immediately before and after the separator must not be same comment prefix.

Multi-document property files are often used in conjunction with activation properties such as spring.config.activate.on-profile. See the next section for details.

Multi-document property files cannot be loaded by using the @PropertySource or @TestPropertySource annotations.

Activation Properties

It is sometimes useful to only activate a given set of properties when certain conditions are met. For example, you might have properties that are only relevant when a specific profile is active.spring-doc.cn

You can conditionally activate a properties document using spring.config.activate.*.spring-doc.cn

The following activation properties are available:spring-doc.cn

Table 1. activation properties
Property	Note
`on-profile`spring-doc.cn	A profile expression that must match for the document to be active.spring-doc.cn
`on-cloud-platform`spring-doc.cn	The `CloudPlatform` that must be detected for the document to be active.spring-doc.cn

For example, the following specifies that the second document is only active when running on Kubernetes, and only when either the “prod” or “staging” profiles are active:spring-doc.cn

Propertiesspring-doc.cn
YAMLspring-doc.cn

myprop=always-set
#---
spring.config.activate.on-cloud-platform=kubernetes
spring.config.activate.on-profile=prod | staging
myotherprop=sometimes-set

myprop:
  "always-set"
---
spring:
  config:
    activate:
      on-cloud-platform: "kubernetes"
      on-profile: "prod | staging"
myotherprop: "sometimes-set"

Use the prefix optional: if the locations are optional and you do not mind if they do not exist.

Wildcard locations only work with external directories. You cannot use a wildcard in a classpath: location.

For example, continuing our prod,live example above, we might have the following files:spring-doc.cn

/cfg
  application-live.properties
/ext
  application-live.properties
  application-prod.properties

When we have a spring.config.location of classpath:/cfg/,classpath:/ext/ we process all /cfg files before all /ext files:spring-doc.cn

/cfg/application-live.propertiesspring-doc.cn
/ext/application-prod.propertiesspring-doc.cn
/ext/application-live.propertiesspring-doc.cn

When we have classpath:/cfg/;classpath:/ext/ instead (with a ; delimiter) we process /cfg and /ext at the same level:spring-doc.cn

/ext/application-prod.propertiesspring-doc.cn
/cfg/application-live.propertiesspring-doc.cn
/ext/application-live.propertiesspring-doc.cn