Spring Boot allows you to externalize your configuration so you can work with the same
application code in different environments. You can use properties files, YAML files,
environment variables and command-line arguments to externalize configuration. Property
values can be injected directly into your beans using the @Value
annotation, accessed
via Spring’s Environment
abstraction or
bound to structured objects
via @ConfigurationProperties
.
Spring Boot uses a very particular PropertySource
order that is designed to allow
sensible overriding of values, properties are considered in the following order:
SPRING_APPLICATION_JSON
(inline JSON embedded in an environment variable or system property)java:comp/env
.System.getProperties()
).RandomValuePropertySource
that only has properties in random.*
.application-{profile}.properties
and YAML variants)application-{profile}.properties
and YAML variants)application.properties
and YAML
variants).application.properties
and YAML
variants).@PropertySource
annotations
on your @Configuration
classes.SpringApplication.setDefaultProperties
).To provide a concrete example, suppose you develop a @Component
that uses a
name
property:
import org.springframework.stereotype.* import org.springframework.beans.factory.annotation.* @Component public class MyBean { @Value("${name}") private String name; // ... }
On your application classpath (e.g. inside your jar) you can have an
application.properties
that provides a sensible default property value for name
. When
running in a new environment, an application.properties
can be provided outside of your
jar that overrides the name
; and for one-off testing, you can launch with a specific
command line switch (e.g. java -jar app.jar --name="Spring"
).
Tip | |
---|---|
The $ SPRING_APPLICATION_JSON='{"foo":{"bar":"spam"}}' java -jar myapp.jar In this example you will end up with $ java -Dspring.application.json='{"foo":"bar"}' -jar myapp.jar or command line argument: $ java -jar myapp.jar --spring.application.json='{"foo":"bar"}' or as a JNDI variable |
The RandomValuePropertySource
is useful for injecting random values (e.g. into secrets
or test cases). It can produce integers, longs or strings, e.g.
my.secret=${random.value} my.number=${random.int} my.bignumber=${random.long} my.number.less.than.ten=${random.int(10)} my.number.in.range=${random.int[1024,65536]}
The random.int*
syntax is OPEN value (,max) CLOSE
where the OPEN,CLOSE
are any
character and value,max
are integers. If max
is provided then value
is the minimum
value and max
is the maximum (exclusive).
By default SpringApplication
will convert any command line option arguments (starting
with ‘--’, e.g. --server.port=9000
) to a property
and add it to the Spring
Environment
. As mentioned above, command line properties always take precedence over
other property sources.
If you don’t want command line properties to be added to the Environment
you can disable
them using SpringApplication.setAddCommandLineProperties(false)
.
SpringApplication
will load properties from application.properties
files in the
following locations and add them to the Spring Environment
:
/config
subdirectory of the current directory./config
packageThe list is ordered by precedence (properties defined in locations higher in the list override those defined in lower locations).
Note | |
---|---|
You can also use YAML ('.yml') files as an alternative to '.properties'. |
If you don’t like application.properties
as the configuration file name you can switch
to another by specifying a spring.config.name
environment property. You can also refer
to an explicit location using the spring.config.location
environment property
(comma-separated list of directory locations, or file paths).
$ java -jar myproject.jar --spring.config.name=myproject
or
$ java -jar myproject.jar --spring.config.location=classpath:/default.properties,classpath:/override.properties
If spring.config.location
contains directories (as opposed to files) they should end
in /
(and will be appended with the names generated from spring.config.name
before
being loaded). The default search path classpath:,classpath:/config,file:,file:config/
is always used, irrespective of the value of spring.config.location
. In that way you
can set up default values for your application in application.properties
(or whatever
other basename you choose with spring.config.name
) and override it at runtime with a
different file, keeping the defaults.
Note | |
---|---|
If you use environment variables rather than system properties, most operating
systems disallow period-separated key names, but you can use underscores instead (e.g.
|
Note | |
---|---|
If you are running in a container then JNDI properties (in |
In addition to application.properties
files, profile-specific properties can also be
defined using the naming convention application-{profile}.properties
. The
Environment
has a set of default profiles (by default [default]
) which are
used if no active profiles are set (i.e. if no profiles are explicitly activated
then properties from application-default.properties
are loaded).
Profile specific properties are loaded from the same locations as standard
application.properties
, with profile-specific files always overriding the non-specific
ones irrespective of whether the profile-specific files are inside or outside your
packaged jar.
If several profiles are specified, a last wins strategy applies. For example, profiles
specified by the spring.active.profiles
property are added after those configured via
the SpringApplication
API and therefore take precedence.
The values in application.properties
are filtered through the existing Environment
when they are used so you can refer back to previously defined values (e.g. from System
properties).
app.name=MyApp app.description=${app.name} is a Spring Boot application
Tip | |
---|---|
You can also use this technique to create ‘short’ variants of existing Spring Boot properties. See the Section 69.3, “Use ‘short’ command line arguments” how-to for details. |
YAML is a superset of JSON, and as such is a very convenient format
for specifying hierarchical configuration data. The SpringApplication
class will
automatically support YAML as an alternative to properties whenever you have the
SnakeYAML library on your classpath.
Note | |
---|---|
If you use ‘starter POMs’ SnakeYAML will be automatically provided via
|
Spring Framework provides two convenient classes that can be used to load YAML documents.
The YamlPropertiesFactoryBean
will load YAML as Properties
and the
YamlMapFactoryBean
will load YAML as a Map
.
For example, the following YAML document:
environments: dev: url: http://dev.bar.com name: Developer Setup prod: url: http://foo.bar.com name: My Cool App
Would be transformed into these properties:
environments.dev.url=http://dev.bar.com environments.dev.name=Developer Setup environments.prod.url=http://foo.bar.com environments.prod.name=My Cool App
YAML lists are represented as property keys with [index]
dereferencers,
for example this YAML:
my: servers: - dev.bar.com - foo.bar.com
Would be transformed into these properties:
my.servers[0]=dev.bar.com my.servers[1]=foo.bar.com
To bind to properties like that using the Spring DataBinder
utilities (which is what
@ConfigurationProperties
does) you need to have a property in the target bean of type
java.util.List
(or Set
) and you either need to provide a setter, or initialize it
with a mutable value, e.g. this will bind to the properties above
@ConfigurationProperties(prefix="my") public class Config { private List<String> servers = new ArrayList<String>(); public List<String> getServers() { return this.servers; } }
The YamlPropertySourceLoader
class can be used to expose YAML as a PropertySource
in the Spring Environment
. This allows you to use the familiar @Value
annotation with
placeholders syntax to access YAML properties.
You can specify multiple profile-specific YAML documents in a single file by
using a spring.profiles
key to indicate when the document applies. For example:
server: address: 192.168.1.100 --- spring: profiles: development server: address: 127.0.0.1 --- spring: profiles: production server: address: 192.168.1.120
In the example above, the server.address
property will be 127.0.0.1
if the
development
profile is active. If the development
and production
profiles are not
enabled, then the value for the property will be 192.168.1.100
.
The default profiles are activated if none are explicitly active when the application
context starts. So in this YAML we set a value for security.user.password
that is
only available in the "default" profile:
server: port: 80000 --- spring: profiles: default security: user: password: weak
whereas in this example, the password is always set because it isn’t attached to any profile, and it would have to be explicitly reset in all other profiles as necessary:
server: port: 80000 security: user: password: weak
Using the @Value("${property}")
annotation to inject configuration properties can
sometimes be cumbersome, especially if you are working with multiple properties or
your data is hierarchical in nature. Spring Boot provides an alternative method
of working with properties that allows strongly typed beans to govern and validate
the configuration of your application. For example:
@Component @ConfigurationProperties(prefix="connection") public class ConnectionSettings { private String username; private InetAddress remoteAddress; // ... getters and setters }
Note | |
---|---|
The getters and setters are advisable, since binding is via standard Java Beans
property descriptors, just like in Spring MVC. They are mandatory for immutable types or
those that are directly coercible from |
Note | |
---|---|
Contrary to |
The @EnableConfigurationProperties
annotation is automatically applied to your project
so that any beans annotated with @ConfigurationProperties
will be configured from the
Environment
properties. This style of configuration works particularly well with the
SpringApplication
external YAML configuration:
# application.yml connection: username: admin remoteAddress: 192.168.1.1 # additional configuration as required
To work with @ConfigurationProperties
beans you can just inject them in the same way
as any other bean.
@Service public class MyService { @Autowired private ConnectionSettings connection; //... @PostConstruct public void openConnection() { Server server = new Server(); this.connection.configure(server); } }
It is also possible to shortcut the registration of @ConfigurationProperties
bean
definitions by simply listing the properties classes directly in the
@EnableConfigurationProperties
annotation:
@Configuration @EnableConfigurationProperties(ConnectionSettings.class) public class MyConfiguration { }
Tip | |
---|---|
Using |
As well as using @ConfigurationProperties
to annotate a class, you can also use it
on @Bean
methods. This can be particularly useful when you want to bind properties to
third-party components that are outside of your control.
To configure a bean from the Environment
properties, add @ConfigurationProperties
to
its bean registration:
@ConfigurationProperties(prefix = "foo") @Bean public FooComponent fooComponent() { ... }
Any property defined with the foo
prefix will be mapped onto that FooComponent
bean
in a similar manner as the ConnectionSettings
example above.
Spring Boot uses some relaxed rules for binding Environment
properties to
@ConfigurationProperties
beans, so there doesn’t need to be an exact match between
the Environment
property name and the bean property name. Common examples where this
is useful include dashed separated (e.g. context-path
binds to contextPath
), and
capitalized (e.g. PORT
binds to port
) environment properties.
For example, given the following @ConfigurationProperties
class:
@Component @ConfigurationProperties(prefix="person") public class ConnectionSettings { private String firstName; public String getFirstName() { return this.firstName; } public void setFirstName(String firstName) { this.firstName = firstName; } }
The following properties names can all be used:
Table 24.1. relaxed binding
Property | Note |
---|---|
| Standard camel case syntax. |
| Dashed notation, recommended for use in |
| Upper case format. Recommended when using a system environment variables. |
Spring will attempt to coerce the external application properties to the right type when
it binds to the @ConfigurationProperties
beans. If you need custom type conversion you
can provide a ConversionService
bean (with bean id conversionService
) or custom
property editors (via a CustomEditorConfigurer
bean) or custom Converters
(with
bean definitions annotated as @ConfigurationPropertiesBinding
).
Note | |
---|---|
As this bean is requested very early during the application lifecycle, make sure to
limit the dependencies that your |
Spring Boot will attempt to validate external configuration, by default using JSR-303
(if it is on the classpath). You can simply add JSR-303 javax.validation
constraint
annotations to your @ConfigurationProperties
class:
@Component @ConfigurationProperties(prefix="connection") public class ConnectionSettings { @NotNull private InetAddress remoteAddress; // ... getters and setters }
In order to validate values of nested properties, you must annotate the associated field
as @Valid
to trigger its validation. For example, building upon the above
ConnectionSettings
example:
@Component @ConfigurationProperties(prefix="connection") public class ConnectionSettings { @NotNull @Valid private RemoteAddress remoteAddress; // ... getters and setters public static class RemoteAddress { @NotEmpty public String hostname; // ... getters and setters } }
You can also add a custom Spring Validator
by creating a bean definition called
configurationPropertiesValidator
. There is a
Validation sample
so you can see how to set things up.
Tip | |
---|---|
The |