spring-boot-demo/configuration-properties/docs/04-records-and-defaults.md

← Registration · Index · Validation →

4. Records, constructor binding and defaults

See MailProperties and the bound output in 03-value-vs-binding.txt.

Records need no annotation

A record has exactly one canonical constructor, so the binder uses it. @ConstructorBinding is only needed to pick between candidates when a type has more than one constructor — and since Spring Boot 3 it goes on the constructor, not the type.

Constructor binding gives you immutability, which matters more than it sounds: a mutable @ConfigurationProperties bean is a singleton that anything can write to.

Defaults

A record cannot have field initialisers, so the default has to be attached to the component:

public record MailProperties(
        String host,                               // no default: null if absent
        @DefaultValue("587") int port,
        @DefaultValue("30s") Duration timeout,
        @DefaultValue RetryProperties retries,     // nested, with its own defaults
        @DefaultValue List<String> recipients,     // empty list, not null
        @DefaultValue Map<String, String> headers) {
}

@DefaultValue with no argument on a nested type means "construct it with its own defaults" rather than "bind it to null". Same for collections: you get an empty one instead of null, which removes a class of NullPointerException from startup code.

A component with neither a value nor a @DefaultValue binds to null for a reference type. A record component of primitive type with no value and no default fails the bind.

The whole-object rule

If nothing under the prefix is present, the binder returns no result at all — not an object full of defaults. BindResult.isBound() is false and get() throws. Defaults apply to components of an object that is being constructed; they do not cause one to be constructed.

For a bean registered through @ConfigurationPropertiesScan this is invisible, because Spring Boot binds with a target that always constructs. It shows up as soon as you call Binder yourself, which is why it is here.

Lists

Written as	@ConfigurationProperties	@Value
YAML block list	binds	does not see it
a,b,c string	binds	binds
foo[0], foo[1]	binds	does not see it

The middle row is the only shape both understand, and it is why comma-separated lists persist in configuration long after they stopped being pleasant to read.

One thing to know about list overriding: a list is bound from the highest-precedence source that contains the property, entirely. Lists do not merge across sources. A source that sets three elements replaces a lower source's two; it does not append to them.