[Nest.js] Fundamentals - Circular dependency, Module reference

순환 의존성

순환 의존성은 두 클래스가 서로를 필요로 할 때 발생합니다. 예를 들어, 클래스 A가 클래스 B를 필요로 하고, 클래스 B도 클래스 A를 필요로 하는 경우입니다. Nest에서는 모듈 간 또는 프로바이더 간에 이러한 순환 의존성이 발생할 수 있습니다.

 

순환 의존성은 가능하면 피하는 것이 좋지만, 항상 그렇게 할 수는 없습니다. 이러한 경우를 위해 Nest는 두 가지 방법으로 프로바이더 간의 순환 의존성을 해결할 수 있도록 지원합니다. 이 장에서는 forwardRef를 사용하는 방법과, DI 컨테이너에서 ModuleRef 클래스를 통해 프로바이더 인스턴스를 가져오는 방법을 설명합니다.

 

또한, 모듈 간의 순환 의존성을 해결하는 방법도 설명합니다.

경고
순환 의존성은 index.ts와 같은 배럴 파일 (barrel file)을 사용하여 import를 그룹화할 때도 발생할 수 있습니다. 특히 모듈이나 프로바이더 클래스와 관련해서는 배럴 파일 사용을 피해야 합니다. 예를 들어, 동일한 디렉터리 내역 파일을 가져올 때는 배럴 파일을 사용하지 말아야 합니다. 즉, cats/cats.controller 에서 cats를 통해 cats/cats.service를 import 하는 방식은 지양해야 합니다. 자세한 내용은 해당 GitHub 이슈를 참고하세요.

전방 선언 (Forward reference)

전방 선언은 아직 정의되지 않은 클래스를 forwardRef() 유틸리티 함수를 사용하여 참조할 수 있도록 합니다. 예를 들어, CatsService와 CommonService가 서로를 의존하는 경우, 양쪽 모두 @Inject()와 forwardRef()를 함께 사용하여 순환 의존성을 해결할 수 있습니다. 그렇지 않으면 필수 메타데이터가 모두 준비되지 않아 Nest가 이들을 인스턴스화하지 못합니다. 다음은 그 예시입니다:

@Injectable()
export class CatsService {
  constructor(
    @Inject(forwardRef(() => CommonService))
    private commonService: CommonService,
  ) {}
}

힌트
forwardRef() 함수는 @nestjs/common 패키지에서 import 됩니다.

 

이제 한쪽 관계를 처리했으므로, CommonService에서도 동일한 방식으로 처리해 보겠습니다:

@Injectable()
export class CommonService {
  constructor(
    @Inject(forwardRef(() => CatsService))
    private catsService: CatsService,
  ) {}
}

주의
인스턴스화 순서는 결정되어 있지 않으므로, 어떤 생성자가 먼저 호출되는지에 의존하는 코드는 작성하지 말아야 합니다. 특히 Scope.REQUEST 범위를 가진 프로바이더가 순환 의존성에 포함될 경우, 의존성이 정의되지 않은 상태가 될 수 있습니다. 자세한 내용은 여기를 참고하세요.

ModuleRef 대안

forwardRef()를 사용하는 대신, 코드를 리팩터링 하여 ModuleRef 클래스를 활용해 순환 관계의 한쪽에서 프로바이더를 직접 가져오는 방식도 사용할 수 있습니다. ModuleRef 유틸리티 클래스에 대한 자세한 내용은 여기를 참고하세요.

모듈 전방 선언

모듈 간의 순환 의존성을 해결하려면, 양쪽 모듈의 연결에서 동일하게 forwardRef() 유틸리티 함수를 사용해야 합니다. 예를 들어:

@Module({
  imports: [forwardRef(() => CatsModule)],
})
export class CommonModule {}

 

이제 한쪽 모듈에서 전방 선언을 설정했으므로, CatsModule에서도 동일한 방식으로 설정해 보겠습니다:

@Module({
  imports: [forwardRef(() => CommonModule)],
})
export class CatsModule {}

모듈 참조

Nest는 ModuleRef 클래스를 제공하여 내부 프로바이더 목록을 탐색하고, 주입 토큰을 키로 사용하여 원하는 프로바이더의 참조를 얻을 수 있도록 합니다. 또한 ModuleRef는 정적 (static) 프로바이더와 범위 (scope)가 지정된 프로바이더 모두를 동적으로 인스턴스화하는 기능도 제공합니다. ModuleRef는 일반적인 방식으로 클래스에 주입할 수 있습니다:

@Injectable()
export class CatsService {
  constructor(private moduleRef: ModuleRef) {}
}

힌트
ModuleRef 클래스는 @nestjs/core 패키지에서 import 됩니다.

인스턴스 가져오기

ModuleRef 인스턴스 (이하 모듈 참조)는 get() 메서드를 제공합니다. 기본적으로 이 메서드는 현재 모듈에 등록되어 인스턴스화된 프로바이더, 컨트롤러 또는 인젝터블 (예: 가드, 인터셉터 등)을 주입 토큰 또는 클래스 이름을 사용하여 반환합니다. 만약 인스턴스를 찾지 못하면 예외가 발생합니다.

@Injectable()
export class CatsService implements OnModuleInit {
  private service: Service;
  constructor(private moduleRef: ModuleRef) {}

  onModuleInit() {
    this.service = this.moduleRef.get(Service);
  }
}

주의
get() 메서드는 범위가 지정된 프로바이더 (예: transient 또는 request 범위)를 가져올 수 없습니다. 이러한 경우에는 아래에 설명된 기법을 사용해야 합니다. 범위 제어에 대한 자세한 내용은 여기를 참고하세요.

 

전역 컨텍스트에서 프로바이더를 가져오려면 (예: 해당 프로바이더가 다른 모듈에서 주입된 경우), get() 메서드의 두 번째 인자로 { strict: false } 옵션을 전달하면 됩니다.

this.moduleRef.get(Service, { strict: false });

범위가 지정된 프로바이더 해결하기

transient 또는 request 범위의 프로바이더를 동적으로 해결하려면, 해당 프로바이더의 주입 토큰을 인자로 전달하여 resolve() 메서드를 사용해야 합니다.

@Injectable()
export class CatsService implements OnModuleInit {
  private transientService: TransientService;
  constructor(private moduleRef: ModuleRef) {}

  async onModuleInit() {
    this.transientService = await this.moduleRef.resolve(TransientService);
  }
}

 

resolve() 메서드는 DI 컨테이너의 하위 트리로부터 프로바이더의 고유한 인스턴스를 반환합니다. 각 하위 트리는 고유한 컨텍스트 식별자를 가지므로, 이 메서드를 여러 번 호출하면 매번 서로 다른 인스턴스가 생성되어 인스턴스 참조를 비교할 경우 동일하지 않음을 알 수 있습니다.

@Injectable()
export class CatsService implements OnModuleInit {
  constructor(private moduleRef: ModuleRef) {}

  async onModuleInit() {
    const transientServices = await Promise.all([
      this.moduleRef.resolve(TransientService),
      this.moduleRef.resolve(TransientService),
    ]);
    console.log(transientServices[0] === transientServices[1]); // false
  }
}

 

여러 번의 resolve() 호출에서도 단일 인스턴스를 생성하고, 동일한 DI 컨테이너 하위 트리를 공유하도록 하려면, resolve() 메서드에 컨텍스트 식별자를 전달하면 됩니다. 이를 위해 ContextIdFactory 클래스를 사용하여 컨텍스트 식별자를 생성할 수 있습니다. 이 클래스는 적절한 고유 식별자를 반환하는 create() 메서드를 제공합니다.

@Injectable()
export class CatsService implements OnModuleInit {
  constructor(private moduleRef: ModuleRef) {}

  async onModuleInit() {
    const contextId = ContextIdFactory.create();
    const transientServices = await Promise.all([
      this.moduleRef.resolve(TransientService, contextId),
      this.moduleRef.resolve(TransientService, contextId),
    ]);
    console.log(transientServices[0] === transientServices[1]); // true
  }
}

힌트
ContextIdFactory 클래스는 @nestjs/core 패키지에서 import 됩니다.

REQUEST 프로바이더 등록하기

ContextIdFactory.create()로 수동 생성한 컨텍스트 식별자는 Nest의 DI 시스템에 의해 인스턴스화되거나 관리되지 않기 때문에, 해당 DI 하위 트리 내에서는 REQUEST 프로바이더가 정의되어 있지 않습니다.

 

이러한 수동 생성 DI 하위 트리에 사용자 정의 REQUEST 객체를 등록하려면, ModuleRef#registerRequestByContextId() 메서드를 다음과 같이 사용해야 합니다:

const contextId = ContextIdFactory.create();
this.moduleRef.registerRequestByContextId(/* 당신의_REQUEST_객체 */, contextId);

현재 하위 트리 가져오기

경우에 따라 요청 컨텍스트 내에서 request 범위의 프로바이더 인스턴스를 해결해야 할 수 있습니다. 예를 들어, CatsService가 request 범위로 지정되어 있고, 동일하게 request 범위인 CatsRepository 인스턴스를 해결하고 싶다고 가정해 봅시다. 동일한 DI 컨테이너 하위 트리를 공유하려면, ContextIdFactory.create()와 같이 새로운 컨텍스트 식별자를 생성하는 대신 현재 컨텍스트 식별자를 얻어야 합니다. 이를 위해 먼저 @Inject() 데코레이터를 사용하여 request 객체를 주입해야 합니다.

@Injectable()
export class CatsService {
  constructor(
    @Inject(REQUEST) private request: Record<string, unknown>,
  ) {}
}

힌트
request 프로바이더에 대한 내용은 여기에서 확인할 수 있습니다.

 

이제 ContextIdFactory 클래스의 getByRequest() 메서드를 사용하여 해당 요청 객체를 기반으로 컨텍스트 ID를 생성하고, 이를 resolve() 호출 시 전달하면 됩니다:

const contextId = ContextIdFactory.getByRequest(this.request);
const catsRepository = await this.moduleRef.resolve(CatsRepository, contextId);

사용자 정의 클래스 동작 인스턴스화

이전에 프로바이더로 등록되지 않은 클래스를 동적으로 인스턴스화하려면, ModuleRef의 create() 메서드를 사용하면 됩니다.

@Injectable()
export class CatsService implements OnModuleInit {
  private catsFactory: CatsFactory;
  constructor(private moduleRef: ModuleRef) {}

  async onModuleInit() {
    this.catsFactory = await this.moduleRef.create(CatsFactory);
  }
}

 

이 기법을 사용하면 프레임워크 컨테이너 외부에서 조건에 따라 서로 다른 클래스를 동적으로 인스턴스화할 수 있습니다.

Reference

• Nest.js | Circular dependency
• Nest.js | Module reference