NestJS로 기본 API 서버 파일 정리

NestJS는 Node.js 기반의 TypeScript 지원 백엔드 프레임워크로, 구조적이고 확장성 있는 서버 애플리케이션을 만들 수 있게 해줍니다. 이 글에서는 NestJS로 API 서버를 시작할 때 생성되는 핵심 파일들을 하나씩 살펴보며, 각각의 역할과 코드 구조를 자세히 설명합니다.

---

📁 NestJS 기본 파일 구조

NestJS를 생성하면 기본적으로 다음과 같은 파일들이 포함됩니다:

• app.module.ts
• app.controller.ts
• app.service.ts
• app.controller.spec.ts

이번 글에서는 이 네 파일의 구조와 기능을 코드 중심으로 살펴봅니다.

---

✅ app.module.ts - 앱의 루트 모듈

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

@Module() 데코레이터는 NestJS에서 의존성 주입과 모듈화를 관리하는 핵심입니다.

• controllers: API 요청을 처리할 컨트롤러 등록
• providers: 서비스나 헬퍼 클래스를 의존성 주입으로 연결

AppModule은 Nest 애플리케이션의 진입점이자 구성의 중심 역할을 합니다.

---

✅ app.controller.ts - 요청을 받아 처리하는 컨트롤러

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }
}

이 컨트롤러는 HTTP 요청을 받아 해당 메서드로 연결합니다.

• @Controller(): 이 클래스가 컨트롤러임을 명시
• @Get(): HTTP GET 메서드와 매핑
• appService.getHello(): 실제 로직은 서비스에 위임

NestJS는 컨트롤러와 서비스의 역할을 명확히 분리합니다.

---

✅ app.service.ts - 로직을 처리하는 서비스

import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

• @Injectable(): Nest가 이 클래스를 의존성 주입할 수 있게 함
• getHello(): 간단한 문자열을 반환하는 예시 메서드

이처럼 서비스는 비즈니스 로직을 처리하고, 컨트롤러는 요청/응답만 담당합니다.

---

✅ app.controller.spec.ts - 기본 컨트롤러 테스트

import { Test, TestingModule } from '@nestjs/testing';
import { AppController } from './app.controller';
import { AppService } from './app.service';

describe('AppController', () => {
  let appController: AppController;

  beforeEach(async () => {
    const app: TestingModule = await Test.createTestingModule({
      controllers: [AppController],
      providers: [AppService],
    }).compile();

    appController = app.get(AppController);
  });

  describe('root', () => {
    it('should return "Hello World!"', () => {
      expect(appController.getHello()).toBe('Hello World!');
    });
  });
});

NestJS에서는 @nestjs/testing 모듈을 활용해 유닛 테스트를 작성할 수 있습니다.

• Test.createTestingModule: 의존성을 포함한 테스트 모듈 생성
• expect(...).toBe(...): 반환 값을 검증하는 Jest 문법

---

📌 정리

파일명	역할
app.module.ts	루트 모듈로 앱 전체 구성
app.controller.ts	HTTP 요청 수신 및 라우팅
app.service.ts	핵심 로직 처리
app.controller.spec.ts	컨트롤러 테스트 코드

---

 

✅ app.e2e-spec.ts - E2E 테스트 예제

import * as request from 'supertest';
import { Test } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import { AppModule } from './../src/app.module';

describe('AppController (e2e)', () => {
  let app: INestApplication;

  beforeAll(async () => {
    const moduleFixture = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  it('/ (GET)', () => {
    return request(app.getHttpServer())
      .get('/')
      .expect(200)
      .expect('Hello World!');
  });
});

이 파일은 E2E(End-to-End) 테스트를 정의합니다. 실제 HTTP 요청을 보내서 API의 전체 흐름을 검증하는 데 사용됩니다.

• supertest: HTTP 요청을 시뮬레이션하는 라이브러리
• Test.createTestingModule(): 테스트 전용 Nest 앱 모듈 생성
• app.getHttpServer(): Nest 앱의 실제 HTTP 서버에 접근
• expect(...): 응답 코드와 본문을 검증

E2E 테스트는 실제 사용자 요청 시나리오를 자동화하는 데 효과적이며, 특히 통합된 컴포넌트 간의 흐름 테스트에 유용합니다.

---

✅ jest-e2e.json - E2E 테스트 환경 설정

{
  "moduleFileExtensions": ["js", "json", "ts"],
  "rootDir": ".",
  "testEnvironment": "node",
  "testRegex": ".e2e-spec.ts$",
  "transform": {
    "^.+\\.(t|j)s$": "ts-jest"
  }
}

이 설정 파일은 Jest 테스트 러너가 E2E 테스트를 어떻게 실행할지 정의합니다.

• moduleFileExtensions: 사용할 파일 확장자
• rootDir: 프로젝트 루트 디렉토리
• testEnvironment: 테스트 환경 (Node.js)
• testRegex: 어떤 파일이 테스트인지 정규식으로 지정 (예: .e2e-spec.ts)
• transform: TypeScript를 Jest에서 인식하도록 ts-jest 적용

이 설정을 기반으로 jest --config jest-e2e.json 명령어를 통해 E2E 테스트를 실행할 수 있습니다.

---

📌 E2E 테스트 요약

파일	역할
app.e2e-spec.ts	API의 전체 흐름을 시뮬레이션하고 응답을 검증
jest-e2e.json	테스트 환경, 변환기, 대상 파일 등 설정 정의

E2E 테스트는 실제 API를 배포하기 전, 실제와 유사한 환경에서 통합 테스트를 수행할 수 있게 해 줍니다.

---

✅ .prettierrc - 코드 스타일 포맷 설정

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "printWidth": 100,
  "trailingComma": "all",
  "endOfLine": "auto"
}

Prettier 설정 파일로, 코드 스타일을 자동으로 정리하는 기준을 정의합니다.

• semi: 세미콜론 사용 여부
• singleQuote: 작은따옴표 사용
• tabWidth: 들여쓰기 간격
• printWidth: 한 줄 최대 길이
• trailingComma: 마지막 쉼표 유지 여부

---

✅ eslint.config.mjs - 린트 및 Prettier 연동 설정

// @ts-check
import eslint from '@eslint/js';
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
import globals from 'globals';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  {
    ignores: ['eslint.config.mjs'],
  },
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  eslintPluginPrettierRecommended,
  {
    languageOptions: {
      globals: {
        ...globals.node,
        ...globals.jest,
      },
      ecmaVersion: 5,
      sourceType: 'module',
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
  {
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
      '@typescript-eslint/no-floating-promises': 'warn',
      '@typescript-eslint/no-unsafe-argument': 'warn'
    },
  },
);

이 구성은 TypeScript + ESLint + Prettier가 함께 동작하도록 구성된 고급 설정입니다.

• typescript-eslint: 타입 기반 린팅
• eslint-plugin-prettier: 포맷팅을 ESLint 룰로 강제
• ecmaVersion: 5: ECMAScript 5까지 지원
• TSConfig와 연동해 정적 분석 수행

---

✅ nest-cli.json - Nest CLI 설정

{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "deleteOutDir": true
  }
}

이 설정은 nest-cli에서 Nest 프로젝트를 빌드하거나 generate할 때의 기본 동작을 제어합니다.

• collection: Nest schematics 기반
• sourceRoot: 소스 루트는 src/
• deleteOutDir: 빌드 시 dist 디렉토리 제거

---

✅ tsconfig.json - TypeScript 전역 설정

{
  "compilerOptions": {
    "module": "commonjs",
    "declaration": true,
    "removeComments": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "allowSyntheticDefaultImports": true,
    "target": "ES2023",
    "sourceMap": true,
    "outDir": "./dist",
    "baseUrl": "./",
    "incremental": true,
    "skipLibCheck": true,
    "strictNullChecks": true,
    "forceConsistentCasingInFileNames": true,
    "noImplicitAny": false,
    "strictBindCallApply": false,
    "noFallthroughCasesInSwitch": false
  }
}

tsconfig.json은 프로젝트 전반의 TypeScript 컴파일 설정을 담당합니다.

• emitDecoratorMetadata, experimentalDecorators: NestJS에 필수
• strictNullChecks: 엄격한 타입 검사
• target: ES2023으로 최신 JS 출력
• outDir: dist/ 디렉토리에 컴파일 결과 저장

---

✅ tsconfig.build.json - 빌드 전용 설정

{
  "extends": "./tsconfig.json",
  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
}

이 파일은 빌드 시에만 사용되는 tsconfig로, 테스트 파일 및 불필요한 폴더를 제외합니다.

• extends: 메인 tsconfig를 기반으로 함
• exclude: 테스트, 빌드 산출물 제외

---

✅ pnpm-lock.yaml - 의존성 버전 고정

pnpm-lock.yaml은 의존성 관리에 사용하는 lock 파일로, 다음을 고정합니다:

• NestJS: @nestjs/common, @nestjs/core → v11.0.12
• 타입스크립트: v5.8.2
• 테스트 도구: jest, supertest, ts-jest
• 코드 스타일링: eslint, prettier, typescript-eslint

pnpm을 사용하면 의존성 설치가 빠르고, 프로젝트 간 중복 없이 효율적입니다.

---

✅ 마무리

이번 포스팅에서는 NestJS 프로젝트의 설정 파일들을 정리해 보았습니다.