3. NestJS 컨트롤러: RESTful API 엔드포인트 구축하기

NestJS

3. NestJS 컨트롤러: RESTful API 엔드포인트 구축하기

오늘의하늘은 2025. 3. 30. 15:16

NestJS 애플리케이션에서 컨트롤러(Controllers)는 클라이언트의 요청을 받고 응답을 반환하는 핵심 구성 요소입니다. 이번 글에서는 NestJS 컨트롤러를 활용하여 RESTful API 엔드포인트를 효과적으로 구축하는 방법을 살펴보겠습니다.

컨트롤러란 무엇인가?

컨트롤러는 클라이언트로부터 들어오는 요청을 처리하고 적절한 응답을 반환하는 역할을 합니다. NestJS에서 컨트롤러는 특정 경로(route)에 대한 처리를 담당하며, MVC(Model-View-Controller) 패턴의 'C' 부분에 해당합니다.

간단히 말하자면, 컨트롤러는 다음과 같은 일을 합니다:

특정 URL 경로에 대한 엔드포인트 정의
HTTP 메서드(GET, POST, PUT, DELETE 등)에 따른 핸들러 함수 제공
요청 데이터 검증 및 변환
비즈니스 로직 호출 (일반적으로 서비스를 통해)
클라이언트에게 응답 반환

기본 컨트롤러 생성하기

NestJS CLI를 사용하면 컨트롤러를 쉽게 생성할 수 있습니다:

nest generate controller users
# 또는 짧게
nest g co users

이 명령은 다음과 같은 파일을 생성합니다:

src/users/users.controller.ts: 컨트롤러 클래스
src/users/users.controller.spec.ts: 테스트 파일

생성된 기본 컨트롤러는 다음과 같습니다:

// src/users/users.controller.ts
import { Controller } from '@nestjs/common';

@Controller('users')
export class UsersController {}

여기서 @Controller('users') 데코레이터는 이 컨트롤러가 '/users' 경로에 대한 요청을 처리한다는 것을 의미합니다.

라우팅

NestJS에서 라우팅은 컨트롤러 클래스와 핸들러 메서드에 적용되는 데코레이터를 통해 정의됩니다. 기본적인 HTTP 메서드에 해당하는 데코레이터는 다음과 같습니다:

@Get(): GET 요청 처리
@Post(): POST 요청 처리
@Put(): PUT 요청 처리
@Delete(): DELETE 요청 처리
@Patch(): PATCH 요청 처리
@Options(): OPTIONS 요청 처리
@Head(): HEAD 요청 처리
@All(): 모든 HTTP 메서드 처리

예를 들어, 사용자 목록을 조회하는 GET 요청을 처리하는 라우트를 추가해 봅시다:

import { Controller, Get } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Get()
  findAll(): string[] {
    return ['user1', 'user2', 'user3'];
  }
}

이 코드에서 @Get() 데코레이터는 HTTP GET 요청을 처리하는 핸들러 메서드를 정의합니다. 따라서 '/users' 경로로 GET 요청이 들어오면 findAll() 메서드가 실행됩니다.

라우트 경로를 더 구체적으로 지정할 수도 있습니다:

@Get('active')
findActive(): string[] {
  return ['user1', 'user3'];
}

이 핸들러는 '/users/active' 경로에 대한 GET 요청을 처리합니다.

요청 객체 다루기

클라이언트 요청에서 정보를 추출하려면 @Req() 데코레이터를 사용하여 요청 객체에 접근할 수 있습니다:

import { Controller, Get, Req } from '@nestjs/common';
import { Request } from 'express';

@Controller('users')
export class UsersController {
  @Get()
  findAll(@Req() request: Request): string[] {
    console.log(request.url); // 요청 URL 출력
    console.log(request.headers); // 요청 헤더 출력
    return ['user1', 'user2', 'user3'];
  }
}

하지만 NestJS는 특정 요청 데이터를 추출하기 위한 전용 데코레이터를 제공하므로, 전체 요청 객체를 주입받는 대신 필요한 데이터만 쉽게 추출할 수 있습니다:

@Body(): 요청 본문
@Param(): 라우트 매개변수
@Query(): 쿼리 매개변수
@Headers(): 요청 헤더
@Ip(): 클라이언트 IP 주소

요청 페이로드

POST, PUT, PATCH 요청과 같이 본문을 포함하는 요청의 경우, @Body() 데코레이터를 사용하여 요청 본문에 접근할 수 있습니다:

import { Controller, Post, Body } from '@nestjs/common';

// DTO(Data Transfer Object) 정의
export class CreateUserDto {
  readonly name: string;
  readonly email: string;
  readonly age: number;
}

@Controller('users')
export class UsersController {
  @Post()
  create(@Body() createUserDto: CreateUserDto): string {
    console.log(createUserDto);
    return `User ${createUserDto.name} created successfully`;
  }
}

여기서 CreateUserDto는 클라이언트에서 전송되는 데이터의 구조를 정의합니다. 이렇게 DTO를 사용하면 타입 안전성이 보장되고 코드의 가독성이 향상됩니다.

응답 다루기

NestJS는 두 가지 응답 방식을 제공합니다:

표준 방식(권장): 핸들러 메서드의 반환값을 자동으로 JSON 응답으로 변환

@Get()
findAll(): string[] {
  return ['user1', 'user2', 'user3']; // 자동으로 JSON 응답으로 변환됨
}

라이브러리 특정 방식: @Res() 데코레이터를 사용하여 응답 객체에 직접 접근

import { Controller, Get, Res } from '@nestjs/common';
import { Response } from 'express';

@Controller('users')
export class UsersController {
  @Get()
  findAll(@Res() response: Response) {
    return response.status(200).json(['user1', 'user2', 'user3']);
  }
}

일반적으로는 첫 번째 방식이 권장됩니다. 이 방식을 사용하면 NestJS의 인터셉터, 예외 필터 등의 기능을 활용할 수 있기 때문입니다.

라우트 와일드카드

NestJS는 와일드카드를 사용한 유연한 라우팅을 지원합니다:

@Get('*')
findAll() {
  return 'This route handles all GET requests to paths starting with /users/';
}

이 핸들러는 '/users/' 이후의 모든 경로에 대한 GET 요청을 처리합니다.

상태 코드

기본적으로 NestJS는 POST 요청에 대해 201 상태 코드를, 나머지 요청에 대해 200 상태 코드를 응답합니다. 이를 변경하려면 @HttpCode() 데코레이터를 사용할 수 있습니다:

import { Controller, Post, HttpCode } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Post()
  @HttpCode(204) // No Content 상태 코드
  create() {
    return; // 응답 본문 없음
  }
}

헤더

사용자 정의 응답 헤더를 설정하려면 @Header() 데코레이터를 사용합니다:

import { Controller, Get, Header } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Get()
  @Header('Cache-Control', 'none')
  findAll() {
    return ['user1', 'user2', 'user3'];
  }
}

리디렉션

클라이언트를 다른 URL로 리디렉션하려면 @Redirect() 데코레이터를 사용하거나 라우트 핸들러에서 응답 객체를 반환할 수 있습니다:

import { Controller, Get, Redirect } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Get('old-path')
  @Redirect('https://example.com/users', 301) // 301: Moved Permanently
  redirectToNewPath() {
    // 리디렉션 처리
  }
  
  @Get('dynamic-redirect')
  dynamicRedirect() {
    // 조건에 따라 다른 URL로 리디렉션
    const condition = true;
    if (condition) {
      return { url: 'https://example.com/users', statusCode: 302 };
    }
    return { url: 'https://example.com/admins', statusCode: 302 };
  }
}

하위 도메인 라우팅

NestJS는 하위 도메인 기반 라우팅을 지원합니다. 이를 위해 @Controller() 데코레이터의 host 옵션을 사용합니다:

import { Controller, Get, HostParam } from '@nestjs/common';

@Controller({ host: ':account.example.com', path: 'users' })
export class UsersController {
  @Get()
  findAll(@HostParam('account') account: string) {
    return `This is the users page for account: ${account}`;
  }
}

이 예제에서는 하위 도메인이 account.example.com 형식인 경우 해당 라우트가 매치됩니다.

전체 CRUD 컨트롤러 예제

이제 지금까지 배운 내용을 토대로 사용자 리소스에 대한 전체 CRUD(Create, Read, Update, Delete) 작업을 처리하는 컨트롤러를 구현해 보겠습니다:

먼저, 필요한 DTO를 정의합니다:

// src/users/dto/create-user.dto.ts
export class CreateUserDto {
  readonly name: string;
  readonly email: string;
  readonly age: number;
}

// src/users/dto/update-user.dto.ts
export class UpdateUserDto {
  readonly name?: string;
  readonly email?: string;
  readonly age?: number;
}

다음으로, 사용자 인터페이스를 정의합니다:

// src/users/interfaces/user.interface.ts
export interface User {
  id: number;
  name: string;
  email: string;
  age: number;
}

이제 컨트롤러를 구현합니다:

// src/users/users.controller.ts
import { Controller, Get, Post, Put, Delete, Body, Param, Query, HttpStatus, HttpException } from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';
import { User } from './interfaces/user.interface';

@Controller('users')
export class UsersController {
  // 실제 애플리케이션에서는 이 데이터가 서비스에서 관리됩니다
  private users: User[] = [
    { id: 1, name: '홍길동', email: 'hong@example.com', age: 30 },
    { id: 2, name: '김철수', email: 'kim@example.com', age: 25 },
  ];

  @Get()
  findAll(@Query('name') name?: string): User[] {
    if (name) {
      return this.users.filter(user => user.name.includes(name));
    }
    return this.users;
  }

  @Get(':id')
  findOne(@Param('id') id: string): User {
    const user = this.users.find(user => user.id === Number(id));
    
    if (!user) {
      throw new HttpException(`User with ID ${id} not found`, HttpStatus.NOT_FOUND);
    }
    
    return user;
  }

  @Post()
  create(@Body() createUserDto: CreateUserDto): User {
    const newUser: User = {
      id: this.users.length + 1,
      ...createUserDto,
    };
    
    this.users.push(newUser);
    return newUser;
  }

  @Put(':id')
  update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto): User {
    const userIndex = this.users.findIndex(user => user.id === Number(id));
    
    if (userIndex === -1) {
      throw new HttpException(`User with ID ${id} not found`, HttpStatus.NOT_FOUND);
    }
    
    this.users[userIndex] = {
      ...this.users[userIndex],
      ...updateUserDto,
    };
    
    return this.users[userIndex];
  }

  @Delete(':id')
  remove(@Param('id') id: string): { message: string } {
    const userIndex = this.users.findIndex(user => user.id === Number(id));
    
    if (userIndex === -1) {
      throw new HttpException(`User with ID ${id} not found`, HttpStatus.NOT_FOUND);
    }
    
    this.users.splice(userIndex, 1);
    return { message: `User with ID ${id} removed successfully` };
  }
}

이 컨트롤러는 다음과 같은 엔드포인트를 제공합니다:

GET /users: 모든 사용자 목록 조회 (선택적으로 이름으로 필터링)
GET /users/:id: ID로 특정 사용자 조회
POST /users: 새 사용자 생성
PUT /users/:id: 특정 사용자 정보 업데이트
DELETE /users/:id: 특정 사용자 삭제

정리

이번 글에서는 NestJS의 컨트롤러를 활용하여 RESTful API 엔드포인트를 구축하는 방법을 알아보았습니다. 컨트롤러는 클라이언트 요청을 처리하고 적절한 응답을 반환하는 역할을 하며, NestJS는 이를 위한 다양한 데코레이터와 기능을 제공합니다.

실제 애플리케이션에서는 컨트롤러에 비즈니스 로직을 직접 구현하지 않고, 서비스 계층을 통해 비즈니스 로직을 분리하는 것이 좋습니다. 이는 코드의 재사용성과 테스트 용이성을 향상시키는 데 도움이 됩니다.

다음 글에서는 NestJS의 프로바이더와 서비스에 대해 알아보고, 컨트롤러와 함께 더욱 체계적인 애플리케이션을 구축하는 방법을 살펴보겠습니다.

'NestJS' 카테고리의 다른 글

5. NestJS 모듈: 애플리케이션 구조화와 모듈간 의존성 관리 (0)	2025.03.30
4. NestJS 프로바이더와 서비스: 비즈니스 로직 분리하기 (0)	2025.03.30
2. NestJS 설치 및 첫 번째 프로젝트 구성하기 (0)	2025.03.30
1. NestJS 소개: 철학, 아키텍처, Express와의 차이점 (0)	2025.03.30
NestJS 소개: 현대적인 백엔드 개발을 위한 프레임워크 (2)	2025.03.28

현재글3. NestJS 컨트롤러: RESTful API 엔드포인트 구축하기

Todayssky

평생 개발하기!!!

typescript, 모듈화, combine, 액세스제어, swift, Express, 백엔드개발, Xcode, 예외처리전략, HTTP, 백준, 백엔드아키텍처, 웹개발, flutter, nodeJS, SwiftUI, 오류핸들링, IOS, 의존성주입, nestjs,

Today :
Yesterday :

일	월	화	수	목	금	토
		1	2	3	4	5
6	7	8	9	10	11	12
13	14	15	16	17	18	19
20	21	22	23	24	25	26
27	28	29	30

Todayssky