✅ Mastering @ConfigurationProperties in Spring Boot: Injecting Configuration in a Clean & Scalable Way

Meta Description:
Learn how to use @ConfigurationProperties in Spring Boot to inject properties or YAML values efficiently into Spring Beans. Includes practical examples, best practices, and setup tips.

---

🔍 What is @ConfigurationProperties in Spring Boot?

In Spring Boot, @ConfigurationProperties is a powerful annotation used to inject values from application.properties or application.yml into a Spring bean in bulk.

This approach is ideal when you want to bind multiple configuration properties that share a common prefix to a single Java class. It promotes cleaner, scalable, and more maintainable code compared to using @Value repeatedly.

---

📌 Key Points to Remember

1. ✅ The keys in the .properties or .yml file must have a common prefix.
2. ✅ The last part of each key (after the prefix) should match the bean's property names.
3. ✅ Annotate the Spring bean class with @ConfigurationProperties(prefix = "your.prefix").
4. ✅ The class must have setter methods (or use Lombok’s @Setter) as Spring uses setter injection for binding.

---

✅ Example: Injecting Custom Properties Using @ConfigurationProperties

Let’s say we want to load some mail server configuration from the application.yml file.

🔧 Step 1: Define properties in application.yml

mail:
  host: smtp.mailtrap.io
  port: 2525
  username: testuser
  password: secret

💡 Step 2: Create a Spring bean class to bind the values

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

@Component
@ConfigurationProperties(prefix = "mail")
public class MailConfig {

    private String host;
    private int port;
    private String username;
    private String password;

    // Setter methods (required for binding)
    public void setHost(String host) { this.host = host; }
    public void setPort(int port) { this.port = port; }
    public void setUsername(String username) { this.username = username; }
    public void setPassword(String password) { this.password = password; }

    // Optional: Getter methods
    public String getHost() { return host; }
    public int getPort() { return port; }
    public String getUsername() { return username; }
    public String getPassword() { return password; }
}

---

🧪 Step 3: Use the MailConfig Bean Anywhere

@RestController
public class TestController {

    private final MailConfig mailConfig;

    public TestController(MailConfig mailConfig) {
        this.mailConfig = mailConfig;
    }

    @GetMapping("/mail-info")
    public String getMailInfo() {
        return "Host: " + mailConfig.getHost() + ", Port: " + mailConfig.getPort();
    }
}

---

💡 Why Use @ConfigurationProperties Over @Value?

@Value	@ConfigurationProperties
Good for single values	Better for groups of related values
Repeated annotations	Cleaner, centralized config
No validation support	Can add validation with @Validated

---

✅ Bonus Tips

• Use @EnableConfigurationProperties if the bean is not annotated with @Component.
• Add spring-boot-configuration-processor dependency for metadata support in IDEs.
• Combine with @Validated for automatic validation of properties.

---