본문으로 건너뛰기

앱 설정 (AppConfig)

개요​

AppConfig는 애플리케이션의 기본적인 운영 설정을 관리합니다. 애플리케이션 식별자, 서버 실행 환경, 배포 환경 등 핵심 설정값을 정의합니다.

구성 요소​

핵심 설정 값​

설정 키환경 변수타입필수 여부기본값설명
nameAPP_NAMEstring선택'dta-wide-api'애플리케이션 이름
portPORTnumber선택3000서버 포트
hostHOSTstring선택'localhost'서버 호스트
runtimeEnvRUNTIME_ENVstring선택'local'런타임 환경 ('local' 또는 'cloudrun')
deployEnvDEPLOY_ENVstring필수'dev'배포 환경 ('dev', 'staging', 'prod')
serviceNameSERVICE_NAMEstring필수-서비스 이름 (클라우드 런 서비스 식별자)
apiHostAPI_HOSTstring필수(cloudrun)'http://localhost:3000'(local)API 서버 호스트 URL

사용 예시​

구성 정의​

// libs/core/config/src/lib/namespaces/app.config.ts
import { registerAs } from '@nestjs/config';

export const appConfig = registerAs('app', () => ({
  name: process.env.APP_NAME || 'dta-wide-api',
  port: parseInt(process.env.PORT || '3000', 10),
  host: process.env.HOST || 'localhost',
  runtimeEnv: process.env.RUNTIME_ENV || 'local',
  deployEnv: process.env.DEPLOY_ENV || 'dev',
  serviceName: process.env.SERVICE_NAME || 'dta-wide-api',
  apiHost: process.env.API_HOST || 'http://localhost:3000',
}));

유효성 검증 스키마​

// libs/core/config/src/lib/schemas/app.schema.ts
import * as Joi from 'joi';

export const appConfigSchema = {
  APP_NAME: Joi.string().default('dta-wide-api'),
  PORT: Joi.number().default(3000),
  HOST: Joi.string().default('localhost'),
  NODE_ENV: Joi.string()
    .valid('development', 'test', 'production')
    .default('development'),
  RUNTIME_ENV: Joi.string()
    .valid('local', 'cloudrun')
    .default('local'),
  DEPLOY_ENV: Joi.string()
    .valid('dev', 'staging', 'prod')
    .default('dev'),
  SERVICE_NAME: Joi.string().required(),
  API_HOST: Joi.string().when('RUNTIME_ENV', {
    is: 'local',
    then: Joi.string().default('http://localhost:3000'),
    otherwise: Joi.string().required(),
  }),
};

서비스에서 사용​

// 앱 설정 사용 예시
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@core/config';

@Injectable()
export class AppService {
  constructor(private readonly configService: ConfigService) {}

  getAppInfo() {
    // 네임스페이스 객체로 접근
    const appConfig = this.configService.getNamespace<{
      name: string;
      port: number;
      host: string;
      runtimeEnv: string;
      deployEnv: string;
      serviceName: string;
      apiHost: string;
    }>('app');

    // 또는 개별 설정 값에 접근
    const serviceName = this.configService.getRequiredConfig<string>('app', 'serviceName');
    const deployEnv = this.configService.getConfig<string>('app', 'deployEnv', 'dev');
    
    return {
      name: appConfig.name,
      environment: `${appConfig.runtimeEnv}/${appConfig.deployEnv}`,
      serviceUrl: appConfig.apiHost,
      isLocalEnvironment: appConfig.runtimeEnv === 'local',
    };
  }
}

환경별 설정 가이드​

로컬 개발 환경​

로컬 개발 환경에서는 서비스별 JSON 설정 파일을 통해 설정합니다. .env 파일은 사용하지 않습니다.

// cloudrun-deploy/secret/local/dev/dta-wide-api.json
{
  "RUNTIME_ENV": "local",
  "DEPLOY_ENV": "dev",
  "APP_NAME": "dta-wide-local-dev",
  "PORT": "3333",
  "HOST": "localhost",
  "SERVICE_NAME": "dta-wide-api",
  "API_HOST": "http://localhost:3333"
}

클라우드 런 환경​

클라우드 런 환경에서는 서비스별 JSON 설정 파일의 내용이 Cloud Run 서비스의 환경 변수로 설정됩니다. 배포 프로세스에서 이 설정을 자동으로 적용합니다.

// cloudrun-deploy/secret/cloudrun/prod/dta-wide-api.json
{
  "RUNTIME_ENV": "cloudrun",
  "DEPLOY_ENV": "prod",
  "APP_NAME": "dta-wide-api",
  "PORT": "8080",
  "SERVICE_NAME": "dta-wide-api",
  "API_HOST": "https://dta-wide-api.weltcorp.com"
}

주의 사항​

  • SERVICE_NAME은 반드시 설정해야 하며, 클라우드 런 서비스 이름과 일치해야 합니다.
  • 로컬 환경이 아닌 경우 API_HOST는 반드시 설정해야 합니다.
  • DEPLOY_ENV 값에 따라 다른 환경 설정이 로드될 수 있으므로 정확히 설정해야 합니다.