@ConfigurationProperties vs @Value differences

1. Overview

In this article, we will learn the differences between @ConfigurationProperties vs @Value. To learn more about @ConfigurationProperties and externalizing the properties, refer to these articles.

2. @ConfigurationProperties vs @Value differences

2.1. @Value

You can use @Value annotation to inject a particular property value into Java or Kotlin field by using its key.

For example, the following @Value annotation injects the server.port application property into the Java field port of type String.

@Value("${server.port}")
String port;

@Value annotation throws exception if no matching property key exists in the application.properties or application.yml file. Thus, it strictly injects property value.

For example, @Value annotation throws the IllegalArgumentException when the property placeholder server.port could not resolve in the external properties such as application.properties file, command line arguments, so on.

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'profilesApplication': Injection of autowired dependencies failed; nested exception is java.lang.IllegalArgumentException: Could not resolve placeholder 'server.port' in value "${server.port}"
	at org.springframework.beans.factory.annotation.AutowiredAnnotationBeanPostProcessor.postProcessProperties(AutowiredAnnotationBeanPostProcessor.java:405) ~[spring-beans-5.3.18.jar:5.3.18]
...
...
Caused by: java.lang.IllegalArgumentException: Could not resolve placeholder 'server.port' in value "${server.port}"
	at org.springframework.util.PropertyPlaceholderHelper.parseStringValue(PropertyPlaceholderHelper.java:180) ~[spring-core-5.3.18.jar:5.3.18]
	at org.springframework.util.PropertyPlaceholderHelper.replacePlaceholders(PropertyPlaceholderHelper.java:126) ~[spring-core-5.3.18.jar:5.3.18]

2.2. @ConfigurationProperties

If you are working with multiple properties or properties which are hierarchical in nature, @Value annotation could be cumbersome and introduce boilerplate code.

So Spring Boot provides an alternative method @ConfigurationProperties of working with properties that let strongly typed beans govern and validate the configuration of your application.

You can add this @ConfigurationProperties annotation to a class definition or a @Bean method in a @Configuration class if you want to bind and validate some external Properties (e.g. from a .properties file).

For example, the following @ConfigurationProperties class manages the properties starting with prefix server. This AppProperties class also has a subclass Error to support the nested properties.

@ConfigurationProperties(value = "server", ignoreUnknownFields = true)
public class AppProperties {
    private String address;
    private Error error = new Error();
    public class Error {
        private String path;
    }
// getters and setters
}

If you want the @ConfigurationProperties class to be managed by the Spring container as regular beans, you can create the @ConfigurationProperties instance with @Bean method or annotate the class with @Component / @Configuration.

Alternatively, you can use the convenient @EnableConfigurationProperties annotation to allow the configuration property scanning by the Spring container.

@ConfigurationProperties annotation ignores the property if there is no key in properties file and does not throw any error. However, you can force to throw error on unknown properties by setting the attribute ignoreUnknownProperties as false.

3. Conclusion

To sum up, we have learned the differences between @ConfigurationProperties vs @Value annotation. You can refer code samples in our GitHub repository.