NestJS에서 구성(configuration)은 어떻게 관리하나요?

Question

Accepted Answer

NestJS는 구성과 환경 변수를 구조화되고, 타입 안전하며, 주입 가능한 방식으로 관리하기 위한 **`@nestjs/config`** 패키지를 제공합니다. `.env` 파일을 로드하고, 구성을 검증하며, 주입 가능한 `ConfigService`를 통해 앱 전체에서 값을 사용할 수 있게 합니다. ## ConfigModule 설정 ```ts import { ConfigModule } from "@nestjs/config"; @Module({ imports: [ ConfigModule.forRoot({ isGlobal: true, // 재import 없이 앱 전역에서 사용 가능 envFilePath: ".env", validationSchema: Joi.object({ // 시작 시 환경 변수 검증 (빠른 실패) DATABASE_URL: Joi.string().required(), PORT: Joi.number().default(3000), JWT_SECRET: Joi.string().required(), }), }), ], }) export class AppModule {} ``` `ConfigModule.forRoot()`는 환경 변수(`.env` + 프로세스 환경에서)를 로드하고 — 결정적으로 — 스키마(Joi)로 그것을 **검증**할 수 있어, 누락되거나 잘못된 구성이 런타임에 알 수 없이 실패하는 대신 시작 시 명확한 오류로 앱을 종료시킵니다. ## ConfigService를 통한 구성 읽기 (주입 가능) ```ts @Injectable() export class DatabaseService { constructor(private configService: ConfigService) {} // ConfigService 주입 connect() { const url = this.configService.get("DATABASE_URL"); const port = this.configService.get("PORT", 3000); // 기본값과 함께 } } ``` 어디서나 `process.env`를 직접 읽는 대신 `ConfigService`를 주입하고 `get()`을 호출합니다 — 타입 안전하고, 테스트 가능하며, 중앙화됩니다. ## 네임스페이스/타입 구성 ```ts // config/database.config.ts — registerAs로 관련 구성 그룹화 export default registerAs("database", () => ({ host: process.env.DB_HOST, port: parseInt(process.env.DB_PORT, 10), })); // 로드: ConfigModule.forRoot({ load: [databaseConfig] }) // 접근: configService.get("database.host") ``` 네임스페이싱은 관련 설정을 그룹화하고 구성이 커질수록 체계적으로 유지합니다. ## 왜 process.env를 직접 사용하지 않나요? ```text ✗ process.env가 여기저기 흩어짐 → 테스트 어려움, 검증 없음, 문자열 타입 ✓ ConfigService → 주입 가능(테스트에서 mock 가능), 시작 시 검증, 타입 지정, 중앙화 — 구조화된 NestJS 방식 ``` ## 비밀과 환경 ```text ✓ 비밀은 .env에 보관 (GITIGNORE) — 필요한 변수를 문서화하는 .env.example을 커밋 ✓ 프로덕션에서는 플랫폼의 환경 변수 / 비밀 관리자를 통해 구성 주입 ✓ 시작 시 검증하여 잘못된 구성이 명확한 메시지로 즉시 실패하게 함 ``` ## 왜 중요한가 적절한 구성 관리는 모든 실제 애플리케이션에 필수적입니다 — 데이터베이스 URL, API 키, 포트, 비밀, 기능 플래그를 환경(개발, 스테이징, 프로덕션)에 걸쳐 안전하고 유연하게 처리합니다. NestJS의 `@nestjs/config`는 이를 수행하는 구조화되고 관용적인 방법을 제공하며, 이를 이해하는 것은 중요한 일상 지식입니다. `process.env`를 직접 읽는 것에 비해 핵심 이점은 상당합니다: 주입 가능한 **`ConfigService`**는 구성을 테스트 가능하고(테스트에서 mock 가능) 중앙화되게 만듭니다; **시작 시 검증**(Joi 스키마와 함께)은 누락되거나 형식이 잘못된 구성을, 요청 깊은 곳의 혼란스러운 런타임 실패가 아니라 명확한 오류로 즉시 잡아냅니다; 그리고 네임스페이싱은 커지는 구성을 체계적으로 유지합니다. 비밀을 gitignore된 `.env` 파일에 보관하는(그리고 커밋된 `.env.example`) 보안 모범 사례와 결합하면, 안전하고 이식 가능하며 검증된 구성을 얻습니다. `ConfigModule`을 설정하고, `ConfigService`를 주입하고 사용하고, 구성을 검증하는 방법을 아는 것은 프로덕션 준비가 된 NestJS 애플리케이션을 구축하는 데 기본적이며 전문적인 백엔드 실무를 반영합니다.