In Spring Boot, externalized configuration is one of its strongest features. Instead of hardcoding values, you can define them in property or YAML files. But injecting many @Value fields can quickly become cumbersome and hard to maintain. This is where property binding using @ConfigurationProperties shines.
With @ConfigurationProperties, you can map entire sections of application.properties or application.yml directly into Java objects. This post covers how to implement property binding using @ConfigurationProperties in Spring Boot.
π― What is @ConfigurationProperties?
@ConfigurationProperties is an annotation provided by Spring Boot that allows you to bind a group of related properties into a structured Java object.
Benefits:
- Clean and structured code
- Easier refactoring
- Strong typing with validation
- Supports nested and list properties
π οΈ Enable Configuration Properties
From Spring Boot 2.2+, you no longer need @EnableConfigurationProperties if the bean is annotated with @Component or manually registered.
π Step-by-Step Example
Letβs walk through property binding using @ConfigurationProperties in a sample Spring Boot application.
π§Ύ application.yml
|
1 2 3 4 5 6 7 8 9 10 11 |
kscodes: mail: host: smtp.kscodes.com port: 587 from: noreply@kscodes.com credentials: username: mailuser password: secret |
π¦ MailProperties.java
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
package com.kscodes.springboot.config; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; @Component @ConfigurationProperties(prefix = "kscodes.mail") public class MailProperties { private String host; private int port; private String from; private Credentials credentials; public static class Credentials { private String username; private String password; // Getters and setters public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public String getPassword() { return password; } public void setPassword(String password) { this.password = password; } } // Getters and setters public String getHost() { return host; } public void setHost(String host) { this.host = host; } public int getPort() { return port; } public void setPort(int port) { this.port = port; } public String getFrom() { return from; } public void setFrom(String from) { this.from = from; } public Credentials getCredentials() { return credentials; } public void setCredentials(Credentials credentials) { this.credentials = credentials; } } |
π§ͺ Using the Bound Properties
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
package com.kscodes.springboot.controller; import com.kscodes.springboot.config.MailProperties; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class MailController { private final MailProperties mailProperties; public MailController(MailProperties mailProperties) { this.mailProperties = mailProperties; } @GetMapping("/mail-config") public String getMailConfig() { return "Mail server: " + mailProperties.getHost() + ", Port: " + mailProperties.getPort() + ", From: " + mailProperties.getFrom(); } } |
π Validating Properties with JSR-303
You can add bean validation to ensure property values are correct:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
import jakarta.validation.constraints.*; @ConfigurationProperties(prefix = "kscodes.mail") @Validated public class MailProperties { @NotEmpty private String host; @Min(1) private int port; @Email private String from; ... } |
Make sure to add the validation dependency:
|
1 2 3 4 5 6 7 |
<dependency> <groupId>jakarta.validation</groupId> <artifactId>jakarta.validation-api</artifactId> </dependency> |
β
Use in @Configuration instead of @Component
If you donβt want to use @Component, register it manually in a config class:
|
1 2 3 4 5 6 7 |
@Configuration @EnableConfigurationProperties(MailProperties.class) public class AppConfig { } |
π Best Practices for Property Binding using @ConfigurationProperties
- Use YAML for hierarchical structure clarity.
- Use
@Validatedand JSR-303 for safe and clean configs. - Prefer
@ConfigurationPropertiesover@Valuefor grouped properties. - Avoid putting
@ConfigurationPropertieson a bean that has logic; keep it as a pure POJO.
β οΈ Difference Between @ConfigurationProperties and @Value
| Feature | @Value | @ConfigurationProperties |
|---|---|---|
| Used For | Single properties | Grouped/nested properties |
| Supports Relaxed Binding | β | β |
| Supports JSR-303 Validation | β | β |
| Supports Lists/Maps | Limited | Full support |
π Conclusion
Using property binding with @ConfigurationProperties in Spring Boot provides a robust, scalable, and maintainable way to manage external configurations. It’s especially useful when you have multiple related config properties and want to avoid cluttering your code with @Value annotations.
Now that you know how to implement property binding using @ConfigurationProperties, your code will be cleaner, safer, and easier to manage.
π Summary
- β
Use
@ConfigurationPropertiesfor structured, grouped configuration. - β
Annotate your POJO with
@Componentor register it manually. - β Use JSR-303 validation for reliable config inputs.
- β Organize complex configuration logic with nested classes.