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.

@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
  }
}

Corresponding YAML configuration:

pack:
  sys:
    remote-address: 192.168.2.100
    enabled: true
    security:
      roles: GUEST, ADMIN

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

2.2 Constructor binding

@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;
  }
}

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

@Configuration
@EnableConfigurationProperties({PackConstructorProperties.class})
public class AppConfig {}

2.3 Record component binding (Java 16+)

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

2.4 Duration conversion

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

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

YAML configuration:

sys:
  times:
    read-timeout: 60
    session-timeout: 6000ms

Result:

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

2.5 DataSize conversion

Spring provides the DataSize type for byte‑based sizes.

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

YAML configuration:

sys:
  ds:
    buffer-size: 10
    size-threshold: 1024KB

Result:

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

2.6 Validation

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

Validation ensures that configuration values meet the defined constraints.