Spring Boot @ConfigurationProperties Annotation | Externalized Configuration

 🚀 Introduction: What is @ConfigurationProperties in Spring Boot?

The @ConfigurationProperties annotation in Spring Boot is used to map external configuration properties (from application.yml or application.properties) to Java objects. It helps in keeping configuration type-safe, structured, and reusable.

✅ Key Features of @ConfigurationProperties:
 ✔ Binds external properties (application.yml, application.properties) to Java classes.
 ✔ Supports prefix-based mapping for structured configuration.
 ✔ Works with YAML and properties files.
 ✔ Allows validation using @Validated.

📌 In this guide, you’ll learn:
 ✅ How @ConfigurationProperties works in Spring Boot.
 ✅ How to use it with YAML/properties files.
 ✅ How to validate configuration values.

1️⃣ Why Use @ConfigurationProperties Instead of @Value?

📌 Use @ConfigurationProperties when working with structured, reusable configurations.
 📌 Use @Value for injecting a single property.

2️⃣ Setting Up @ConfigurationProperties in Spring Boot

1. Enable Configuration Properties in the Main Class

@SpringBootApplication
@EnableConfigurationProperties(AppConfig.class) // Enable configuration binding
public class SpringBootApp {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootApp.class, args);
    }
}

✅ @EnableConfigurationProperties allows Spring Boot to scan configuration classes.

2. Define a Configuration Class (AppConfig.java)

@ConfigurationProperties(prefix = "app") // Maps properties with 'app' prefix
public class AppConfig {
    
    private String name;
    private String version;
    
    // Getters and Setters
}

✅ Maps app.name and app.version from the properties file.

3. Define Properties in application.yml

app:
  name: "MyApp"
  version: "1.0.0"

✅ Spring Boot automatically binds these values to AppConfig.

4. Inject AppConfig into a Component

@RestController
@RequestMapping("/api")
public class ConfigController {

    private final AppConfig appConfig;

    public ConfigController(AppConfig appConfig) {
        this.appConfig = appConfig;
    }

    @GetMapping("/config")
    public String getConfig() {
        return "App Name: " + appConfig.getName() + ", Version: " + appConfig.getVersion();
    }
}

📌 GET Request (GET /api/config)

Response: App Name: MyApp, Version: 1.0.0

✅ The configuration is successfully injected into the controller.

3️⃣ Binding Complex Data Types (List, Map, Nested Objects)

1. Define a Complex Configuration Class

@ConfigurationProperties(prefix = "server")
public class ServerConfig {

    private List<String> hosts;
    private Map<String, String> credentials;
    private Database database;

    // Getters and Setters

    public static class Database {
        private String url;
        private String username;
        private String password;
        
        // Getters and Setters
    }
}

✅ Supports List, Map, and nested objects (Database).

2. Define Configuration in application.yml

server:
  hosts:
    - "host1.example.com"
    - "host2.example.com"
  credentials:
    username: "admin"
    password: "securepass"
  database:
    url: "jdbc:mysql://localhost:3306/mydb"
    username: "dbuser"
    password: "dbpass"

✅ Values are mapped automatically to ServerConfig.

3. Inject and Use the Configuration

@RestController
@RequestMapping("/api")
public class ServerController {

    private final ServerConfig serverConfig;

    public ServerController(ServerConfig serverConfig) {
        this.serverConfig = serverConfig;
    }

    @GetMapping("/server-info")
    public String getServerInfo() {
        return "Hosts: " + serverConfig.getHosts() + ", DB URL: " + serverConfig.getDatabase().getUrl();
    }
}

📌 GET Request (GET /api/server-info)

Response: Hosts: [host1.example.com, host2.example.com], DB URL: jdbc:mysql://localhost:3306/mydb

✅ Spring Boot successfully maps nested configurations.

4️⃣ Validating Configuration Properties

Spring Boot allows automatic validation of configuration properties using @Validated.

1. Enable Validation in the Configuration Class

@ConfigurationProperties(prefix = "app")
@Validated
public class AppConfig {

    @NotBlank // Ensures name is not blank
    private String name;

    @Pattern(regexp = "\\d+\\.\\d+\\.\\d+") // Ensures version follows X.Y.Z format
    private String version;

    // Getters and Setters
}

✅ If app.name is blank or app.version is invalid, the application fails to start.

5️⃣ Using @ConstructorBinding for Immutable Configurations

From Spring Boot 2.2+, you can use @ConstructorBinding to make configuration properties immutable (no setters required).

📌 Example: Immutable Configuration Class

@ConfigurationProperties(prefix = "app")
@ConstructorBinding
public record AppConfig(String name, String version) {}

✅ No need for setters — values are set at the time of object creation.

🎯 Summary: Best Practices for Using @ConfigurationProperties

✅ Use @ConfigurationProperties for structured configurations.
 ✅ Use @Validated to enforce validation rules.
 ✅ Use @ConstructorBinding for immutable configurations.
 ✅ Group related properties in a single class instead of multiple @Value injections.
 ✅ Keep property names consistent and meaningful.

🚀 Following these best practices ensures clean, maintainable configurations in Spring Boot!