How to Use @ConfigurationProperties in Spring Boot

Use @ConfigurationProperties on a Java class to bind external configuration properties (like from application.yml or application.properties) to its fields automatically. Annotate the class with @Component or use @EnableConfigurationProperties to register it as a Spring bean.

Syntax

The @ConfigurationProperties annotation is placed on a Java class to map configuration properties with a common prefix to its fields. The class must be a Spring bean, usually annotated with @Component or registered via @EnableConfigurationProperties.

Key parts:

• prefix: The property prefix to bind (e.g., app for app.name).
• Fields: Java fields matching property names under the prefix.
• Getters and setters: Required for binding.

java

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    private int timeout;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getTimeout() {
        return timeout;
    }

    public void setTimeout(int timeout) {
        this.timeout = timeout;
    }
}

Example

This example shows how to bind properties from application.yml to a Java class using @ConfigurationProperties. The properties app.name and app.timeout are mapped to fields in AppProperties. The class is a Spring bean and can be injected anywhere.

java

/* application.yml */
app:
  name: MyApp
  timeout: 30


// AppProperties.java
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    private int timeout;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getTimeout() {
        return timeout;
    }

    public void setTimeout(int timeout) {
        this.timeout = timeout;
    }
}


// Usage in a Spring service
import org.springframework.stereotype.Service;

@Service
public class MyService {
    private final AppProperties appProperties;

    public MyService(AppProperties appProperties) {
        this.appProperties = appProperties;
    }

    public String getAppInfo() {
        return "App: " + appProperties.getName() + ", Timeout: " + appProperties.getTimeout();
    }
}

Output

App: MyApp, Timeout: 30

Common Pitfalls

• Forgetting to annotate the class with @Component or not enabling configuration properties registration causes binding to fail.
• Missing getters and setters prevents Spring from setting the fields.
• Incorrect prefix in @ConfigurationProperties leads to no values being bound.
• Using immutable fields without constructor binding (requires Spring Boot 2.2+ and extra setup).

java

/* Wrong: Missing @Component, so binding won't happen */
import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
}

/* Right: Add @Component to register bean */
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
}

Quick Reference

• @ConfigurationProperties(prefix = "prefix"): Binds properties with this prefix.
• @Component: Registers the class as a Spring bean.
• Properties file keys must match Java field names (camelCase or kebab-case).
• Getters and setters are required for binding.
• Use @EnableConfigurationProperties on a configuration class alternatively to register.

Key Takeaways

Annotate a class with @ConfigurationProperties and a prefix to bind external config properties.

Make the class a Spring bean using @Component or @EnableConfigurationProperties for binding to work.

Ensure fields have getters and setters matching property names for proper binding.

Use application.yml or application.properties to define the properties with the matching prefix.

Common mistakes include missing bean registration and incorrect prefix causing no binding.