의존성 주입과 IoC 컨테이너

객체지향 설계 원칙, 특히 의존성 역전 원칙(DIP)을 지키다 보면 자연스럽게 의존성 주입(Dependency Injection, DI) 개념을 만나게 됩니다.

그리고 규모가 커진 애플리케이션에서 DI를 효율적으로 관리하기 위해 IoC 컨테이너(Inversion of Control Container)를 사용합니다.

이 절에서는 의존성 주입의 개념, 다양한 주입 방식, 그리고 IoC 컨테이너의 역할과 이점에 대해 타입스크립트와 함께 살펴보겠습니다.

SOLID의 ILogger 예제와 생성자·인터페이스가 선수 학습 개념입니다. IoC는 필요한 작업을 언제 호출하거나 객체를 어떻게 연결할지에 관한 제어를 바깥에 맡기는 더 넓은 개념입니다. 프레임워크가 등록된 이벤트 콜백을 호출하는 것도 그 사례입니다. DI는 그중 의존 객체를 외부에서 제공하는 방법이며, IoC 컨테이너는 DI의 조립을 관리하는 도구입니다. 수동 생성자 주입에도 컨테이너 설치는 필요하지 않습니다.

의존성 주입

정의: 의존성 주입은 객체가 자신이 의존하는 객체(의존성)를 직접 생성하거나 찾는 대신, 외부에서 주입받는 설계 패턴입니다.

설명: 일반적으로 객체는 자신이 필요한 다른 객체(의존성)를 직접 생성하거나, 팩토리 메서드를 호출하여 얻어옵니다.

이 경우, 객체와 그 의존성 사이에 강한 결합이 발생합니다.

이는 코드의 재사용성을 저해하고, 테스트를 어렵게 만들며, 변경에 취약하게 만듭니다.

의존성 주입은 이러한 강한 결합을 느슨하게(Loosely Coupled) 만들어줍니다.

객체는 자신이 필요한 것을 주입받으므로, 어떤 구현체를 사용할지 직접 결정하지 않습니다.

대신, 그 결정은 외부(즉, DI를 수행하는 주체)로 역전(Inversion)됩니다.

• 결합도 감소: 객체 생성·선택 책임을 사용하는 객체에서 분리합니다. 아래처럼 사용자가 소유한 인터페이스로 받으면 구체 구현에 대한 소스 의존도 줄일 수 있습니다. 구체 클래스 타입을 주입하는 DI만으로 DIP가 자동 성립하지는 않습니다.
• 재사용성 증가: 의존하는 구현체를 쉽게 교체할 수 있으므로, 동일한 객체를 다른 환경이나 다른 구현체와 함께 재사용하기 용이합니다.
• 테스트 용이성: 유닛 테스트 시 실제 의존성 대신 목(Mock) 객체나 스텁(Stub) 객체를 쉽게 주입하여 테스트 범위를 격리하고 신뢰성을 높일 수 있습니다.
• 유지보수성 및 확장성: 변경에 대한 파급 효과를 줄이고, 새로운 기능을 추가할 때 기존 코드를 수정하는 대신 새로운 구현체를 주입하는 방식으로 확장이 용이해집니다 (OCP, DIP 준수).

이전 10장 1절의 DIP 예시와 유사합니다.

// 1. 추상화 (의존성: ILogger)
interface ILogger {
  log(message: string): void;
}

// 2. 구체적인 의존성 구현체 (저수준 모듈)
class ConsoleLogger implements ILogger {
  log(message: string): void {
    console.log(`[Console Log]: ${message}`);
  }
}

class FileLogger implements ILogger {
  log(message: string): void {
    console.log(`[File Log]: ${message}`);
    // 실제 파일 시스템에 쓰는 로직
  }
}

// 3. 의존성을 주입받는 객체 (고수준 모듈)
class UserService {
  private logger: ILogger; // ILogger 인터페이스에 의존

  // 1. 생성자 주입 (Constructor Injection): 가장 일반적이고 권장되는 방식
  constructor(logger: ILogger) {
    this.logger = logger;
  }

  // 2. 메서드 주입 (Method Injection): 특정 메서드 실행 시 필요한 의존성
  public registerUser(username: string, email: string, logger?: ILogger): void {
    const activeLogger = logger ?? this.logger; // 메서드 인자가 우선, 없으면 생성자 주입된 것 사용
    activeLogger.log(`Registering user: ${username}, ${email}`);
    // 사용자 등록 로직
  }

  // 3. 속성(Setter) 주입 (Property/Setter Injection): public 속성 또는 setter 메서드를 통해 주입
  public setLogger(logger: ILogger): void {
    this.logger = logger;
  }

  public processUserData(data: unknown): void {
    this.logger.log(`Processing user data: ${JSON.stringify(data)}`);
    // 데이터 처리 로직
  }
}

// 사용 예시 (DI 적용)
// 생성자 주입
const consoleLogger = new ConsoleLogger();
const userServiceWithConsole = new UserService(consoleLogger);
userServiceWithConsole.registerUser("Alice", "[email protected]");
userServiceWithConsole.processUserData({ id: 1, name: "Alice" });

// 다른 로거로 쉽게 교체 (테스트 용이성)
const fileLogger = new FileLogger();
const userServiceWithFile = new UserService(fileLogger);
userServiceWithFile.registerUser("Bob", "[email protected]");

// 메서드 주입 예시
userServiceWithConsole.registerUser("Charlie", "[email protected]", fileLogger); // 일시적으로 fileLogger 사용

// 속성 주입 예시
const userServiceWithSetter = new UserService(new ConsoleLogger()); // 일단 ConsoleLogger로 초기화
userServiceWithSetter.setLogger(new FileLogger()); // 나중에 FileLogger로 변경
userServiceWithSetter.processUserData({ id: 3, name: "David" });

의존성이 필수인지, 호출마다 달라지는지, 생성 이후 바뀌어야 하는지를 기준으로 주입 방식을 선택할 수 있습니다.

생성자 주입은 필요한 값을 받는 시점을 정합니다. 이 예제처럼 setLogger가 있으면 생성자에서 받았더라도 이후 값이 바뀝니다. 객체의 불변성까지 필요하다면 변경 메서드를 두지 않는 별도 설계가 필요합니다. DI는 값을 외부에서 넘기는 방식이고 DIP는 코드가 의존하는 추상화의 방향이므로, 구체 클래스 자체를 주입하는 코드가 자동으로 DIP를 만족하는 것은 아닙니다.

호출 범위와 저장된 의존성 확인

FileLogger라는 이름은 원문에서 콘솔 출력 형식을 구별하기 위한 것이며 실제 파일 쓰기는 구현하지 않았습니다. 로그를 눈으로 비교하는 대신 다음 테스트 로거를 같은 수동 DI 예제에 추가해 보세요.

class MemoryLogger implements ILogger {
  readonly messages: string[] = [];

  log(message: string): void {
    this.messages.push(message);
  }
}

const defaultLog = new MemoryLogger();
const temporaryLog = new MemoryLogger();
const service = new UserService(defaultLog);
service.registerUser("Eve", "[email protected]", temporaryLog);
service.processUserData({ id: 4 });
service.setLogger(temporaryLog);
service.processUserData({ id: 5 });
console.log(defaultLog.messages);
console.log(temporaryLog.messages);

여기서는 JSON으로 직렬화할 수 있는 객체만 예제로 사용합니다. unknown은 입력의 타입을 임의로 가정하지 않게 하지만 순환 참조나 BigInt의 직렬화 성공까지 보장하지 않습니다. readonly messages도 배열 필드의 재대입을 제한할 뿐 push()까지 금지하지 않습니다.

예상되는 배열은 defaultLog에 Processing user data: {"id":4} 한 항목, temporaryLog에 Registering user: Eve, [email protected]과 Processing user data: {"id":5} 두 항목입니다. Eve의 한 호출에 넘긴 로거가 서비스의 필드를 바꾸지 않았으므로 id 4는 처음 로거로 갑니다. setter 호출 뒤 id 5는 저장된 새 로거로 갑니다. JSON.stringify 결과가 메시지 뒤에 붙는 점도 원문에서 확인하세요.

스스로 호출 범위 바꾸기

위 실행을 마친 뒤 service.registerUser("Finn", "[email protected]", defaultLog), service.processUserData({ id: 6 })을 순서대로 호출합니다. 두 배열의 최종 길이와 새 메시지가 들어갈 배열을 예측해 보세요.

IoC 컨테이너

정의: IoC 컨테이너는 객체의 생성, 구성, 생명 주기를 관리하고, 객체 간의 의존성을 자동으로 주입해주는 프레임워크 또는 라이브러리입니다.

설명: DI 패턴을 직접 구현하다 보면, 애플리케이션의 규모가 커질수록 수많은 객체들을 수동으로 생성하고 의존성을 주입하는 코드가 복잡해집니다.

이때 IoC 컨테이너가 큰 도움이 됩니다.

IoC 컨테이너는 객체 생성 및 의존성 주입의 제어권을 개발자에게서 컨테이너로 넘겨 관리합니다. 이를 제어의 역전(Inversion)이라고 합니다.

개발자는 런타임 token과 provider를 등록하고 해당 token의 객체를 요청합니다. TypeScript interface는 실행 시 사라지므로 이 예제는 Symbol을 token으로 사용합니다.

컨테이너는 등록된 정보를 바탕으로 필요한 의존성을 찾아 자동으로 주입해줍니다.

자바스크립트/타입스크립트 생태계에는 다양한 IoC 컨테이너 라이브러리가 존재합니다.

대표적인 예시는 다음과 같습니다.

• InversifyJS: 타입스크립트 기반의 IoC 컨테이너로, 데코레이터(Decorator)를 사용하여 의존성 주입을 선언적으로 표현할 수 있게 합니다.
• TypeDI: 데코레이터를 사용하여 DI를 쉽게 구현할 수 있도록 돕는 또 다른 인기 있는 라이브러리입니다.
• NestJS (프레임워크): 자체적으로 강력한 IoC 컨테이너를 내장하고 있어, DI를 기반으로 한 아키텍처를 쉽게 구축할 수 있습니다.

import "reflect-metadata"; // 이 Inversify 레거시 데코레이터 예제의 메타데이터 지원
import { Container, injectable, inject } from "inversify";

// 1. 심볼(Symbol) 또는 문자열을 사용하여 서비스(인터페이스)를 식별합니다.
const TYPES = {
  ILogger: Symbol.for("ILogger"),
  UserService: Symbol.for("UserService"),
};

// 2. 추상화 (인터페이스)
interface ILogger {
  log(message: string): void;
}

// 3. 구현체 (InversifyJS의 @injectable 데코레이터 사용)
@injectable()
class ConsoleLogger implements ILogger {
  log(message: string): void {
    console.log(`[Console Log by Inversify]: ${message}`);
  }
}

@injectable()
class FileLogger implements ILogger {
  log(message: string): void {
    console.log(`[File Log by Inversify]: ${message}`);
  }
}

// 4. 의존성을 주입받는 클래스 (InversifyJS의 @inject 데코레이터 사용)
@injectable()
class UserService {
  private logger: ILogger;

  // 생성자 주입을 @inject 데코레이터로 명시
  constructor(@inject(TYPES.ILogger) logger: ILogger) {
    this.logger = logger;
  }

  registerUser(username: string): void {
    this.logger.log(`User registered: ${username}`);
  }
}

// 5. IoC 컨테이너 설정 (바인딩)
const container = new Container();

// ILogger 심볼에 ConsoleLogger 구현체를 바인딩
container.bind<ILogger>(TYPES.ILogger).to(ConsoleLogger);

// FileLogger를 사용하려면 위 ConsoleLogger 바인딩 줄 대신 아래 줄을 활성화합니다.
// container.bind<ILogger>(TYPES.ILogger).to(FileLogger);

// UserService 심볼에 UserService 클래스를 바인딩
container.bind<UserService>(TYPES.UserService).to(UserService);

// 6. 컨테이너를 통해 객체 요청 (주입은 컨테이너가 알아서 처리)
const userService = container.get<UserService>(TYPES.UserService);
userService.registerUser("Grace");

// 런타임에 로거 구현체를 변경하고 싶다면, 바인딩만 변경하면 됩니다.
// container.rebind<ILogger>(TYPES.ILogger).to(FileLogger);
// const anotherUserService = container.get<UserService>(TYPES.UserService);
// anotherUserService.registerUser("Heidi");

• reflect-metadata: 이 Inversify 예제에서는 타입스크립트의 레거시 데코레이터 설정인 experimentalDecorators와 emitDecoratorMetadata를 모두 true로 설정합니다.
• @injectable(): 이 데코레이터는 클래스가 IoC 컨테이너에 의해 관리될 수 있음을 나타냅니다.
• @inject(TYPES.ILogger): 생성자 매개변수에 이 데코레이터를 붙여주면, InversifyJS 컨테이너는 TYPES.ILogger 심벌에 바인딩된 구현체를 찾아 UserService의 생성자로 주입해줍니다.
• container.bind<ILogger>(TYPES.ILogger).to(ConsoleLogger): 런타임 식별자 TYPES.ILogger가 요청될 때 제공할 클래스를 등록합니다. <ILogger>는 정적 타입 검사에 쓰이며 실행 시 token을 대신하지 않습니다.
• container.get<UserService>(TYPES.UserService): 컨테이너에게 UserService 인스턴스를 요청합니다. 컨테이너는 UserService가 ILogger를 필요로 한다는 점을 파악하고, 바인딩된 ConsoleLogger를 자동 생성해 UserService에 주입한 뒤 최종 인스턴스를 반환합니다.

그림의 scope cache는 재사용하도록 설정된 수명 정책에 해당합니다. 원문은 기본 바인딩만 보여주며 singleton/request scope를 설정한 예가 아닙니다.

라이브러리 예제를 따라갈 때의 확인 순서

Inversify 블록은 수동 DI 예제와 이름이 겹치므로 별도 파일과 프로젝트에서 사용합니다. interface 타입은 실행 시 token이 될 수 없어 TYPES의 Symbol과 생성자 @inject가 연결을 설명하는 핵심입니다. 먼저 ILogger·UserService의 두 등록이 완료된 뒤 get을 호출하는 순서를 확인하세요. ILogger 등록을 빼면 주입에 필요한 의존성을 해결할 수 없으며, 완성 객체를 반환했다는 결과를 기대하면 안 됩니다.

2026년 10월 9일 확인한 공식 시작 안내와 Container API의 대상은 8.x입니다. 이 예제에는 experimentalDecorators와 emitDecoratorMetadata를 설정하고 reflect-metadata를 불러옵니다. 이는 Inversify의 레거시 생성자 매개변수 데코레이터 구성으로, TypeScript의 모든 데코레이터에 이 라이브러리가 필요하다는 뜻이 아닙니다.

8.x의 기본 scope는 transient이고 get은 하나의 일치하는 동기 바인딩을 요구합니다. 같은 token을 bind로 두 번 등록하면 기본 get이 임의로 마지막 로거를 고르는 것이 아니라 오류가 됩니다. 위 대체 바인딩 주석은 두 줄을 동시에 활성화하라는 뜻이 아닙니다. 현재 8.x의 rebind(...).to(...)는 동기 교체이며, rebindAsync(...)는 Promise를 반환합니다. 비동기 정리·생성 조건이 있다면 해당 API를 기다리고 getAsync 등 맞는 해결 경로를 선택합니다. 라이브러리를 설치해 이 교재를 실행한 결과는 아니므로 실제 설치 버전·설정과 타입 검사·실행 결과는 따로 확인합니다.

한 번 resolve해 받은 userService의 logger 필드는 그때 주입한 객체를 가리킵니다. 나중에 컨테이너의 ILogger 바인딩을 바꾼다고 이미 반환된 서비스의 필드가 저절로 교체되지는 않습니다. 새 root를 resolve할지 기존 객체를 명시적으로 변경할지는 객체 수명과 조립 경계의 별도 결정입니다.

의존성 주입과 IoC 컨테이너의 장단점

• 느슨한 결합: 객체 간의 의존성을 분리하여 코드의 유연성과 재사용성을 극대화합니다.
• 테스트 용이성: 목 객체를 쉽게 주입하여 단위 테스트를 간결하게 만듭니다.
• 확장성: 새로운 구현체가 추가되어도 기존 코드를 수정할 필요 없이 설정을 통해 변경할 수 있습니다.
• 중앙 집중식 관리: 모든 의존성 관계와 객체 생명 주기를 한곳에서 관리하여 코드베이스 이해도를 높입니다.

• 초기 학습 곡선: DI 패턴과 IoC 컨테이너의 개념 및 사용법을 익히는 데 시간이 필요할 수 있습니다.
• 런타임 오버헤드: 컨테이너가 객체를 동적으로 생성하고 의존성을 해결하는 과정에서 런타임 오버헤드가 발생할 수 있습니다. 객체 그래프 크기·해결 빈도·수명 정책에 따라 비용이 달라지므로 실제 사용 경로를 측정합니다.
• 설정 복잡성: 대규모 프로젝트에서는 컨테이너 설정 파일이나 바인딩 코드가 복잡해질 수 있습니다.

조립 경계 검토

위 그림은 컨테이너 의존을 조립 경계로 제한하는 설계 방향입니다. 앞의 Inversify 예제는 UserService 생성자에 @inject와 token을 사용하므로 그림처럼 컨테이너 관련 선언까지 완전히 분리한 구현은 아닙니다. 컨테이너 없는 생성자 주입 예제와 비교해 필요한 격리 수준을 선택합니다.

등록 위치, 객체 수명, 테스트 대역이 같은 계약을 따르는지 확인합니다. 컨테이너는 DI의 필수 조건이 아니며, 작은 객체 그래프는 수동 조립으로도 충분합니다.

token·수명·조립 실패를 구별하는 연습

1. 등록에 const registered = Symbol("ILogger"), 조회에 별도로 만든 const requested = Symbol("ILogger")를 썼습니다. 설명 문자열이 같으니 같은 의존성을 찾을 수 있습니까? 하나의 공유 token 상수를 쓰면 무엇이 달라집니까?
2. 위 기본 바인딩에서 get(TYPES.UserService)를 두 번 호출한 뒤 로거 바인딩을 바꿉니다. 기존 서비스의 로거까지 바뀝니까? singleton을 따로 설정했다면 새 root를 요청하는 것만으로 모든 의존성이 새로 조립됩니까?
3. TYPES.ILogger에 ConsoleLogger와 FileLogger를 둘 다 기본 bind로 등록했습니다. 기본 get(TYPES.UserService)는 어느 것을 선택해야 합니까? 한 구현만 쓰려는 목표와 여러 구현을 모두 받으려는 목표를 나누어 설명하세요.