Quick overview

If you hate scattering string literals all over your code and enjoy typed safety with a side of mild smugness this guide shows how to bind configuration properties in Spring and Spring Boot using @ConfigurationProperties. You will see how to handle lists maps nested classes and prefix based binding while keeping your app readable and testable.

Define the config class

Create a plain Java class and annotate it with @ConfigurationProperties(prefix = "app"). You can use traditional setters and getters or prefer constructor based binding with @ConstructorBinding if you like immutable objects and fewer surprises at runtime.

@ConfigurationProperties(prefix = "app")
public class AppConfig {
    private List items
    private Map settings
    private Security security

    public static class Security {
        private boolean enabled
        private List roles
    }

    // add getters or use constructor binding
}

Register and enable binding

Spring needs to know where to find that class. You have options depending on how tidy or lazy you feel.

• Use @EnableConfigurationProperties(AppConfig.class) on a configuration class if you like explicit wiring
• Add @ConfigurationPropertiesScan on your main application class to let Spring pick up annotated classes automatically
• Annotate the config class with @Component for quick results when you are in a hurry

Working with lists maps and nested types

Collections and nested groups are first class citizens. Use List for ordered collections and Map for keyed data. Nest related settings into a static inner class to keep things organized.

app.items[0]=alpha
app.items[1]=beta
app.settings.mode=fast
app.security.enabled=true
app.security.roles[0]=USER
app.security.roles[1]=ADMIN

Spring Boot relaxed binding will map hyphens underscores and camel case to your fields so app-settings or app_settings will still land in the right place without manual gymnastics.

Test and verify the binding

Inject the config class into a test or component and assert the expected values. If a list or map looks empty check the property keys the field types and whether the class was registered for binding before blaming Spring.

Example verification approach

• Load the test context with @SpringBootTest or with a slice that includes configuration properties
• Autowire the AppConfig and assert items size settings and nested flags
• If a value is missing check prefix typos and whether you used constructor binding without matching constructor parameters

Common gotchas

• Empty list or map often means a typo in property keys or wrong field type
• Not picking up the class means you forgot @EnableConfigurationProperties or @ConfigurationPropertiesScan is not active
• Constructor based binding will fail if constructor parameters do not match property names

Best practices

• Prefer constructor binding for immutable configuration classes it reduces accidental mutation
• Use @ConfigurationPropertiesScan so you do not have to register every single config class by hand
• Group related values inside nested classes to keep properties tidy and easier to document

Final thought If you follow these steps you get typed configuration that plays nicely with Spring Boot and reduces the chance of runtime surprises. Also you get to stop using mysterious string keys in ten different classes which will make future you mildly grateful and present you slightly smug.