External configuration
Configuration is the settings that change from one place to another while the code stays the same: a server URL, a port, a timeout, a feature switch, a log level. spring_boot_dart reads them from outside the code, so one build runs on a laptop, in tests and in production, each with its own values, and nothing is recompiled.
This is Spring Boot's Externalized Configuration. The file names, keys and rules are Spring Boot's, so configuration from a Spring project usually works unchanged.
Why
A setting written in code needs a new build to change. A setting read from configuration can be changed by whoever runs the program: an operator with a file next to the binary, a container with an environment variable, a CI job with a command-line option, a Flutter build with a --dart-define. Spring Boot's rules decide which of them wins, so you can ship sensible defaults in lib/resources/application.yml and override any key from outside.
Example
The same key from five places. The highest source wins.
# lib/resources/application.yml: shipped with the program
shop:
url: http://localhost:8080
# lib/resources/application-prod.yml: read with the prod profile
shop:
url: https://neon.books
dart run bin/main.dart # http://localhost:8080
dart run bin/main.dart --spring.profiles.active=prod # https://neon.books
SHOP_URL=https://staging.neon.books dart run bin/main.dart # the environment wins over files
dart run bin/main.dart --shop.url=http://127.0.0.1:9000 # the command line wins over all
// Any bean reads it the same way, whatever the source.
@Service()
class Links {
Links(@Value(r'${shop.url}') this.url);
final String url;
}
The sources
| Source | Where it comes from | Page |
|---|---|---|
| Config files | application.properties, application.yml, application.yaml in lib/resources/, lib/resources/config/, ./, ./config/, ./config/*/ |
Config files |
| Profile files and documents | application-{profile}.*, and documents with spring.config.activate.on-profile |
Profiles |
| Imports | spring.config.import: more files, directories, config trees, HTTP, packages, assets |
Imports |
| Command line | --key=value |
Command line, environment and --dart-define |
| Environment variables | SHOP_URL=..., with relaxed names |
Command line, environment and --dart-define |
--dart-define |
Values compiled into the program | Command line, environment and --dart-define |
SPRING_APPLICATION_JSON |
One JSON object in a variable or property | Command line, environment and --dart-define |
| Code | SpringApplication(defaultProperties:), run(properties:), EnvironmentPostProcessor |
Command line, environment and --dart-define |
@PropertySource |
Files named on a configuration class | Property sources |
Which source wins
When several sources set the same key, the highest one wins. From the highest:
run(properties: ...), andspringBootTest(properties: ...)in tests (the test'sdynamicPropertiesare higher still).- Command-line arguments (
--shop.url=...). --dart-definevalues.SPRING_APPLICATION_JSON(or--spring.application.json).- OS environment variables. Flutter apps do not read them unless the build switches it on.
${random.*}values.- Config files, in this order (higher first):
spring.config.importgiven on the command line or in the environment;- then
spring.config.additional-location; - then the locations:
file:./config/*/,file:./config/,file:./aboveresources:/config/,resources:/; - within each group, profile files above plain files, the last active profile highest;
- an imported file above the file that imports it, and its profile variants above those of the importing file;
- in one location,
.propertiesabove.ymlabove.yaml; - in one file, a later document above an earlier one.
@PropertySourcefiles.SpringApplication(defaultProperties: ...).
A list always comes whole from the highest source that has it: --shop.hosts[0]=local replaces the file's three hosts, it does not change the first one. Map entries are merged across sources, the higher source winning per key. See @ConfigurationProperties.
When the configuration is read
The configuration is read once, at the start, before any bean is created:
- The command line, the
--dart-definevalues, the environment, the code's properties and${random.*}become property sources. EnvironmentPostProcessors ordered beforeEnvironmentPostProcessor.configDataOrderrun (SPRING_APPLICATION_JSONis one of them).- The config files are read: locations, profiles, imports, documents. This is
ConfigDataEnvironment. - The other
EnvironmentPostProcessors run, among them the check for renamed properties. ApplicationEnvironmentPreparedEventis published, the log levels are applied and the beans are created.
runApplication reads the files synchronously. Locations that can only be read asynchronously (HTTP, Flutter assets) need runApplicationAsync, which Flutter apps use anyway.
Changing a config file needs a restart. In development, a hot reload restarts the context with the new values.
Editor completion
The generator writes lib/spring_gen/spring_metadata.json for every package with Spring code: the keys of its @ConfigurationProperties classes with their /// comments, types, defaults and allowed values. dart run tool/spring_schema.dart <app> (in the framework repository) turns the metadata of an application and its dependencies into a JSON Schema for the YAML language server, so application*.yml gets completion and checks. See Metadata.
In Spring (Java)
Everything on these pages follows Spring Boot's Externalized Configuration, with these main differences:
lib/resources/is the classpath, writtenresources:(notclasspath:).--dart-definevalues are a source of their own, right below the command line. Java has no counterpart; the nearest is-Dkey=value..propertiesfiles are UTF-8, not ISO-8859-1.- No
env:imports, no XML properties files, no Spring Cloud Config client. HTTP imports exist (spring.config.import=https://...), with an asynchronous start.
The full list is on Differences from Spring.