Master Spring Boot Config: @Value vs @ConfigurationProperties & Advanced Binding

Environment: SpringBoot 3.3.0

1. Introduction

In Spring Boot, custom configuration properties can be loaded and bound using annotations such as @Value and @ConfigurationProperties . This article introduces both approaches.

1.1 @Value annotation

@Value injects a specific value from a configuration file into a bean field.

2.2 @ConfigurationProperties annotation

@ConfigurationProperties binds external configuration properties to Java class fields, especially useful for complex configurations.

2.3 Comparison

Feature

@ConfigurationProperties

@Value

Loose binding

Yes

Limited

Metadata support

Yes

No

SpEL expression

No

Yes

2. Practical Cases

2.1 JavaBean property binding

This is the most common property binding scenario.

<code>@Component
@ConfigurationProperties("pack")
public class PackProperties {
  private boolean enabled;
  private InetAddress remoteAddress;
  private final Security security = new Security();
  // getters, setters
  public static class Security {
    private String username;
    private String password;
    private List<String> roles = new ArrayList<>(Collections.singleton("USER"));
    // getters, setters
  }
}
</code>

Corresponding YAML configuration:

<code>pack:
  sys:
    remote-address: 192.168.2.100
    enabled: true
    security:
      roles: GUEST, ADMIN
</code>

If the setter for a property is omitted, an error will occur (see image).

2.2 Constructor binding

<code>@ConfigurationProperties(prefix = "pack")
public class PackConstructorProperties {
  private Integer age;
  private String name;
  @DurationUnit(ChronoUnit.SECONDS)
  private Duration expire;
  private Security security = new Security();

  @ConstructorBinding
  public PackConstructorProperties(Integer age, String name, Duration expire, Security security) {
    this.age = age;
    this.name = name;
    this.expire = expire;
    this.security = security;
  }

  public static class Security {
    private String role;
  }
}
</code>

When using constructor binding, the class must be registered via @ConfigurationPropertiesScan or @EnableConfigurationProperties :

<code>@Configuration
@EnableConfigurationProperties({PackConstructorProperties.class})
public class AppConfig {}
</code>

2.3 Record component binding (Java 16+)

<code>@ConfigurationProperties(prefix = "pack.app")
public record AppProperties(String version, String title, Integer numbers) {}
</code>

2.4 Duration conversion

Spring Boot supports binding java.time.Duration with various formats (plain long, ISO‑8601, or readable unit suffixes).

<code>@Component
@ConfigurationProperties("sys.times")
public class PackTimeProperties {
  @DurationUnit(ChronoUnit.SECONDS)
  private Duration sessionTimeout = Duration.ofSeconds(30);
  private Duration readTimeout = Duration.ofMillis(1000);
  // getters, setters
}
</code>

YAML configuration:

<code>sys:
  times:
    read-timeout: 60
    session-timeout: 6000ms
</code>

Result: PackTimeProperties [sessionTimeout=PT6S, readTimeout=PT0.06S]

2.5 DataSize conversion

Spring provides the DataSize type for byte‑based sizes.

<code>@Component
@ConfigurationProperties("sys.ds")
public class PackDataSizeProperties {
  @DataSizeUnit(DataUnit.MEGABYTES)
  private DataSize bufferSize = DataSize.ofMegabytes(2);
  private DataSize sizeThreshold = DataSize.ofBytes(512);
}
</code>

YAML configuration:

<code>sys:
  ds:
    buffer-size: 10
    size-threshold: 1024KB
</code>

Result: PackDataSizeProperties [bufferSize=10485760B, sizeThreshold=1048576B]

2.6 Validation

<code>@ConfigurationProperties("pack")
@Validated
public class MyProperties {
  @NotNull
  private InetAddress remoteAddress;
  @Valid
  private final Security security = new Security();
}
</code>

Validation ensures that configuration values meet the defined constraints.