🌿 스프링/김영한

4. 컴포넌트 스캔

le2donguk 2026. 2. 8. 01:57

 

등록해야 할 스프링 빈이 수십, 수백 개가 되면 일일이 등록하기도 귀찮고 , 설정 정보도 커지고, 누락하는 문제도 발생한다

그래서 스프링은 설정 정보가 없이도 자동으로 스프링 빈을 등록하는 컴포넌트 스캔이라는 기능을 제공한다

의존관계도 자동으로 주입하는 @Autowired 라는 기능도 제공한다

 

 

컴포넌트 스캔

 

컴포넌트 스캔은 지정한 패키지를 자동으로 탐색하여 특정 어노테이션이 붙은 클래스를 스프링 빈으로 등록하는 기능이다.
개발자가 설정 클래스에 직접 등록하지 않아도 자동으로 컨테이너에 포함된다.

 

동작 방식

  • 지정된 패키지부터 하위 패키지까지 탐색
  • 컴포넌트 계열 어노테이션이 붙은 클래스 발견
  • 스프링 빈으로 자동 등록

스캔 범위 지정 

basePackages

탐색 시작 패키지를 문자열로 지정 할 수 있다 

@ComponentScan(basePackages = "com.example.app")

 

 

basePackageClasses

특정 클래스가 속한 패키지를 기준으로 탐색을 시작할 수 있다

@ComponentScan(basePackageClasses = AppConfig.class)

 

 

별도로 탐색 시작 위치를 지정하지 않으면 @ComponentScan이 붙은 설정 클래스의 패키지가 시작 위치가 된다.

 

스프링 부트관례

보통  루트 디렉토리 에 @SpringBootApplication을 사용한다.

이 어노테이션에는 내부에는 @ComponentScan이 포함되어 있다. 그래서 따로 탐색 시작 위치를 지정하지 않았기에 루트 패키지가 컴포넌트 스캔의 시작 위치로 지정이 된다!
결 메인 애플리케이션 클래스를 루트 패키지에 두면 전체 하위 패키지가 자동으로 스캔된다.

 

컴포넌트 스캔 기본 대상

이 어노테이션이 붙은 클래스는 자동 스캔 대상이다.

  • @Component
  • @Controller
  • @Service
  • @Repository
  • @Configuration

이 어노테이션들은 내부적으로 @Component를 포함하는 메타 어노테이션 구조다.

 

스캔 필터

컴포넌트 스캔대상에 추가하거나 혹은 스캔 대상에서 제외되고 싶을 때 필터를 사용한다

includeFilters : 스캔 대상을 추가

excludeFilters : 스캔 대상에서 제외

 

예시)

@ComponentScan(
    includeFilters = @ComponentScan.Filter(
        type = FilterType.ANNOTATION,
        classes = MyIncludeComponent.class
    ),
    excludeFilters = @ComponentScan.Filter(
        type = FilterType.ANNOTATION,
        classes = MyExcludeComponent.class
    )
)

 


@Autowired

 

@Autowired는 스프링이 의존관계를 자동으로 주입해 주는 기능이다.
컨테이너에서 필요한 타입의 빈을 찾아 자동으로 연결한다.

 

동작 기준 

 

  1. 타입 기준으로 빈 검색
  2. 같은 타입이 여러 개면 이름 기준으로 추가 매칭
  3. 최종 후보 하나를 주입

 

 

중복 등록과 충돌

컴포넌트 스캔에서 같은 빈 이름을 등록하면 어떻게 될까?

  1. 자동 빈 등록 vs 자동 빈 등록
    → 이런 경우는 거의 없긴 한데 만약 충돌되면 ConfilctingBeanDefinitionException 예외 발생
  2. 자동 빈 등록 vs 수동 빈 등록
    예를 들어 한쪽은 @Component와 AppConfig의 ComponentScan으로 자동 등록을 이용했고
    다른 한쪽은 AppConfig에서 @Bean으로 똑같은 이름으로 수동 등록 했는데 충돌이 난 상황을 가정해보자

    스프링 부트는 수동 빈 등록과 자동 빈 등록이 충돌 나면 오류가 발생하도록 기본 값을 가지고 있다