Spring Boot에서 @ConfigurationProperties와 @ConfigurationPropertiesScan 완벽 이해

이전에 진행한 프로젝트 코드에서 메인 클래스에 @SpringBootApplication 외에 @ConfigurationPropertiesScan가 붙어 있는 것을 보고,
“왜 @ConfigurationPropertiesScan이 필요할까?”라는 궁금증이 생겼습니다. 그래서 Spring Boot에서 설정 관련 기본 개념을 다시 정리해보았습니다.

 

Spring Boot 프로젝트를 진행하다 보면, application.yml 또는 application.properties에 작성한 설정 값을 POJO로 매핑하고 싶은 경우가 많습니다.
이때 사용하는 것이 바로 @ConfigurationProperties입니다.

 

하지만 중요한 점은, @ConfigurationProperties가 붙은 클래스는 자동으로 Spring Bean이 되지 않는다는 것입니다.
즉, 단순히 애너테이션을 붙이는 것만으로는 DI(@Autowired) 등에서 사용할 수 없습니다.

 

그래서 Spring Boot에서는 @ConfigurationPropertiesScan 을 사용하여 @ConfigurationProperties가 붙은 클래스를 스캔하고, Spring Bean으로 등록하도록 도와줍니다.

이를 통해 설정 파일의 값을 POJO에 안전하게 바인딩하고, 다른 컴포넌트에서 쉽게 주입받아 사용할 수 있습니다.

---

1. @ConfigurationProperties란?

@ConfigurationProperties는 설정 파일(yml/properties)의 값을 POJO로 바인딩하는 기능입니다.
예를 들어, Redis 서버 설정을 application.yml에 넣었다고 가정해봅시다.

application.yml

cache:
  host: localhost
  port: 6379
  timeout: 1000

CacheProperties.java

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "cache")
public class CacheProperties {
    private String host;
    private int port;
    private int timeout;

    // getters and setters
}

 

이제 CacheProperties 객체에는 yml의 값이 자동으로 매핑되기 위한 준비가 되었습니다.

---

2. 중요한 점: @ConfigurationProperties만 붙였다고 빈이 아니다!

제가 오해했던 부분이 바로 “@ConfigurationProperties가 붙은 클래스는 자동으로 스프링 빈이 된다”라는 생각입니다.
하지만 실제로는 단독으로 붙어있으면 빈으로 등록되지 않아 다른 컴포넌트에서 DI(@Autowired) 불가합니다.

따라서 빈으로 등록하는 것이 필요합니다.

---

3. @ConfigurationProperties를 스프링 빈으로 등록하는 3가지 방법

방법 A: @Component 사용

import org.springframework.stereotype.Component;
import org.springframework.boot.context.properties.ConfigurationProperties;

@Component
@ConfigurationProperties(prefix = "cache")
public class CacheProperties {
    private String host;
    private int port;
    private int timeout;
}

• 장점: 클래스만 붙이면 끝
• 단점: 설정 클래스와 컴포넌트 역할이 섞임

이 경우 @ConfigurationPropertiesScan 불필요 합니다. 이미 Bean으로 등록되었기 때문에 @SpringBootApplication 에 내장되어 있는 내장된 컴포넌트 스캔만으로 충분합니다.

---

방법 B: @EnableConfigurationProperties 사용

@ConfigurationProperties(prefix = "cache")
public class CacheProperties {
    private String host;
    private int port;
    private int timeout;
}

@SpringBootApplication
@EnableConfigurationProperties(CacheProperties.class)
public class MyApplication {}

• 장점: 설정 클래스와 일반 컴포넌트 분리 가능
• 단점: 클래스가 많아지면 매번 추가해야 함

이 경우도 @ConfigurationPropertiesScan 불필요합니다. @EnableConfigurationProperties 가 대신 그 일을 해주고 있기 때문이죠.

---

방법 C: @ConfigurationPropertiesScan 사용 (Spring Boot 2.2+)

@ConfigurationProperties(prefix = "cache")
public class CacheProperties {
    private String host;
    private int port;
    private int timeout;
}

@SpringBootApplication
@ConfigurationPropertiesScan("com.example.config")
public class MyApplication {}

• 지정한 패키지 내 모든 @ConfigurationProperties 클래스를 자동으로 스캔하여 빈으로 등록
• 유지보수가 편리 → 클래스 추가 시 MyApplication 수정 불필요

패키지를 지정하지 않으면 @SpringBootApplication이 선언된 패키지 이하를 기본 스캔합니다.

---

핵심 포인트

@ConfigurationProperties만 붙이면 POJO에 yml 값을 바인딩할 준비는 되지만, 스프링 빈으로 자동 등록되지는 않음 → DI 불가
@ConfigurationPropertiesScan으로 지정한 패키지에서 @ConfigurationProperties 클래스들을 스캔하여 Spring Bean으로 등록하도록 지시해야만 DI 시점에서 스프링이 Bean을 찾아 사용할 수 있습니다.

@ConfigurationPropertiesScan은 @ConfigurationProperties가 붙은 클래스들을 자동으로 스캔해 빈으로 등록해주는 기능으로,
클래스가 많거나 유지보수를 쉽게 하고 싶다면 현대적인 Spring Boot 설정 방식으로 권장됩니다.