Mastering the Singleton Pattern in TypeScript: A Complete Guide

소프트웨어 개발에는 강력하지만 신중하게 사용해야 하는 도구들이 있습니다. 싱글톤 패턴은 그중 하나로, 클래스가 오직 하나의 인스턴스만 가지도록 보장하고 그 인스턴스에 대한 전역 접근 경로를 제공합니다¹. 이 글에서는 싱글톤의 목적과 한계, TypeScript 구현 예제, 테스트와 유지보수 관점의 대안인 의존성 주입(Dependency Injection, DI)까지 실무에서 바로 활용할 수 있도록 정리합니다.

싱글톤 패턴이란 무엇이고 언제 유용한가?

한 왕국에 공식 서기관이 단 한 명만 있어 모든 칙령을 기록한다고 상상해 보세요. 이처럼 싱글톤은 특정 리소스의 ‘단일 진실의 근원’을 제공해 일관성과 충돌 방지를 돕습니다. 중앙 설정 관리자나 전역 로거, 하드웨어 인터페이스 같은 본질적으로 유일한 리소스에 적합합니다.

핵심 목적과 비유

싱글톤의 목적은 단순히 객체 생성을 제한하는 것이 아니라 제어를 중앙집중화하는 데 있습니다. 이는 애플리케이션의 여러 부분이 서로 충돌하는 독립 인스턴스를 만들지 못하게 막습니다. 예를 들어 데이터베이스 연결 풀을 각자 열게 두면 리소스 고갈로 이어질 수 있습니다. 싱글톤은 하나의 풀을 관리해 효율적으로 분배합니다.

싱글톤 한눈에 보기

실용적 사용 사례

• 로깅 서비스: 모든 로그가 동일한 대상에 기록되도록 보장합니다.
• 설정 관리: 애플리케이션 설정의 단일 소스 역할을 합니다.
• 하드웨어 인터페이스: 장치 제어 명령의 충돌을 방지합니다.

싱글톤의 장단점

싱글톤은 간단한 전역 접근 지점을 제공하지만, 남용하면 유지보수성과 테스트에 악영향을 미칩니다.

장점

• 전역 접근 지점으로 사용을 단순화합니다.
• 지연 초기화로 시작 비용을 줄일 수 있습니다.
• 자원 중복을 줄여 성능과 메모리 사용을 최적화합니다.

단점

• 강한 결합을 유발해 유지보수성을 떨어뜨립니다.
• 전역 가변 상태는 추적하기 어려운 버그를 만들 수 있습니다.
• 의존성이 숨겨져 테스트와 리팩터링을 어렵게 합니다³.

테스트와 결합도에 미치는 영향

싱글톤은 전역적 상태를 도입해 단위 테스트를 복잡하게 만듭니다. 테스트 간 상태 누수나 목(mock) 처리의 어려움이 생길 수 있어, 많은 팀이 의존성을 명시적으로 만들고 테스트 중에 쉽게 교체할 수 있게 하는 의존성 주입을 선호합니다³.

싱글톤은 단순함을 전역 상태와 교환합니다. 장단점을 고려해 신중히 선택하세요.

TypeScript에서 싱글톤 구현하기

TypeScript에서는 private 생성자와 static 메서드를 조합해 타입 안전한 싱글톤을 만들 수 있습니다. 아래 예제는 구성 설정을 관리하는 ConfigManager입니다.

타입 안전한 ConfigManager 예제

class ConfigManager {
  private static instance: ConfigManager;
  private settings: Map<string, any> = new Map();

  private constructor() {
    console.log(“Initializing ConfigManager instance...”);
    this.settings.set(“API_URL”, “https://api.example.com”);
    this.settings.set(“TIMEOUT”, 5000);
  }

  public static getInstance(): ConfigManager {
    if (!ConfigManager.instance) {
      ConfigManager.instance = new ConfigManager();
    }
    return ConfigManager.instance;
  }

  public get(key: string): any {
    return this.settings.get(key);
  }
}

// new ConfigManager(); // Error: Constructor of class 'ConfigManager' is private.

이 구조는 지연 초기화와 인스턴스 생성 제한을 동시에 제공합니다. TypeScript의 접근 제어자는 단일 인스턴스를 강제하는 데 유용합니다².

서비스를 통한 사용 예

class ApiService {
  private apiUrl: string;

  constructor() {
    const config = ConfigManager.getInstance();
    this.apiUrl = config.get(“API_URL”);
    console.log(`ApiService initialized with API URL: ${this.apiUrl}`);
  }

  public fetchData(): void {
    console.log(`Fetching data from ${this.apiUrl}...`);
  }
}

console.log(“Application starting...”);
const service1 = new ApiService();
service1.fetchData();
const service2 = new ApiService();
console.log(“Application finished.”);

이 코드를 실행하면 ConfigManager의 초기화 로그는 한 번만 출력됩니다. 두 서비스가 동일한 인스턴스를 공유하기 때문입니다.

왜 싱글톤이 나쁜 평판을 얻는가

싱글톤은 전역 접근성 때문에 편리하지만, 잘못 사용하면 숨겨진 결합과 전역 가변 상태로 인해 테스트와 유지보수가 어려워집니다. 특히 동시성 시나리오에서 경쟁 조건(race condition)을 유발할 수 있습니다. 예를 들어 동시 요청이 같은 카운터를 증가시키는 SessionCounter를 다루면 동기화가 없을 때 충돌이 발생할 수 있습니다.

테스트 문제

싱글톤은 테스트 사이에 상태가 누수되거나 목킹이 어려워 테스트가 불안정해질 수 있습니다. 이 때문에 대부분의 현대 팀은 의존성을 명시적으로 만들어 테스트 더블을 주입할 수 있는 DI를 선호합니다³.

싱글톤이 한 번 코드베이스에 퍼지면 제거가 어렵습니다. 따라서 감사(audit)와 점진적 리팩터링 전략을 세우는 것이 중요합니다.

현대적 대안: 의존성 주입(Dependency Injection)

의존성 주입은 공유 리소스를 관리하면서도 테스트 가능성과 모듈성을 유지하는 대표적 방법입니다. 많은 TypeScript 프레임워크는 DI를 내장하거나 지원합니다. 예를 들어 NestJS는 DI를 핵심으로 제공하고, 일반 프로젝트에서는 InversifyJS 같은 라이브러리를 사용할 수 있습니다⁴⁵.

DI vs 싱글톤

다음은 ApiService를 싱글톤에 직접 의존시키는 방식과 DI를 사용하는 방식의 차이입니다.

interface IConfigManager {
  get(key: string): any;
}

class ApiService {
  private apiUrl: string;
  constructor(config: IConfigManager) {
    this.apiUrl = config.get(“API_URL”);
  }
}

이제 ApiService는 IConfigManager 계약에만 의존합니다. 테스트 중에는 페이크나 목을 주입해 빠르고 예측 가능한 테스트를 작성할 수 있습니다. DI는 의존성 역전의 아이디어를 적용해 구성 요소를 더 유연하게 만듭니다.

IoC 컨테이너의 역할

IoC 컨테이너는 객체 생성과 주입을 관리하고, 객체의 수명주기(transient, scoped, singleton-like)를 선택하게 해줍니다. 이는 프로그래밍적 싱글톤의 결합 없이도 단일 공유 인스턴스의 이점을 제공합니다. 많은 팀이 DI를 통해 테스트 안정성을 크게 향상시키고 있습니다⁷.

레거시 코드베이스에서 싱글톤을 리팩터링하는 방법

점진적으로 접근하세요. 싱글톤 사용 지점을 식별하고 인터페이스를 정의한 뒤 소비자를 하나씩 생성자 주입으로 변경하세요. 마지막으로 컴포지션 루트에서 인스턴스를 연결하거나 DI 컨테이너로 수명주기를 관리하면 안전하게 마이그레이션할 수 있습니다.

단계별 요약

1. 싱글톤 호출(MySingleton.getInstance())을 전부 찾아 책임 경계를 정의하세요.
2. 필요한 공개 메서드를 명세한 인터페이스를 도입하세요.
3. 소비자 하나씩 생성자 주입으로 변경하고, 마이그레이션이 완료되면 정적 접근을 제거하세요.

핵심 요약

• 싱글톤은 진정으로 고유해야 하는 서비스에만 사용하세요.
• 테스트 가능성과 결합 해소를 위해 의존성 주입을 우선 고려하세요.
• 싱글톤을 사용할 경우 지연 초기화와 동시성 안전성을 반드시 검토하세요.
• 레거시 시스템에서는 점진적 리팩터링으로 DI와 컴포지션 루트를 도입하세요.

추가 Q&A — 실무에서 바로 적용할 수 있는 간단 답변

Q&A 1

Q: 싱글톤을 언제 사용하는 것이 적절한가? A: 전역적으로 하나만 존재해야 하고 상태 변경이 작은 자원(예: 중앙 로거, 하드웨어 어댑터)에만 제한적으로 사용하세요.

Q&A 2

Q: 테스트가 어려운 기존 싱글톤 코드를 어떻게 다루죠? A: 인터페이스를 도입하고 소비자를 생성자 주입으로 하나씩 바꿔 테스트 더블을 주입할 수 있게 만드세요. 점진적 리팩터링이 핵심입니다.

Q&A 3

Q: DI를 도입할 때 추천할 만한 도구는 무엇인가요? A: NestJS(프레임워크 내장 DI)나 InversifyJS 같은 라이브러리를 고려하세요. 또한 프로젝트의 컴포지션 루트에서 수명주기를 명확히 관리하세요⁴⁵.

빠른 FAQ

Q: 싱글톤은 항상 나쁜가요? A: 항상 나쁜 것은 아닙니다. 그러나 가능한 경우 DI를 통해 동일한 동작을 더 나은 테스트 환경과 함께 제공하는 편이 좋습니다.

Q: 단위 테스트를 어떻게 안정화하죠? A: 인터페이스 도입, 소비자의 생성자 주입, 테스트 더블 사용으로 안정화를 도모하세요.

Q: 레거시 앱에서의 안전한 제거 방법은? A: 사용처 매핑 → 인터페이스 정의 → 소비자 리팩터링 → 컴포지션 루트에서 단일 인스턴스 주입 순으로 진행하세요.