@Value를 버리고 @ConfigurationProperties로 갈아탄 이유

설정값이 서너 개일 때는 @Value가 편하다. 문제는 프로젝트가 크면서 설정이 수십 개가 되고, 어디서 뭘 읽는지 추적이 안 되기 시작할 때다.

@Value의 문제

@Service
public class SettlementService {
    @Value("${settlement.cp-share-rate}")
    private BigDecimal cpShareRate;

    @Value("${settlement.rounding-mode:HALF_UP}")
    private String roundingMode;
}

• 같은 키를 읽는 코드가 여러 클래스에 흩어진다
• 오타가 나면 런타임에 터진다
• 테스트에서 주입하려면 리플렉션이나 생성자 장난이 필요하다

@ConfigurationProperties로

@ConfigurationProperties(prefix = "settlement")
public record SettlementProperties(
    BigDecimal cpShareRate,
    RoundingMode roundingMode
) {}

settlement:
  cp-share-rate: 0.6000
  rounding-mode: HALF_UP

record + 생성자 바인딩이면 불변이고, 타입 변환(문자열 → RoundingMode)도 스프링이 해준다. @ConfigurationPropertiesScan 한 줄이면 등록 끝.

얻는 것

1. 설정의 응집 — settlement 관련 값은 이 클래스에 다 있다
2. 컴파일 타임 안전 — 필드명이 곧 키라서 IDE가 자동완성·리팩터링을 해준다
3. 검증 — @Validated + @NotNull로 부팅 시점에 잡는다
4. 테스트 — 그냥 new SettlementProperties(...) 하면 된다

작은 프로젝트라도 설정이 도메인 개념이라면(수수료율, 정산 주기 같은) 처음부터 Properties 클래스로 시작하는 편이 낫다.