전체 메뉴

테마

Chapter 03

IoC, DI, Bean

직접 객체를 만드는 코드의 한계를 살펴보고 Spring IoC 컨테이너의 생성자 주입, Bean 등록과 선택, Scope와 생명주기를 익힙니다.

난이도
입문
예상 학습
90분
Spring Boot 기준
Spring Boot 4.1.1
JDK 기준
JDK 21
최종 검토

전체 24개 Chapter 중 Chapter 03입니다. 예제 코드는 공개 저장소 spring-boot-curriculum의 examples/ch03-ioc-di-bean 폴더에서 확인할 수 있습니다.

Learning goals

오늘 배울 내용

  • IoC와 DI가 필요한 이유를 직접 new 하는 코드와 비교해 설명하기
  • @Component와 @Bean 등록 방식 및 Bean 이름 규칙 구분하기
  • @Primary, @Qualifier, List 주입으로 같은 타입의 구현 선택하기
  • singleton·prototype Scope와 Bean 생명주기 확인하기
  1. 직접 생성의 문제
  2. IoC와 DI 이해
  3. Bean 등록
  4. 구현 선택
  5. Scope 확인
  6. 생명주기 점검
이 Chapter의 진행 흐름

이 Chapter에서 완성할 것

앞의 두 Chapter에서 컨트롤러가 생성자로 Environment나 설정 객체를 받는 것을 계속 봤습니다. 누가 그 객체를 만들어서 넘겨주는 걸까요? 이 질문의 답이 스프링의 가장 중심에 있는 개념, IoC 컨테이너와 DI입니다.

Chapter를 마치면 아래 내용을 직접 만들고 확인한 상태가 됩니다.

만드는 것 설명
NotificationSender 알림 전송을 추상화한 인터페이스입니다. 구현은 이메일과 SMS 두 가지입니다.
OrderService 주문을 받아 알림을 보내는 서비스입니다. 구현 클래스를 모르고 인터페이스만 압니다.
GET /orders, GET /senders, GET /beans 어떤 구현이 선택되는지, 컨테이너에 어떤 Bean이 있는지 보여 주는 API입니다.
AppConfig, LifecycleRecorder @Bean 등록과 Bean 생명주기를 확인하는 예제입니다.
테스트 12건 연결, Scope, 생명주기, 컨테이너 없는 단위 테스트를 자동으로 검증합니다.

사전 지식은 Chapter 01 프로젝트 시작하기의 프로젝트 구조와 @RestController, Chapter 02 설정과 Profile의 생성자 기반 설정 주입, 그리고 Java의 인터페이스와 구현 클래스 개념입니다. 코드는 공개 저장소의 examples/ch03-ioc-di-bean 폴더에 있습니다. JDK 21과 Spring Boot 4.1.1을 기준으로 하며, 모든 명령은 저장소 루트에서 Gradle Wrapper로 실행합니다. 실행 결과는 컨테이너(JDK 21.0.11)에서 직접 얻은 값이고, Windows 실행은 검증하지 못했습니다.

객체를 직접 만들면 생기는 문제

주문 서비스가 알림을 보내야 한다고 해 봅시다. 가장 단순한 방법은 서비스 안에서 이메일 발송 객체를 직접 만드는 것입니다. 코드가 짧고 이해하기 쉬워서 처음에는 문제가 없어 보입니다. 하지만 요구가 하나만 바뀌어도 이 방식의 한계가 드러납니다.

이 절에서는 new로 객체를 고정했을 때 생기는 문제 두 가지를 확인하고, 인터페이스로 분리하는 첫 단계까지 갑니다. 스프링은 아직 등장하지 않습니다. 이 문제를 이해해야 스프링의 해법이 왜 필요한지 보입니다.

직접 만드는 코드

public class OrderService {
    private final EmailSender sender = new EmailSender();   // 구현 클래스에 고정

    public String place(String item) {
        return sender.send("order placed: " + item);
    }
}

new로 고정한 구조의 서비스는 구현 클래스를 직접 알아서, 구현을 바꾸려면 서비스를 고쳐야 합니다. 아래 “첫 단계: 인터페이스로 분리하기” 절에서 만들 구조의 서비스는 인터페이스만 알고, 어떤 구현이 들어올지는 서비스 바깥에서 정합니다.

OrderService가 EmailSender를 필요로 합니다. 이것을 의존한다고 말합니다. 위 코드는 의존 대상을 클래스 안에서 직접 정해 버렸다는 점이 문제입니다.

문제 1: 바꾸려면 서비스 코드를 고쳐야 한다

긴급 주문은 문자(SMS)로 보내자는 요구가 생겼다고 해 봅시다. OrderService 안의 new EmailSender()를 new SmsSender()로 바꾸거나, 두 객체를 모두 만들어 분기하는 코드를 서비스 안에 넣어야 합니다. 알림 방식이 바뀔 때마다 주문 로직이 같이 수정되고, 주문 로직이 틀어질 위험도 함께 커집니다.

문제 2: 테스트에서 진짜 전송을 피할 수 없다

서비스의 주문 로직만 검증하고 싶어도 EmailSender가 항상 같이 만들어집니다. 진짜 이메일 서버에 접속하는 클래스라면 테스트가 느려지고, 외부 장애에 따라 결과가 달라지며, 메일이 실제로 나갈 수도 있습니다. 가짜 객체로 바꿔 끼울 방법이 없습니다.

두 문제의 뿌리는 같습니다. 서비스가 “무엇을 쓸지”까지 정하고 있기 때문입니다.

첫 단계: 인터페이스로 분리하기

해법의 첫 단계는 “알림을 보낸다”는 역할을 인터페이스로 뽑는 것입니다.

/** 알림 전송 방식의 추상화. 호출하는 쪽은 구현 클래스를 알 필요가 없다. */
public interface NotificationSender {

    String channel();

    String send(String message);
}

이메일과 SMS는 이 인터페이스를 구현합니다.

public class EmailSender implements NotificationSender {
    @Override
    public String channel() { return "email"; }

    @Override
    public String send(String message) { return "[email] " + message; }
}

public class SmsSender implements NotificationSender {
    @Override
    public String channel() { return "sms"; }

    @Override
    public String send(String message) { return "[sms] " + message; }
}

그리고 서비스는 구현이 아니라 인터페이스에만 의존하도록 바꿉니다.

public class OrderService {
    private final NotificationSender sender;       // 구현 클래스를 모른다

    public OrderService(NotificationSender sender) {   // 밖에서 받는다
        this.sender = sender;
    }

    public String place(String item) {
        return sender.send("order placed: " + item);
    }
}

바뀐 점은 두 가지입니다.

  • 필드 타입이 EmailSender에서 NotificationSender로 올라갔습니다. 서비스는 “알림을 보낼 수 있는 무언가”만 압니다.
  • 객체를 new로 만들지 않고 생성자로 받습니다. 누가 어떤 구현을 넣을지는 서비스 바깥의 문제가 되었습니다.

이제 사용하는 쪽에서 선택합니다.

OrderService emailOrders = new OrderService(new EmailSender());
OrderService smsOrders   = new OrderService(new SmsSender());

서비스 코드는 한 줄도 바뀌지 않고 구현만 바뀝니다. 테스트에서는 가짜 구현을 넣을 수 있습니다.

NotificationSender fake = new NotificationSender() {
    public String channel() { return "fake"; }
    public String send(String message) { return "fake:" + message; }
};
OrderService service = new OrderService(fake);

아직 남은 문제

인터페이스로 분리하고 생성자로 받게 했지만, 누군가는 여전히 new EmailSender()를 해서 넘겨 줘야 합니다. 서비스가 열 개이고 각각 의존하는 객체가 여럿이면 객체를 만들고 연결하는 코드가 애플리케이션 시작 지점에 쌓입니다.

  • 어떤 순서로 만들어야 하는가 (A가 B를 필요로 하면 B를 먼저)
  • 같은 객체를 여러 곳이 공유할 것인가, 따로 만들 것인가
  • 환경에 따라 어느 구현을 쓸 것인가

이 “만들고 연결하는 일”을 코드가 아니라 컨테이너에 맡기는 것이 스프링의 IoC/DI입니다. 아래 “세 가지 용어” 절에서 이어집니다.

이 문제가 실제 프로젝트에서 커지는 모습

예제는 객체 하나라 가볍게 보이지만 실제 서비스에서는 이렇게 번집니다.

상황 new로 고정했을 때 인터페이스로 분리했을 때
알림 방식을 이메일에서 SMS로 교체 서비스 코드 수정, 같은 서비스를 쓰는 모든 곳 재검토 넘겨 주는 구현만 교체
서비스 단위 테스트 진짜 전송 객체가 함께 만들어져 느리고 불안정 가짜 구현을 넣어 빠르게 검증
구현 추가(푸시 알림) 분기 코드가 서비스 안에 늘어남 구현 클래스 하나를 추가
코드 읽기 서비스가 구현 세부(전송 방식)까지 알아야 함 서비스는 “알림을 보낸다”만 알면 됨

이 표의 마지막 줄이 중요합니다. 의존 대상을 인터페이스로 바꾸면 코드가 길어지는 대신 서비스가 알아야 하는 범위가 줄어듭니다.

확인 문제

  1. OrderService가 EmailSender에 의존한다는 말은 코드에서 무엇을 뜻하나요?
  2. 서비스 생성자가 인터페이스 타입 인자를 받으면 테스트에서 무엇이 쉬워지나요?
  3. 인터페이스로 분리해도 남는 “누군가는 new를 해야 한다”는 문제를 이 과정은 어떻게 해결하나요?

답: 1) 클래스 안에 EmailSender 타입의 필드나 new EmailSender()가 있다는 뜻입니다. 2) 가짜 구현을 넘겨 외부 의존 없이 서비스 로직만 검증할 수 있습니다. 3) 스프링 컨테이너가 객체를 만들고 연결합니다. 아래 “세 가지 용어” 절에서 이어집니다.

직접 해 보기

  1. 위 인터페이스와 구현 클래스를 스프링 없이 일반 Java 프로젝트에 만들어 보세요. main에서 이메일과 SMS 서비스를 각각 만들어 호출합니다.
  2. 세 번째 구현 PushSender를 추가하되, OrderService는 수정하지 않고 main만 바꿔 보세요.
  3. 가짜 구현을 만들어 OrderService의 결과 문자열을 확인하는 JUnit 테스트를 써 보세요. 진짜 전송 클래스 없이 테스트가 되는지 확인합니다.

판정 기준: 1번은 서비스가 늘수록 main의 연결 코드가 길어지는 것이 보이면 됩니다. 2번은 OrderService를 한 줄도 건드리지 않았다면 성공입니다. 3번은 가짜 구현이 "fake:order placed: book"을 돌려주게 하고 assertEquals로 확인해, 진짜 EmailSender 없이 통과하면 성공입니다.

IoC와 DI, 컨테이너가 하는 일

앞의 “첫 단계: 인터페이스로 분리하기” 절에서 서비스가 구현을 new로 만들지 않고 생성자로 받도록 바꿨습니다. 하지만 누군가는 그 객체를 만들어서 넘겨줘야 했습니다. 이 절에서는 그 일을 맡는 스프링 컨테이너와, 그 방식을 가리키는 용어 IoC, DI, Bean을 정리합니다.

용어는 어렵게 들리지만 인터페이스로 분리한 코드를 이해했다면 이미 절반은 알고 있습니다. 용어를 정확히 붙이는 것이 이 절의 목표입니다.

세 가지 용어

  • IoC(Inversion of Control, 제어의 역전): 객체를 만들고 연결하는 일(제어)을 코드가 아니라 스프링 컨테이너가 맡는 구조입니다. “제어가 뒤집혔다”는 말은, 원래 내 코드가 객체를 만들었는데 이제는 컨테이너가 만든다는 뜻입니다.
  • DI(Dependency Injection, 의존성 주입): 필요한 객체를 직접 만들지 않고 밖에서 넣어 받는 방식입니다. IoC를 실현하는 구체적인 방법입니다. 인터페이스로 분리할 때 만든 OrderService(NotificationSender sender) 생성자가 DI의 한 형태입니다.
  • Bean: 컨테이너가 만들고 관리하는 객체입니다. 우리가 new로 만든 객체는 Bean이 아니고, 컨테이너가 만든 객체만 Bean입니다.

세 용어를 한 문장으로 이으면 이렇습니다. IoC 컨테이너가 Bean을 만들고, DI로 서로 연결해 준다.

컨테이너는 시작할 때 무엇을 하나

서버가 켜질 때 컨테이너(ApplicationContext)가 하는 일은 대략 이 순서입니다.

  1. 컴포넌트 스캔: 시작 클래스의 패키지 아래에서 @Component가 붙은 클래스를 찾습니다. Chapter 01에서 본 @SpringBootApplication 안의 @ComponentScan이 하는 일입니다.
  2. @Bean 메서드 실행: @Configuration 클래스 안의 @Bean 메서드가 돌려주는 객체를 등록합니다.
  3. 의존 관계 분석: 각 Bean의 생성자를 보고 “이 Bean을 만들려면 어떤 타입의 Bean이 필요한가”를 파악합니다.
  4. Bean 생성: 필요한 것이 먼저 만들어지도록 순서를 정해 생성자를 호출하고, 초기화 메서드(@PostConstruct)를 실행합니다.
  5. 종료: 컨텍스트가 닫힐 때 소멸 전 메서드(@PreDestroy)를 실행합니다.

개발자가 신경 쓰는 것은 “무엇이 무엇을 필요로 하는가”를 생성자에 적는 일까지입니다. 만드는 순서, 연결, 공유 여부는 컨테이너의 몫입니다.

생성자 주입

OrderService는 의존하는 객체를 생성자 인자로 받습니다. 이것이 생성자 주입이고, 스프링이 지원하는 주입 방식 중 이 과정의 기본입니다.

@Service
public class OrderService {

    private final NotificationSender sender;
    private final NotificationSender urgentSender;
    private final List<NotificationSender> allSenders;

    public OrderService(
            NotificationSender sender,
            @Qualifier("smsSender") NotificationSender urgentSender,
            List<NotificationSender> allSenders) {
        this.sender = sender;
        this.urgentSender = urgentSender;
        this.allSenders = allSenders;
    }
    // ...
}

주목할 점이 몇 가지 있습니다.

  • 생성자가 하나뿐이면 @Autowired를 쓰지 않아도 됩니다. 스프링이 그 생성자를 사용합니다.
  • 필드를 final로 둘 수 있어 한 번 정해지면 바뀌지 않습니다.
  • Spring 없이도 new OrderService(a, b, list)로 만들 수 있어 단위 테스트가 쉽습니다.

주입 방식에는 필드에 직접 @Autowired를 붙이는 방식이나 setter 방식도 있습니다. 이 과정에서 쓰지 않는 이유는 필드를 final로 둘 수 없고, 스프링 없이 객체를 만들어 테스트하기 어렵기 때문입니다. 그 두 방식의 동작은 이 Chapter에서 확인하지 않았습니다.

컨테이너가 보는 의존 관계

생성자 인자 타입에 맞는 Bean이 하나면 그대로 주입됩니다. 둘 이상이면 @Primary, @Qualifier, 이름 같은 단서로 하나를 고르고, 단서가 없으면 기동이 실패합니다. 고르는 방법은 아래 “하나의 생성자에서 세 방식을 모두 쓴다” 절에서 다룹니다.

이 구조의 가장 큰 이득은, 구현을 바꾸고 싶을 때 서비스 코드는 두고 Bean만 바꾸면 된다는 점입니다. 이메일 구현을 SMS로 바꾸려면 서비스의 생성자 인자에 어떤 Bean을 연결할지만 컨테이너 설정에서 바꿉니다.

이 Chapter 예제의 의존 관계

컨테이너가 만든 Bean들은 이렇게 연결됩니다. 컨트롤러가 서비스를, 서비스가 알림 구현들을 필요로 합니다. 컨테이너는 이 의존 관계를 보고 EmailSender와 SmsSender를 먼저 만들고, OrderService, BeanController 순서로 만듭니다.

생성자 주입을 쓰는 이유

항목 생성자 주입 필드 주입
final 필드 가능 불가능
스프링 없이 new로 생성 가능(인자로 넘김) 어려움(필드가 private이라 값을 넣을 방법이 없음)
필요한 의존성 확인 생성자 인자에 모두 드러남 필드에 흩어져 놓치기 쉬움
의존성이 너무 많을 때 인자가 길어져 설계를 되돌아보게 됨 늘어나도 눈에 덜 띔

생성자 인자가 늘어나는 것이 불편해 보여도, 그것은 클래스가 너무 많은 일을 하고 있다는 신호입니다. 필드 주입은 그 신호를 가려 버립니다.

자주 하는 오해

오해 사실
스프링이 new를 없애 준다 컨테이너가 대신 호출할 뿐, 객체는 여전히 만들어집니다.
Bean은 특별한 클래스다 평범한 클래스입니다. 컨테이너가 만들고 관리한다는 점만 다릅니다.
@Autowired를 꼭 붙여야 한다 생성자가 하나면 생략할 수 있습니다.

확인 문제

  1. IoC와 DI의 관계를 한 문장으로 말해 보세요.
  2. 컨테이너가 OrderService를 만들기 전에 반드시 먼저 만들어야 하는 것은 무엇인가요?

답: 1) IoC는 “객체를 만들고 연결하는 제어를 컨테이너가 가진다”는 구조이고, DI는 그것을 생성자 등으로 객체를 밖에서 넣어 주는 방식으로 구현한 것입니다. 2) 생성자 인자에 필요한 NotificationSender 구현들(EmailSender, SmsSender)입니다.

직접 해 보기

  1. OrderService의 생성자 위에 @Autowired를 붙여도 동작이 같은지 확인해 보세요(생성자가 하나뿐이므로 같아야 합니다).
  2. EmailSender에서 @Component를 지우면 서버가 어떤 오류로 멈추는지 먼저 예측해 보세요. Bean이 등록되지 않았을 때의 실제 메시지는 아래 “오류 3: Bean으로 등록되지 않았다” 절에 있습니다.
  3. Ch03Application의 main에서 SpringApplication.run이 돌려주는 값(ConfigurableApplicationContext)을 받아 getBeanDefinitionNames()를 출력해 보세요. 컨테이너에 어떤 Bean이 있는지 볼 수 있습니다.

Bean 등록: @Component와 @Bean

컨테이너가 객체를 관리하려면 먼저 “이 클래스를 Bean으로 등록해 달라”는 표시가 필요합니다. 표시하는 방법은 크게 두 가지입니다. 내가 만든 클래스에는 애노테이션을 붙이고, 내가 고칠 수 없는 클래스는 메서드로 등록합니다.

이 절에서는 두 방법을 나란히 놓고, Bean 이름이 어떻게 정해지는지, 그리고 컴포넌트 스캔이 어디까지 찾아다니는지를 테스트로 확인합니다.

방법 1: 클래스에 애노테이션 붙이기

EmailSender와 SmsSender는 우리가 만든 클래스이므로 클래스 위에 @Component를 붙이면 됩니다.

Bean이 컨테이너에 올라가는 길은 두 가지이고, 두 길 모두 결과는 같습니다. 컨테이너가 보관한 Bean을 생성자 인자 타입으로 찾아 넣어 줍니다. 차이는 “누가 객체를 만드는가”입니다. 스캔은 컨테이너가 기본 생성자 규칙으로 만들고, @Bean은 메서드 코드가 직접 만듭니다.

@Component
@Order(2)
public class SmsSender implements NotificationSender {
    @Override public String channel() { return "sms"; }
    @Override public String send(String message) { return "[sms] " + message; }
}

@Component를 붙이면 컴포넌트 스캔이 이 클래스를 찾아 Bean으로 등록합니다. 역할을 드러내고 싶을 때는 같은 기능의 이름 있는 애노테이션을 씁니다.

애노테이션 쓰는 곳 비고
@Component 특별한 역할이 없는 일반 구성 요소 기본형
@Service 업무 로직을 담은 서비스 OrderService에 사용
@RestController 웹 요청을 받는 컨트롤러 BeanController에 사용
@Repository 데이터 접근 계층 이후 Chapter에서 사용

이름이 다를 뿐 모두 @Component를 포함합니다. 동작상 차이는 거의 없고, 읽는 사람에게 계층을 알려 주는 표시입니다.

방법 2: @Bean 메서드로 등록하기

java.time.Clock은 라이브러리(JDK) 클래스라서 소스를 열어 @Component를 붙일 수 없습니다. 이럴 때는 설정 클래스 안의 메서드가 객체를 만들어 돌려주게 하고, 그 반환값을 Bean으로 등록합니다.

@Configuration
public class AppConfig {

    @Bean
    public Clock systemClock() {
        return Clock.systemUTC();
    }
}

주요 코드 설명

  • @Configuration: 이 클래스가 Bean 정의를 담은 설정 클래스임을 알립니다. 이 클래스 자신도 Bean(appConfig)이 됩니다.
  • @Bean: 이 메서드가 돌려주는 객체를 컨테이너에 등록합니다. 메서드 안에서 new나 팩토리를 마음대로 쓸 수 있습니다.
  • 반환 타입 Clock이 Bean의 기준 타입입니다. 다른 곳에서 Clock을 생성자로 요청하면 이 객체가 주입됩니다.

두 방법의 선택 기준은 간단합니다.

상황 선택
내가 만든 클래스 @Component 계열
라이브러리 클래스, 생성 과정에 코드가 필요한 객체 @Bean 메서드

Bean 이름은 어떻게 정해지나

Bean에는 이름이 붙고, 이름은 같은 컨테이너 안에서 유일해야 합니다.

등록 방법 이름 규칙 이 예제의 이름
@Component 계열 클래스명의 첫 글자를 소문자로 emailSender, smsSender, orderService, beanController
@Bean 메서드 메서드 이름 systemClock
@Configuration 클래스 클래스명 첫 글자를 소문자로 appConfig

이름은 아래 “2. @Qualifier: 이름으로 콕 집는다” 절에서 Bean을 지정할 때 쓰므로 규칙을 기억해 두세요. 이름을 직접 정하고 싶으면 @Component("mailer")나 @Bean("clock")처럼 값을 줍니다.

컴포넌트 스캔은 어디까지 찾나

Chapter 01에서 시작 클래스의 패키지 아래만 훑는다고 했습니다. 이 Chapter는 그 말을 눈으로 확인하려고 일부러 범위 밖에 클래스를 하나 두었습니다.

package com.jqdom.curriculum.outside;      // 시작 클래스(com.jqdom.curriculum.ch03) 바깥

@Component
public class OutsideComponent {
}

@Component가 붙어 있어도, 시작 클래스 Ch03Application은 com.jqdom.curriculum.ch03 패키지에 있으므로 outside 패키지는 스캔 대상이 아닙니다. 테스트로 확인합니다.

@Test
void componentOutsideScanPackageIsNotRegistered() {
    assertEquals(0, context.getBeanNamesForType(OutsideComponent.class).length);
}

getBeanNamesForType이 빈 배열을 돌려주면 컨테이너에 그 타입의 Bean이 없다는 뜻입니다. 이 테스트가 통과합니다. 범위 밖 클래스를 쓰고 싶다면 두 가지 길이 있습니다. 클래스를 스캔 범위 안으로 옮기거나, 설정 클래스에서 @Import(OutsideComponent.class)처럼 명시적으로 불러옵니다. 이 Chapter에서는 @Import를 실행해 보지 않았으므로 개념만 소개합니다.

등록된 Bean을 눈으로 확인하기

컨테이너에 실제로 어떤 Bean이 올라갔는지 BeanController의 GET /beans로 봅니다. 이 Chapter 패키지에서 온 Bean만 이름순으로 돌려주도록 만들었습니다. 전체 실행 결과는 아래 “서버 실행과 요청” 절에서 보여 줍니다. 여기서는 규칙의 결과만 짚습니다.

["appConfig","beanController","ch03Application","emailSender","lifecycleRecorder","orderService","smsSender","systemClock"]
  • 시작 클래스 ch03Application도 Bean입니다. @SpringBootApplication이 설정 클래스를 포함하기 때문입니다.
  • systemClock은 @Bean 메서드 이름 그대로입니다.
  • outsideComponent는 목록에 없습니다.

따라 하기: Bean 목록으로 확인하기

  1. ./gradlew :examples:ch03-ioc-di-bean:bootRun으로 서버를 켭니다.
  2. curl http://localhost:8080/beans를 호출합니다.
  3. 응답 목록에 emailSender, smsSender, orderService, systemClock, appConfig가 있고 outsideComponent가 없으면 성공입니다.
  4. OutsideComponent를 com.jqdom.curriculum.ch03 패키지 아래로 옮겨 다시 실행하면 목록에 나타나는지 확인합니다. 스캔 범위가 어디까지인지 직접 보는 실험입니다.

자주 하는 실수

실수 증상 해결
@Component를 붙였는데 패키지가 시작 클래스 바깥 Bean이 등록되지 않아 주입 시 NoSuchBeanDefinitionException 시작 클래스 패키지 아래로 이동하거나 @Import 사용
@Bean 메서드가 @Configuration 없이 일반 클래스에 있음 등록 방식이 의도와 달라질 수 있음 설정 클래스에는 @Configuration 사용
같은 이름의 Bean을 두 곳에서 등록 Boot는 기본적으로 Bean 덮어쓰기를 허용하지 않아 기동이 실패 Bean 이름 규칙을 확인하고 이름을 구분

Bean 이름이 필요한 경우(@Qualifier)는 아래 “2. @Qualifier: 이름으로 콕 집는다” 절에서, 등록하지 않았을 때의 실제 오류 메시지는 아래 “오류 3: Bean으로 등록되지 않았다” 절에서 확인합니다.

확인 문제

  1. 내가 만든 클래스와, 소스를 고칠 수 없는 외부 라이브러리 클래스는 각각 어떤 방법으로 Bean으로 등록하나요?
  2. 컴포넌트 스캔 범위 밖 패키지의 @Component 클래스는 Bean이 되나요?

답: 1) 내 클래스는 @Component 계열 애노테이션, 고칠 수 없는 클래스는 @Configuration 안의 @Bean 메서드로 등록합니다. 2) 되지 않습니다. 스캔은 시작 클래스의 패키지 아래만 찾습니다.

직접 해 보기

  1. OutsideComponent를 ch03 패키지 아래로 옮기고 /beans를 호출해 outsideComponent가 나타나는지 확인하세요. 위 테스트는 실패해야 합니다.
  2. AppConfig에 @Bean public String appName() { return "ch03"; }를 추가해 보세요. /beans에 appName이 나타나는지 봅니다. 이름이 메서드 이름인지 확인하는 실험입니다.
  3. SmsSender를 @Component("mobile")로 바꾸고 서버를 켜 보세요. 기동 오류가 난다면 메시지가 어떤 이름을 말하는지 읽어 보세요(@Qualifier("smsSender")가 더는 맞지 않습니다).

같은 타입이 둘일 때: @Primary와 @Qualifier

NotificationSender 구현이 이메일과 SMS 두 개가 되었습니다. 서비스가 생성자에서 NotificationSender 타입을 요청하면 컨테이너는 어느 것을 넣어야 할까요? 둘 중 하나를 고를 단서가 없으면 서버는 기동하지 못합니다.

이 절에서는 단서를 주는 세 가지 방법, @Primary, @Qualifier, List 주입을 하나의 생성자에서 모두 써 봅니다.

하나의 생성자에서 세 방식을 모두 쓴다

public OrderService(
        NotificationSender sender,                              // @Primary인 EmailSender
        @Qualifier("smsSender") NotificationSender urgentSender, // 이름으로 지정
        List<NotificationSender> allSenders) {                  // 해당 타입의 Bean 전부
    this.sender = sender;
    this.urgentSender = urgentSender;
    this.allSenders = allSenders;
}

생성자 인자마다 컨테이너는 이 순서로 Bean을 고릅니다. @Qualifier가 있으면 이름이 일치하는 Bean을, List 타입이면 그 타입의 Bean 전부를 @Order 순서로, 후보가 하나뿐이면 그 Bean을, 후보가 여럿이면 @Primary가 붙은 Bean을 고릅니다. @Primary도 없으면 NoUniqueBeanDefinitionException으로 기동이 실패합니다. 실제 내부 구현은 더 세부적이지만, 이 예제의 세 인자가 어떤 경로로 결정되는지 이해하는 데는 이 순서면 충분합니다.

세 인자는 모두 NotificationSender 타입을 요청하지만 단서가 다릅니다.

1. @Primary: 기본값을 정한다

EmailSender 클래스에 @Primary가 붙어 있습니다.

@Component
@Primary
@Order(1)
public class EmailSender implements NotificationSender { ... }

같은 타입이 여럿일 때 단서 없이 요청하면 @Primary 쪽이 선택됩니다. 첫 번째 인자 sender에 EmailSender가 들어옵니다. “대부분은 이걸 쓰고, 예외일 때만 다른 걸 쓴다”는 기본값을 정할 때 알맞습니다.

2. @Qualifier: 이름으로 콕 집는다

두 번째 인자에는 @Qualifier("smsSender")가 붙어 있습니다. 괄호 안은 Bean 이름이고, 이름은 앞의 “Bean 이름은 어떻게 정해지나” 절의 규칙(SmsSender → smsSender)으로 정해집니다. @Primary가 있어도 @Qualifier가 있으면 지정한 쪽이 이깁니다. 그래서 urgentSender에는 SmsSender가 들어옵니다.

3. List: 전부 받는다

세 번째 인자는 List<NotificationSender>입니다. 타입을 List로 요청하면 컨테이너는 그 타입의 Bean을 모두 모아 넣어 줍니다. 구현이 늘어도 서비스 코드는 바뀌지 않으므로 “모든 구현을 돌며 처리”하는 구조에 씁니다. 이 아이디어는 Chapter 16 Composite·Strategy와 모듈 경계의 전략 패턴과 Composite에서 크게 쓰입니다.

List의 순서는 @Order 값(작을수록 앞)을 따릅니다. EmailSender가 @Order(1), SmsSender가 @Order(2)이므로 [email, sms] 순서입니다. @Order는 순서만 정하고 어느 것을 우선 선택할지는 정하지 않는다는 점이 @Primary와 다릅니다.

서비스에서의 사용

public String place(String item, boolean urgent) {
    NotificationSender target = urgent ? urgentSender : sender;
    return target.send("order placed: " + item);
}

public List<String> channels() {
    return allSenders.stream().map(NotificationSender::channel).toList();
}

place는 긴급 여부에 따라 SMS 또는 기본(이메일) 발송기를 씁니다. 서비스는 EmailSender나 SmsSender라는 이름을 코드에 한 번도 적지 않았습니다. 구현이 바뀌어도 이 메서드는 그대로입니다.

세 방식 비교

방식 의미 쓰는 때
@Primary 단서가 없을 때의 기본값 대부분 한 구현을 쓰는 경우
@Qualifier("이름") 이 이름의 Bean을 지정 특정 구현이 꼭 필요한 경우
List<타입> 모든 구현을 받음 여러 구현을 모두 쓰거나 키로 골라 쓰는 경우

세 가지는 함께 쓸 수 있습니다. 위 생성자가 그 예입니다. 생성자 인자 이름을 Bean 이름과 같게(NotificationSender smsSender) 쓰면 @Qualifier 없이도 이름으로 맞춰지는 경우가 있지만, 컴파일 옵션에 따라 달라질 수 있어 이 Chapter에서는 확인하지 않았습니다. 명시적인 @Qualifier가 안전합니다.

단서가 없으면

@Primary를 지우고 @Qualifier도 없이 NotificationSender를 요청하면 컨테이너는 고를 수 없어 기동이 멈춥니다. 실제 오류 메시지는 아래 “오류 1: expected single matching bean but found 2” 절에서 재현한 값을 보여 줍니다.

따라 하기: 선택 결과 확인

  1. 서버를 켠 뒤 아래 세 요청을 보냅니다.
curl "http://localhost:8080/orders?item=book"
curl "http://localhost:8080/orders?item=book&urgent=true"
curl http://localhost:8080/senders
  1. 응답이 [email] order placed: book, [sms] order placed: book, ["email","sms"] 순서로 나오면 성공입니다.
  2. EmailSender의 @Order(1)과 SmsSender의 @Order(2)를 서로 바꿔 다시 /senders를 호출하면 ["sms","email"]로 바뀌는지 확인합니다.

선택 기준 정리

질문 답
대부분 같은 구현을 쓰고 가끔만 다른 구현을 쓴다 @Primary로 기본을 정하고 예외만 @Qualifier
구현마다 이름이 의미 있다 @Qualifier로 명시
모든 구현을 순회하거나 키로 골라 쓴다 List<타입> 또는 Map<String, 타입> 주입

자주 하는 실수

실수 증상 해결
@Primary 없이 같은 타입 구현을 둘 이상 등록 expected single matching bean but found 2 @Primary 또는 @Qualifier 추가
@Qualifier 이름 철자 오류 expected at least 1 bean which qualifies 앞의 “Bean 이름은 어떻게 정해지나” 절의 규칙과 비교
@Order가 없는 List의 순서를 믿음 순서가 보장되지 않아 환경에 따라 달라 보일 수 있음 순서가 중요하면 @Order 명시

확인 문제

  1. 같은 타입의 Bean이 둘 이상인데 아무 단서도 주지 않으면 어떻게 되나요?
  2. @Primary, @Qualifier, List 주입은 각각 어떤 방식으로 하나 또는 여러 개를 고르나요?

답: 1) 기동이 실패합니다. 2) @Primary는 기본값으로 하나를 지정하고, @Qualifier는 이름으로 지정하며, List는 전부 받습니다.

직접 해 보기

  1. OrderService의 첫 번째 인자 위에 @Qualifier("smsSender")를 붙이고 /orders?item=book을 호출해 보세요. 이메일이 아니라 SMS 응답이 오는지 확인합니다.
  2. EmailSender와 SmsSender의 @Order 값을 서로 바꾸고 /senders의 순서가 어떻게 달라지는지 보세요.
  3. 세 번째 구현 PushSender(@Component, @Order(3))를 추가해 서비스 코드를 한 줄도 바꾸지 않고 /senders에 push가 나타나는지 확인하세요.

실행해서 Bean 확인하기

지금까지는 코드를 읽기만 했습니다. 이 절에서는 서버를 켜서 지금까지 본 규칙이 실제 응답으로 나오는지 확인하고, 같은 서비스를 컨테이너 없이 테스트하는 방법을 봅니다.

서버 실행과 요청

./gradlew :examples:ch03-ioc-di-bean:bootRun

요청은 주입된 객체를 거쳐 응답이 됩니다. urgent가 true이면 서비스는 @Qualifier로 받은 SMS 구현을, 아니면 @Primary인 이메일 구현을 씁니다. 컨트롤러는 어떤 구현이 쓰였는지 모릅니다.

Windows에서는 gradlew.bat을 씁니다. 다른 터미널에서 요청합니다.

curl "http://localhost:8080/orders?item=book"
curl "http://localhost:8080/orders?item=book&urgent=true"
curl http://localhost:8080/senders
curl http://localhost:8080/beans

실행 결과

[email] order placed: book
[sms] order placed: book
["email","sms"]
["appConfig","beanController","ch03Application","emailSender","lifecycleRecorder","orderService","smsSender","systemClock"]

각 줄이 앞에서 본 규칙을 증명합니다.

응답 의미
[email] order placed: book 단서 없는 요청에는 @Primary인 EmailSender가 쓰였습니다.
[sms] order placed: book urgent=true일 때 @Qualifier("smsSender")로 받은 SmsSender가 쓰였습니다.
["email","sms"] List로 둘 다 받았고 @Order 순서입니다.
/beans 목록 이름 규칙대로 등록되었고 outsideComponent는 없습니다.

컨트롤러 코드의 핵심

@GetMapping("/orders")
public String order(@RequestParam String item,
                    @RequestParam(defaultValue = "false") boolean urgent) {
    return orderService.place(item, urgent);
}

컨트롤러도 생성자에서 OrderService를 받습니다. ApplicationContext와 ConfigurableListableBeanFactory도 생성자 인자로 요청하는데, 컨테이너 자신도 주입 대상이 될 수 있기 때문입니다. /beans는 이 둘로 등록된 Bean 이름을 읽어 이 Chapter 패키지에서 온 것만 골라냅니다.

MockMvc 테스트

같은 확인을 테스트로 남겨 두면 수정할 때마다 자동으로 검증됩니다.

@SpringBootTest
@AutoConfigureMockMvc
class BeanWiringTests {

    @Test
    void primaryAndQualifierSelectSender() throws Exception {
        mockMvc.perform(get("/orders").param("item", "book"))
                .andExpect(content().string("[email] order placed: book"));

        mockMvc.perform(get("/orders").param("item", "book").param("urgent", "true"))
                .andExpect(content().string("[sms] order placed: book"));
    }

    @Test
    void listInjectionCollectsAllImplementationsInOrder() throws Exception {
        mockMvc.perform(get("/senders"))
                .andExpect(jsonPath("$", contains("email", "sms")));
    }
}

MockMvc 사용법은 Chapter 01의 “MockMvc로 서버 없이 컨트롤러를 확인합니다” 절과 같습니다. 새로 나온 것은 contains(...)로 JSON 배열의 순서까지 검증한 점입니다. 순서를 신경 쓰지 않으려면 hasItems를 씁니다.

컨테이너 없는 단위 테스트

생성자 주입의 이점은 여기서 드러납니다. OrderService는 스프링 없이도 new로 만들 수 있습니다.

class OrderServiceUnitTests {

    @Test
    void usesDefaultSenderUnlessUrgent() {
        NotificationSender normal = fake("normal");
        NotificationSender urgent = fake("urgent");
        OrderService service = new OrderService(normal, urgent, List.of(normal, urgent));

        assertEquals("normal:order placed: book", service.place("book", false));
        assertEquals("urgent:order placed: book", service.place("book", true));
        assertEquals(List.of("normal", "urgent"), service.channels());
    }
}

@SpringBootTest가 없으므로 컨텍스트를 띄우지 않아 빠릅니다. 진짜 이메일이나 SMS 구현이 필요 없고, 가짜 구현이 정해 둔 문자열로 서비스 로직만 검증합니다. 앞의 “문제 2: 테스트에서 진짜 전송을 피할 수 없다” 절에서 말한 “테스트에서 바꿔 끼울 수 없다”는 문제가 풀렸습니다. 단위 테스트와 슬라이스 테스트는 Chapter 19 단위·슬라이스 테스트에서 더 체계적으로 다룹니다.

테스트 실행 결과

./gradlew :examples:ch03-ioc-di-bean:build

이 Chapter의 테스트 12건이 모두 통과했습니다.

테스트 클래스 건수 내용
Ch03ApplicationTests 1 컨텍스트 로딩
BeanWiringTests 8 선택 결과, 이름 규칙, 스캔 범위, 생명주기
OrderServiceUnitTests 1 컨테이너 없는 단위 테스트
ScopeAndLifecycleTests 2 Scope, @PreDestroy

성공 판정 기준

확인 기대 결과
GET /orders?item=book [email] order placed: book
GET /orders?item=book&urgent=true [sms] order placed: book
GET /senders ["email","sms"]
GET /beans outsideComponent가 목록에 없음
./gradlew :examples:ch03-ioc-di-bean:build 테스트 12건 통과

자주 하는 실수

실수 증상 해결
urgent 값을 maybe처럼 불리언으로 바꿀 수 없는 값으로 보냄 400 오류 true 또는 false 사용
서버를 켠 채로 같은 포트로 다시 실행 Port 8080 was already in use 이전 서버 종료
단위 테스트에 @SpringBootTest를 붙임 컨텍스트를 띄워 느려짐 컨테이너 없이 new로 만들어 테스트

확인 문제

  1. /orders, /senders, /beans 응답은 각각 무엇을 보여 주나요?
  2. 생성자 주입 덕분에 얻는 테스트상의 이점은 무엇인가요?

답: 1) /orders는 @Primary와 @Qualifier의 선택, /senders는 List 주입, /beans는 이름 규칙과 스캔 범위를 보여 줍니다. 2) 컨테이너 없이 new로 서비스를 만들고 가짜 구현을 넣어 테스트할 수 있습니다.

직접 해 보기

  1. /orders에 item 없이 요청하면 어떤 상태 코드가 오는지 확인하세요(필수 파라미터이므로 400이 예상됩니다).
  2. OrderServiceUnitTests에서 channels()의 기대값을 틀리게 바꾸고 실패 메시지를 읽어 보세요.
  3. /beans의 응답에 systemClock이 포함되는 것을 확인한 뒤, 이 Bean의 실제 타입을 context.getBean("systemClock").getClass()로 출력해 보세요.

Scope와 Bean 생명주기

컨테이너가 Bean을 만든다고 했는데, 같은 Bean을 요청할 때마다 새로 만들까요, 하나를 돌려 쓸까요? 그리고 Bean은 언제 초기화되고 언제 정리될까요? 이 두 질문이 Scope와 생명주기입니다.

이 절에서는 스프링 부트 없이 컨테이너만 직접 만드는 테스트로 두 가지를 확인합니다. 작은 컨테이너로 보면 규칙이 더 선명하게 보입니다.

Scope: 인스턴스를 몇 개 만드나

Scope 의미
singleton (기본) 컨테이너 안에 하나만 만들고 모든 요청에 같은 객체를 줍니다.
prototype 요청할 때마다 새 객체를 만듭니다.

singleton은 모든 요청이 같은 객체를 공유하고, prototype은 꺼낼 때마다 새 객체가 만들어집니다.

웹 요청마다 만드는 request Scope 같은 것도 있지만 이 Chapter에서는 다루지 않습니다.

테스트로 확인하기

스프링 부트 없이 AnnotationConfigApplicationContext로 컨테이너만 만듭니다.

@Component
static class SingletonBean { }

@Component
@Scope("prototype")
static class PrototypeBean { }

@Test
void singletonReturnsSameInstancePrototypeReturnsNewOne() {
    try (var ctx = new AnnotationConfigApplicationContext(SingletonBean.class, PrototypeBean.class)) {
        assertSame(ctx.getBean(SingletonBean.class), ctx.getBean(SingletonBean.class));
        assertNotSame(ctx.getBean(PrototypeBean.class), ctx.getBean(PrototypeBean.class));
    }
}

주요 코드 설명

  • AnnotationConfigApplicationContext: 스프링 컨테이너를 직접 만드는 클래스입니다. 인자로 Bean이 될 클래스를 넘깁니다.
  • @Scope("prototype"): 기본값(singleton)을 바꿉니다.
  • assertSame: 두 참조가 같은 객체여야 통과합니다. assertNotSame는 다른 객체여야 통과합니다.
  • try (var ctx = ...): 컨텍스트는 닫을 수 있는 자원이어서 블록을 벗어나면 자동으로 닫힙니다.

이 테스트가 통과합니다. singleton은 두 번 꺼내도 같은 객체이고, prototype은 매번 다른 객체입니다. 같은 확인을 BeanWiringTests에서는 실제 앱의 OrderService로도 했습니다(singletonIsSharedByDefault).

singleton을 쓸 때 주의할 점

기본이 singleton이라는 말은 서비스 하나를 모든 요청이 공유한다는 뜻입니다. 그래서 서비스나 컨트롤러에 요청마다 달라지는 값을 필드로 두면 안 됩니다. 다른 요청의 값과 섞이기 때문입니다. 이 Chapter의 OrderService는 필드가 모두 final인 의존 객체뿐이어서 안전합니다. 요청별 상태는 메서드 인자와 지역 변수로 다루세요.

생명주기: 만들고, 초기화하고, 정리한다

Bean 하나의 일생은 생성자 호출, 의존성 주입 완료, @PostConstruct 실행, 사용, 컨텍스트 종료 시 @PreDestroy 실행 순서입니다.

LifecycleRecorder는 각 시점을 기록하도록 만들었습니다.

@Component
public class LifecycleRecorder {

    private final List<String> events = new ArrayList<>();

    public LifecycleRecorder() {
        events.add("constructor");
    }

    @PostConstruct
    void init() {
        events.add("postConstruct");
    }

    @PreDestroy
    void destroy() {
        events.add("preDestroy");
    }

    public List<String> events() {
        return Collections.unmodifiableList(events);
    }
}
  • @PostConstruct: 생성자가 끝나고 의존성 주입이 끝난 직후 한 번 호출됩니다. 주입받은 값이 필요한 초기화에 씁니다.
  • @PreDestroy: 컨텍스트가 닫힐 때 호출됩니다. 연결 종료 같은 정리에 씁니다.
  • 두 애노테이션은 jakarta.annotation 패키지입니다. Boot 4에서도 같습니다.

테스트로 순서 확인

@Test
void preDestroyRunsWhenContextCloses() {
    var ctx = new AnnotationConfigApplicationContext(LifecycleRecorder.class);
    LifecycleRecorder recorder = ctx.getBean(LifecycleRecorder.class);
    assertEquals(List.of("constructor", "postConstruct"), recorder.events());

    ctx.close();

    assertEquals(List.of("constructor", "postConstruct", "preDestroy"), recorder.events());
}

close() 전에는 constructor, postConstruct만 있고, 닫은 뒤 preDestroy가 추가됩니다. 서버 기동 후 앱에서도 앞의 두 이벤트가 BeanWiringTests.lifecycleCallbacksRanAtStartup으로 확인됩니다. 서버를 종료할 때 preDestroy가 실행되는 것은 이 테스트로는 보이지 않고, 컨텍스트를 직접 닫은 위 테스트로 확인했습니다.

Scope를 이해해야 하는 이유

이 두 개념은 이후 Chapter에서 계속 만납니다. 데이터베이스 연결 풀처럼 시작할 때 만들어 종료 때 닫아야 하는 자원이 대표적인 사례이고, 서비스가 상태를 가지면 안 된다는 규칙은 트랜잭션과 동시성 이야기로 이어집니다. 프록시가 Bean을 감싸는 방식은 Chapter 18 AOP와 온디맨드 배치에서 이 생명주기 위에서 설명합니다.

어느 Scope를 쓸까

상황 Scope 이유
상태 없는 서비스, 컨트롤러, 저장소 singleton(기본) 공유해도 안전하고 객체를 반복해서 만들지 않음
호출마다 독립된 상태가 필요한 객체 prototype 객체마다 필드 값이 달라야 할 때
요청별 상태(로그인 사용자 등) 필드에 두지 않고 메서드 인자나 요청 범위 객체 사용 singleton의 필드는 모든 요청이 공유하므로

자주 하는 실수

실수 증상 해결
singleton 서비스의 필드에 요청별 값을 저장 동시 요청에서 값이 섞임 값은 메서드 지역 변수나 인자로 전달
prototype Bean을 singleton에 주입하고 매번 새로 만들어질 것으로 기대 주입은 한 번만 일어나 같은 객체를 계속 사용 필요할 때마다 컨테이너에서 꺼내는 방식 사용
@PreDestroy를 prototype에 기대 컨테이너가 prototype의 소멸을 관리하지 않음 정리가 필요하면 직접 호출

확인 문제

  1. singleton Bean에 int counter 필드를 두고 요청마다 1씩 올리면 어떤 문제가 생길까요?
  2. 생성자 실행, @PostConstruct, @PreDestroy 중 서버가 켜질 때 일어나는 것과 종료될 때 일어나는 것을 나눠 보세요.

답: 1) 모든 요청이 같은 객체를 공유하므로 값이 섞이고 동시성 문제가 생깁니다. 2) 생성자와 @PostConstruct는 시작할 때, @PreDestroy는 종료할 때입니다.

직접 해 보기

  1. PrototypeBean을 @Scope("singleton")으로 바꾸면 테스트의 어느 줄이 실패하는지 예측하고 확인하세요.
  2. LifecycleRecorder의 init()에서 예외를 던지면 서버가 어떻게 되는지 보세요. 기동이 실패하는 로그를 읽어 봅니다.
  3. OrderService에 private int count;를 추가하고 place마다 증가시킨 뒤 /orders를 연속 호출해 값이 누적되는지 확인하세요. 왜 공유 상태가 위험한지 직접 보게 됩니다. 확인 후에는 되돌립니다.

자주 만나는 오류와 해결 방법

DI 오류는 서버가 시작할 때 한꺼번에 나서 오히려 찾기 쉽습니다. 메시지에 필요한 정보가 거의 다 들어 있기 때문에, 읽는 법만 알면 대부분 한 번에 해결됩니다.

이 절의 오류는 저장소 복사본의 예제에서 일부러 코드를 망가뜨려 얻은 메시지입니다. 세 경우 모두 테스트 12건 중 9건이 실패했습니다(컨텍스트를 띄우는 테스트가 함께 실패하기 때문입니다).

오류 1: expected single matching bean but found 2

EmailSender의 @Primary를 지웠습니다. 같은 타입이 둘인데 고를 단서가 없는 상태입니다.

APPLICATION FAILED TO START
Parameter 0 of constructor in ...OrderService required a single bean, but 2 were found

테스트에서는 이렇게 보입니다.

NoUniqueBeanDefinitionException: No qualifying bean of type '...NotificationSender' available: expected single matching bean but found 2: emailSender,smsSender

읽는 법은 다음과 같습니다.

  • Parameter 0 of constructor: OrderService의 생성자 첫 번째 인자가 문제입니다.
  • found 2: emailSender,smsSender: 후보 이름까지 알려 줍니다.

해결은 둘 중 하나입니다. 기본값이 있다면 하나에 @Primary를 붙이고, 특정 구현이 필요하면 그 인자에 @Qualifier("이름")을 붙입니다. 두 방법은 앞의 “하나의 생성자에서 세 방식을 모두 쓴다” 절에서 다뤘습니다.

오류 2: expected at least 1 bean which qualifies

@Qualifier("smsSender")를 "smsSendr"로 틀리게 썼습니다.

NoSuchBeanDefinitionException: No qualifying bean of type '...NotificationSender' available: expected at least 1 bean which qualifies as autowire candidate. Dependency annotations: {@org.springframework.beans.factory.annotation.Qualifier("smsSendr")}

Dependency annotations에 내가 쓴 이름이 그대로 나옵니다. 그 이름을 앞의 “Bean 이름은 어떻게 정해지나” 절의 규칙(SmsSender → smsSender)과 비교하면 철자 오류가 바로 보입니다. 문자열은 컴파일러가 검사해 주지 않으므로, 이 오류는 서버를 켜 봐야 알 수 있습니다.

오류 3: Bean으로 등록되지 않았다

OrderService에서 @Service를 지웠습니다.

NoSuchBeanDefinitionException: No qualifying bean of type '...OrderService' available: expected at least 1 bean which qualifies as autowire candidate. Dependency annotations: {}

오류 2와 문장은 같지만 Dependency annotations: {}가 비어 있습니다. 어노테이션 때문이 아니라 그 타입의 Bean이 아예 없다는 뜻입니다. 확인할 것은 두 가지입니다.

  1. @Component 계열 애노테이션이 붙어 있는가.
  2. 클래스가 시작 클래스와 같은 패키지 아래에 있는가(앞의 “컴포넌트 스캔은 어디까지 찾나” 절).

스캔 범위 밖에 둔 클래스를 쓰려면 위치를 옮기거나 @Import로 명시합니다.

오류 메시지는 아래에서부터 읽는다

세 오류 모두 UnsatisfiedDependencyException: Error creating bean with name 'beanController'로 시작합니다. 이 줄은 “어떤 Bean을 만들다 실패했는가”일 뿐 진짜 원인이 아닙니다. 맨 아래 Caused by를 읽으세요. Chapter 01의 “오류 메시지는 맨 아래 Caused by부터 읽습니다” 절에서 익힌 방법과 같습니다.

세 오류를 구분하는 방법

메시지의 found 2인지 at least 1인지를 먼저 보고, at least 1이면 Dependency annotations 괄호 안이 비었는지로 두 경우를 가릅니다.

증상별 점검표

증상 가장 먼저 볼 것
expected single matching bean but found 2 @Primary 또는 @Qualifier
expected at least 1 bean ... {@Qualifier("x")} Bean 이름과 x의 철자
expected at least 1 bean ... {} @Component 계열 유무, 스캔 범위
required a bean of type '...' that could not be found 위와 같음(Bean이 하나도 없음)

직접 해 보기

  1. 저장소를 복사해 EmailSender의 @Primary를 지우고 bootRun으로 위 오류를 재현해 보세요. 확인 후 되돌립니다.
  2. @Qualifier의 철자를 일부러 틀리게 쓰고 Dependency annotations에 무엇이 찍히는지 보세요.
  3. 오류가 났을 때 로그의 Caused by만 복사해 원인을 한 문장으로 적어 보는 연습을 해 보세요.

용어와 참고 자료

아래 표는 이 Chapter에 나온 용어와 참고한 사이트를 모은 것입니다. Chapter 01, 02에서 이미 설명한 용어는 다시 쓰지 않으므로 Chapter 01 프로젝트 시작하기와 Chapter 02 설정과 Profile을 참고하세요.

참고한 자료

컨테이너와 DI

용어 설명
의존성(dependency) 어떤 클래스가 동작하려고 필요로 하는 다른 객체입니다.
결합도 클래스가 서로의 구체적인 구현에 얽매인 정도입니다. 구현 클래스를 직접 new하면 높아집니다.
인터페이스 “무엇을 하는가”만 정한 약속입니다. 호출하는 쪽이 구현을 몰라도 되게 합니다.
IoC 객체 생성과 연결의 제어를 코드가 아니라 컨테이너가 맡는 구조입니다.
DI 필요한 객체를 직접 만들지 않고 밖에서 주입받는 방식입니다.
Bean 컨테이너가 만들고 관리하는 객체입니다.
생성자 주입 의존 객체를 생성자 인자로 받는 방식입니다. 생성자가 하나면 @Autowired를 생략합니다.
ApplicationContext 스프링 컨테이너입니다. Bean을 조회하거나 종료할 수 있습니다.

Bean 등록과 선택

용어 설명
@Component 클래스를 Bean으로 등록해 달라는 표시입니다. @Service, @RestController, @Repository가 이를 포함합니다.
@Configuration Bean 정의를 담은 설정 클래스입니다.
@Bean 메서드가 돌려주는 객체를 Bean으로 등록합니다. 라이브러리 클래스를 등록할 때 씁니다.
Bean 이름 @Component는 클래스명의 소문자 시작형, @Bean은 메서드 이름입니다.
컴포넌트 스캔 시작 클래스 패키지 아래에서 @Component 계열을 찾는 과정입니다.
@Import 스캔 범위 밖의 클래스를 명시적으로 불러옵니다. 이 Chapter에서는 개념만 소개했습니다.
@Primary 같은 타입이 여럿일 때 기본으로 선택할 Bean을 표시합니다.
@Qualifier 이름으로 주입할 Bean을 지정합니다. @Primary보다 우선합니다.
@Order List 주입 시 순서를 정합니다. 작을수록 앞입니다.
List 주입 같은 타입의 Bean을 모두 받습니다.

Scope와 생명주기

용어 설명
singleton 컨테이너에 하나만 만들어 공유하는 기본 Scope입니다.
prototype 요청할 때마다 새로 만드는 Scope입니다.
@PostConstruct 생성자와 주입이 끝난 직후 한 번 호출되는 초기화 메서드입니다.
@PreDestroy 컨텍스트가 닫힐 때 호출되는 정리 메서드입니다.
assertSame / assertNotSame 두 참조가 같은 객체인지 아닌지 검증합니다.

오류 메시지

용어 설명
NoUniqueBeanDefinitionException 같은 타입이 여럿인데 고를 단서가 없습니다.
NoSuchBeanDefinitionException 요청한 Bean이 없습니다.
Dependency annotations 주입 지점에 붙은 애노테이션 목록입니다. 비어 있으면 Bean 자체가 없다는 뜻입니다.

예제 코드 파일

본문에서 다룬 파일은 예제 저장소의 다음 위치에 있습니다.

대상 링크
알림 인터페이스 NotificationSender.java
이메일 구현 EmailSender.java
SMS 구현 SmsSender.java
서비스(생성자 주입) OrderService.java
@Bean 설정 AppConfig.java
범위 밖 클래스 OutsideComponent.java
Bean 연결 테스트 BeanWiringTests.java
컨트롤러 BeanController.java
단위 테스트 OrderServiceUnitTests.java
생명주기 Bean LifecycleRecorder.java
Scope·생명주기 테스트 ScopeAndLifecycleTests.java

직접 해보기

  1. 스프링 없이 만든 OrderService에 세 번째 구현 PushSender를 추가하고, 서비스 코드를 바꾸지 않은 채 main만 고쳐 동작시키는 것으로 “객체를 직접 만들면 생기는 문제” 절의 불편을 직접 확인해 보세요.
  2. ./gradlew :examples:ch03-ioc-di-bean:bootRun으로 서버를 켜고 /beans, /senders, /orders?item=book을 호출해 컨테이너가 등록한 Bean과 주입 순서를 확인해 보세요.
  3. OrderService의 첫 번째 인자에 @Qualifier("smsSender")를 붙이고 EmailSender와 SmsSender의 @Order 값을 바꿔, /orders와 /senders의 응답이 어떻게 달라지는지 비교해 보세요.
  4. PrototypeBean을 @Scope("singleton")으로 바꿔 ./gradlew :examples:ch03-ioc-di-bean:build에서 어느 검증이 실패하는지 예측한 뒤 확인하고 되돌려 보세요.
  5. EmailSender의 @Primary를 지워 기동 오류를 재현하고, 로그의 Caused by만 읽어 원인을 한 문장으로 적은 뒤 원래대로 되돌려 보세요.

이번 장의 정리

  • 서비스 안에서 구현 클래스를 new로 만들면 구현을 바꾸거나 테스트하기 어렵습니다. 인터페이스로 역할을 나누고 구현을 생성자로 받으면 그 결정이 서비스 밖으로 나갑니다.
  • IoC는 객체 생성과 연결의 제어를 컨테이너가 맡는 구조, DI는 필요한 객체를 밖에서 주입받는 방식, Bean은 컨테이너가 관리하는 객체입니다. 이 과정은 생성자 주입을 쓰고, 생성자가 하나면 @Autowired를 생략합니다.
  • 내 클래스는 @Component 계열, 고칠 수 없는 클래스는 @Configuration 안의 @Bean 메서드로 등록합니다. 컴포넌트 스캔은 시작 클래스의 패키지 아래만 찾습니다.
  • 같은 타입이 여럿이면 @Primary로 기본값을 정하고 @Qualifier로 이름을 지정하며, List로 전부 받을 때의 순서는 @Order가 정합니다.
  • 기본 Scope는 singleton이므로 서비스에 요청별 상태를 필드로 두지 않고, 초기화와 정리는 @PostConstruct와 @PreDestroy로 합니다.
  • DI 오류는 기동 시점에 나며 found 2, qualifies + 이름, qualifies + {}로 원인을 가릅니다. 첫 줄이 아니라 Caused by부터 읽습니다.

다음 Chapter 04 HTTP와 REST Controller에서는 이 Bean 구조 위에 REST API를 본격적으로 쌓습니다.

FAQ

자주 묻는 질문

IoC와 DI는 같은 말인가요?

IoC는 객체 생성과 연결의 제어권을 컨테이너에 맡기는 큰 원리이고, DI는 필요한 의존 객체를 외부에서 전달하는 구현 방식입니다.

생성자 주입을 권하는 이유는 무엇인가요?

필수 의존성이 생성 시점에 드러나고 필드를 final로 둘 수 있으며, 스프링 없이도 단위 테스트에서 가짜 구현을 직접 전달하기 쉽습니다.

@Component와 @Bean은 어떻게 고르나요?

직접 작성하고 스캔할 수 있는 클래스에는 @Component 계열을, 외부 라이브러리 객체나 생성 과정을 세밀하게 제어해야 하는 객체에는 설정 클래스의 @Bean을 사용합니다.

같은 인터페이스 구현이 여러 개면 어떻게 하나요?

기본 구현 하나에는 @Primary를 붙이고 특정 구현이 필요한 곳에는 @Qualifier를 사용합니다. 모두 필요하면 List로 주입받습니다.

작성·편집 ToolPado

콘텐츠 유형 Spring Boot 학습 가이드

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토