Nest.js에서의 컨트롤러: 웹 애플리케이션의 중추적 역할

Nest.js는 현대적인 웹 애플리케이션을 구축하기 위한 강력한 프레임워크로, 그 핵심 구성 요소 중 하나가 바로 컨트롤러입니다. 컨트롤러는 클라이언트의 요청을 처리하고 적절한 응답을 반환하는 중요한 역할을 수행합니다. 이번 포스트에서는 Nest.js의 컨트롤러에 대해 깊이 있게 살펴보고, 그 역할과 기능, 기본적인 예제, 요청 핸들링 과정, 에러 핸들링 및 응답 상태 코드 설정에 대해 알아보겠습니다.

컨트롤러의 역할과 기능

컨트롤러는 웹 애플리케이션의 비즈니스 로직과 데이터 흐름을 조율하는 중추적인 역할을 합니다. 다음은 컨트롤러의 주요 기능입니다.

1. 요청 라우팅

   • 클라이언트가 보낸 요청이 어떤 경로를 가졌는지에 따라 해당 요청을 적절한 함수(핸들러)에 전달합니다. 이 과정에서 요청의 메서드(GET, POST 등)와 URL 경로를 분석하여 적합한 핸들러를 선택합니다.

2. 비즈니스 로직 호출

   • 요청이 들어오면, 비즈니스 로직(주로 서비스)을 호출하여 데이터를 처리하거나 필요한 작업을 수행합니다. 이 단계에서 컨트롤러는 서비스와의 상호작용을 통해 데이터베이스와의 연결, 외부 API 호출 등 다양한 작업을 수행할 수 있습니다.

3. 응답 생성

   • 비즈니스 로직의 결과를 기반으로 클라이언트에게 반환할 응답 객체를 생성합니다. 이 응답 객체는 클라이언트가 요청한 데이터뿐만 아니라, 요청 처리의 결과에 대한 상태 메시지나 오류 정보를 포함할 수 있습니다.

기본적인 예제

아래는 간단한 사용자 정보를 관리하는 컨트롤러 예제입니다.

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

@Controller('users') // '/users' 경로에 대한 모든 요청 처리
export class UsersController {

  private users = []; // 메모리에 저장될 사용자 목록

  @Get() // GET /users
  getAllUsers() {
    return this.users; // 모든 사용자 정보 반환
  }

  @Post() // POST /users
  createUser(@Body() userDto: { name: string; age: number }) {
    this.users.push(userDto); // 새로운 사용자 추가
    return { message: 'User created successfully', user: userDto };
  }
}

위 코드에서 @Controller 데코레이터는 이 클래스가 사용자의 /users 경로에 대한 모든 요청을 처리하도록 지정합니다. @Get()과 @Post() 데코레이터는 각각 GET 및 POST HTTP 메서드를 나타내며, 해당 메서드에 맞게 함수를 정의해 줍니다. 이러한 구조는 코드의 가독성을 높이고, 각 메서드의 역할을 명확히 하여 유지보수를 용이하게 합니다.

요청 핸들링 과정 설명

1. GET /users

   • 사용자가 /users URL로 GET 요청을 보내면, getAllUsers() 함수가 호출되어 현재 저장된 모든 사용자를 배열 형태로 반환합니다. 이 과정에서 사용자는 현재 시스템에 등록된 모든 사용자 정보를 손쉽게 조회할 수 있습니다.

2. POST /users

   • 사용자가 /users URL로 POST 요청과 함께 JSON 형식으로 { "name": "John", "age": 30 } 같은 데이터를 보내면, createUser() 함수가 실행됩니다.
   • 여기서 @Body() 데코레이터를 통해 전송된 데이터(body)를 가져옵니다. 이 데이터는 새로운 사용자의 이름과 나이를 포함하고 있으며, 이를 통해 사용자를 생성하는 데 필요한 정보를 제공합니다.
   • 새롭게 추가된 사용자는 메모리에 저장되고, 성공 메시지가 포함된 객체가 응답으로 돌아갑니다. 이 응답은 클라이언트에게 요청이 성공적으로 처리되었음을 알리는 중요한 역할을 합니다.

에러 핸들링 및 응답 상태 코드 설정

Nest.js에서는 다양한 방법으로 오류 처리를 할 수 있습니다:

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

@Controller('items')
export class ItemsController {

  @Get(':id')
  getItemById(id: string) {
    const item = this.findItemById(id);

    if (!item) {
      throw new HttpException('Item not found', HttpStatus.NOT_FOUND); 
      // 아이템이 없으면 NOT FOUND 상태 코드를 가진 예외 발생
    }

    return item;
  }

}

여기서 만약 주어진 ID에 해당하는 아이템이 없다면 HttpException 클래스를 이용해 적절한 에러 메시지와 상태 코드를 반환하게 됩니다. 이러한 에러 핸들링은 클라이언트가 요청 처리 과정에서 발생할 수 있는 문제를 인지하고, 적절한 조치를 취할 수 있도록 돕습니다.

결론

컨트롤러는 Nest.js 애플리케이션에서 중요한 역할을 하며 클라이언트와 서버 간의 인터랙션 포인트입니다. 각종 HTTP 요청(method)에 대해 어떻게 반응하고 데이터를 어떻게 처리하며 응답할지를 잘 설계해야 효율적이고 안정적인 웹 서비스를 구축할 수 있습니다. 이러한 구조화된 접근 방식 덕분에 개발자는 명확하게 책임 분담이 가능하고 유지보수 또한 용이해집니다. 컨트롤러의 설계와 구현은 애플리케이션의 전반적인 품질과 성능에 큰 영향을 미치므로, 신중하게 접근해야 합니다.