애플리케이션 부트스트랩 프로세스

개요

이 문서는 DTA-WIDE-API 애플리케이션의 부트스트랩 과정과 NestJS 애플리케이션 초기화 로직을 설명합니다.

부트스트랩 프로세스

애플리케이션 부트스트랩은 main.ts 파일에 구현하며 다음 단계를 포함합니다:

1. NestJS 애플리케이션 인스턴스 생성
2. 환경 설정 로딩 (ConfigService)
3. NestJS의 기반 기술인 Express 미들웨어 설정 (JSON, Raw 바디 파싱 등)
4. Google Cloud 인증 설정
5. API 접두사 설정
6. Swagger UI 설정
7. 유효성 검증 파이프라인 설정
8. 서버 리스닝 시작

환경 설정 및 구성 참조

부트스트랩 프로세스에서 사용되는 주요 환경 변수:

환경 변수	용도	설정 위치
PORT	서버 리스닝 포트	환경 변수 또는 .env
API_PREFIX	API 경로 접두사	환경 변수 또는 .env
RUNTIME_ENV	실행 환경 식별	환경 변수 또는 .env
SERVICE_NAME	서비스 식별자	환경 변수 또는 .env
GOOGLE_APPLICATION_CREDENTIALS	GCP 인증 정보	환경 변수 또는 .env

구성 세부사항 관련해서는 다음 구현 참고사항을 확인하세요:

• Google Cloud 인증 설정은 환경에 따라 다른 경로를 사용합니다
• 로컬 개발과 클라우드 환경에서 Swagger UI 경로가 다릅니다
• 환경별 API 엔드포인트 구성은 API_HOST와 API_PREFIX 환경 변수에 의해 결정됩니다

환경별 초기화 차이점

로컬 환경 특화 초기화

로컬 개발 환경에서는 다음과 같은 특수한 초기화 과정이 필요합니다:

// RUNTIME_ENV가 'LOCAL'일 경우
if (runtimeEnv === 'LOCAL') {
  // 로컬 개발 환경에서만 필요한 설정
  setupMockServices(app);
  // 로컬 Google Cloud 인증 설정
  process.env.GOOGLE_APPLICATION_CREDENTIALS = path.resolve(
    process.cwd(),
    configService.get('GOOGLE_APPLICATION_CREDENTIALS')
  );
}

클라우드 환경 특화 초기화

클라우드 환경(DEV, STAGE, PROD)에서는 다음과 같은 초기화 과정이 필요합니다:

// RUNTIME_ENV가 'LOCAL'이 아닐 경우
if (runtimeEnv !== 'LOCAL') {
  // 클라우드 환경에서만 필요한 설정
  setupMonitoring(app);
  setupCloudTracing(app);
  // 자세한 내용은 application-configuration.md의 OpenTelemetry 설정 참조
}

오류 처리 메커니즘

애플리케이션은 다음과 같은 오류 처리 메커니즘을 구현합니다:

1. 타임아웃 처리 (30초 후 재시도)
2. 예외 발생 시 로깅 및 애플리케이션 종료
3. 프로세스 재시작 전 정상적인 리소스 해제

애플리케이션은 통합된 로깅 및 에러 핸들링 시스템을 사용합니다.

모든 에러는 ErrorLoggerService를 통해 표준화된 포맷으로 기록되며, 환경에 따라 적절한 출력 전략을 통해 처리됩니다. 로깅과 에러 처리에 대한 자세한 내용은 다음 문서를 참조하세요:

DDD 관점에서의 의미

부트스트랩 프로세스는 DDD 패턴에서 인프라스트럭처 레이어에 해당합니다. 이 코드는 직접 도메인 로직을 포함하지 않지만, 다음과 같은 DDD 구현을 지원합니다:

1. 도메인 로직을 실행할 기술적 환경 제공
2. API 엔드포인트를 통한 바운디드 컨텍스트 노출
3. 의존성 주입을 통한 헥사고날 아키텍처 지원
4. 유효성 검증을 통한 도메인 무결성 보장

구현 예시

import helmet from 'helmet';

async function bootstrap() {
  try {
    // 1. NestJS 애플리케이션 인스턴스 생성
    const app = await NestFactory.create(AppModule);
    
    // 2. 환경 설정 로딩
    const configService = app.get(ConfigService);
    const port = configService.get('PORT') || 3000;
    const apiPrefix = configService.get('API_PREFIX') || 'v1';
    const runtimeEnv = configService.get('RUNTIME_ENV') || 'LOCAL';
    
    // 3. Express 미들웨어 설정
    app.use(json({ limit: '50mb' }));
    app.use(urlencoded({ limit: '50mb', extended: true }));
    
    // Helmet 미들웨어 적용
    app.use(helmet());
    
    // CORS 설정
    app.enableCors({
      origin: configService.get<string>('CORS_ORIGIN'),
      methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
      credentials: true,
    });
    
    // 4. Google Cloud 인증 설정
    const credentialsPath = configService.get('GOOGLE_APPLICATION_CREDENTIALS');
    if (runtimeEnv === 'LOCAL') {
      // 로컬 개발 환경일 경우 상대 경로 해석
      process.env.GOOGLE_APPLICATION_CREDENTIALS = path.resolve(
        process.cwd(),
        credentialsPath
      );
    }
    // application-configuration.md 문서의 환경별 경로 참조
    
    // 5. API 접두사 설정
    app.setGlobalPrefix(apiPrefix);
    
    // 6. Swagger UI 설정
    const options = new DocumentBuilder()
      .setTitle('DTA WIDE API')
      .setDescription('DTA WIDE API 문서')
      .setVersion('1.0')
      .addBearerAuth()
      .build();
      
    const document = SwaggerModule.createDocument(app, options);
    SwaggerModule.setup(`${apiPrefix}/docs`, app, document);
    // application-configuration.md 문서의 환경별 설정 참조
    
    // 7. 유효성 검증 파이프라인 설정
    app.useGlobalPipes(
      new ValidationPipe({
        transform: true,
        whitelist: true,
        forbidNonWhitelisted: true,
      })
    );
    
    // 환경별 특화 설정
    if (runtimeEnv !== 'LOCAL') {
      // 클라우드 환경 특화 설정
      setupMonitoring(app);
    }
    
    // 8. 서버 리스닝 시작
    await app.listen(port);
    console.log(`Application is running on: ${await app.getUrl()}`);
  } catch (error) {
    console.error('Bootstrap error:', error);
    process.exit(1);
  }
}

bootstrap();

관련 아티팩트

• main.ts: 애플리케이션 부트스트랩 로직
• app.module.ts: 애플리케이션 모듈 정의
• .env: 환경 변수 기본값

보안 설정

CSRF 및 XSS 방어

Cross-Site Request Forgery (CSRF) 및 Cross-Site Scripting (XSS) 공격을 방어하기 위한 조치:

1. JSON 콘텐츠 타입 검증: Content-Type: application/json 헤더가 있는 요청만 허용
2. 입력 데이터 이스케이프 처리: HTML 태그 및 스크립트 문자를 이스케이프 처리
3. HTTP Only 및 Secure 쿠키 사용: 민감한 정보를 저장하는 쿠키에 HttpOnly 및 Secure 플래그 설정
4. Helmet 미들웨어 사용: HTTP 헤더 보안 강화

// main.ts
import helmet from 'helmet';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  // Helmet 미들웨어 적용
  app.use(helmet());
  
  // CORS 설정
  app.enableCors({
    origin: configService.get<string>('CORS_ORIGIN'),
    methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
    credentials: true,
  });
  
  // 글로벌 유효성 검증 파이프
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
    }),
  );
  
  await app.listen(configService.get<number>('PORT') || 3000);
}

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-03-20	bok@weltcorp.com	최초 작성
0.1.1	2025-03-21	bok@weltcorp.com	로깅 아키텍처 다이어그램 중앙화
0.1.2	2025-03-25	bok@weltcorp.com	보안 설정: CSRF 및 XSS 방어 섹션 추가