🦅 게시판(Board) 만들기

지난 포스팅에서 우리는 NestJS가 "Node.js 위의 Spring"이라는 것을 알았습니다.

이번에는 이론을 넘어 실제 작동하는 게시판(Board) API를 만들어보겠습니다.

단, 복잡도를 줄이기 위해 이번 편에서는 데이터베이스(DB)와 유효성 검증(Validation Pipe)은 진행하지 않습니다.
또한 Javascript 배열(Array)을 이용한 In-Memory 방식으로 진행합니다.

🛠️ 기본 구성 진행 - With CLI

신규 도메인을 생성할때, NestJS 에서는 CLI 로 간편하게 구조를 생성할 수 있습니다.

앞선 글-Module을 통해, Controller, Repository, Service, Module 등 다양한 typescript 파일을 생성해야 하는 것을 확인하였습니다.

이러한 작업을 간단하게 CLI 을 통해 한번에 진행할 수 있습니다.

도메인 생성

다음과 같은 명령어를 추가해, 새로운 도메인을 생성합니다.

$ nest g resource boards

g : Generate - 생성
resource : 리소스 (Controller, Service, Module, DTO, Entity 등을 한번에)
boards : 생성할 도메인 이름 (복수형 권장)

몇가지 추가 설정

$ nest g resource boards
? What transport layer do you use?
❯ REST API
  GraphQL (code first)
  GraphQL (schema first)
  Microservice (non-HTTP)
  WebSockets

↑↓ navigate • ⏎ select

어떠한 형식의 Resource 를 생성할 것인지 물어봅니다.
👉 저희는 REST API 를 생성할 것이기 때문에, REST API 를 선택합니다.

Would you like to generate CRUD entry points? (Y/n)

CRUD Entiry Points 를 만들어줄까 물어봅니다.
👉 저희는 수동으로 생성할 것이기 때문에 N 를 선택해 줍니다.

결과적으로 다음과 같은 작업이 추가됩니다.

CREATE src/boards/boards.controller.ts (223 bytes)
CREATE src/boards/boards.module.ts (264 bytes)
CREATE src/boards/boards.service.ts (94 bytes)
UPDATE src/app.module.ts (326 bytes)
✔ Packages installed successfully.

Tip: 테스트 파일(spec.ts)이 필요 없다면 --no-spec 옵션을 붙이면 됩니다. nest g resource boards --no-spec

특정 리소스만 생성 - nest new 옵션 알아보기

특정한 리소스만 생성하거나, ts/js 를 선택할 수도 있습니다.

예를 들어, nest g controller user 을 실행하면, userController 만 만들어 집니다.

이때, user.module.ts 가 없다면, 등록할 곳으로 최상위 app.module.ts 로 등록하게 됩니다.

다양한 옵션은 공식문서를 통해 확인이 가능합니다!

📝 Model 정의하기

DB는 없지만, 데이터의 형태는 정의하도록 하겠습니다.

보통 src/{domain}/entites 경로에 생성하게 됩니다.

src/boards/entites/board.entity.ts

import { BoardStatus } from "./board-status.enum";

export class Board {
  id: string;
  title: string;
  description: string;
  status: BoardStatus;
}

src/boards/entites/board-status.enum.ts

export enum BoardStatus {
  PUBLIC = 'PUBLIC',
  PRIVATE = 'PRIVATE',
}

🚀 CRUD - Create 작업

생성된 Model 과 Controller, Service 를 통해 CRUD 중 Create 를 작업 해보겠습니다.

Board 저장 생성 - service

현재 별도의 DB 없이 인메모리에서 데이터를 관리할 예정입니다.

따라서, service 에서는 Board를 타입으로 가지는 배열을 생성해주도록 하겠습니다.

board.service.ts

@Injectable()
export class BoardsService {
  private boards: Board[] = [];
}

DTO 생성

boards, 즉 새로운 글을 등록하기 위해서는 현재 제목(title), 설명(description)이 필요합니다.

id 와 status 는 각자 자동으로 생성되도록 구성할 예정입니다.

따라서, 이 두개를 api 요청으로 받을 수 있도록 dto 로 구성합니다.

글 작성 후, 완료된 글에 대한 정보를 응답할 대 사용할 dto 또한 필요합니다.

2가지 dto 를 생성해주도록 하겠습니다.

create-board.dto.ts

import { BoardStatus } from "../entities/board-status.enum";

export class CreateBoardRequest {
  title: string;
  description: string;
}

export class CreateBoardResponse {
  id: string;
  title: string;
  description: string;
  status: BoardStatus;
}

Q) CreateBoardResponse는 필요없지 않나요? 그냥 Entity 객체를 내보내면 되잖아요.
A) 필연적으로 Entity 객체를 내보내게 될 경우, 보안의 문제가 발생하게 됩니다.
현재는 매우 간단한 Entity 로 구성되어있어 큰 문제가 없지만, 내부적으로 공개하지 말아야 할 정보가 Entity 에 포함된 경우에는 문제가 됩니다.
예시로 회원가입 후, 비밀번호가 그대로 반환된다고 생각을 해봅시다.
Entity 자체를 반환해서 응답으로 사용하는건 매우 안티 패턴입니다!

Service 마무리 - 생성 및 저장

파라미터로 위에서 생성한 CreateBoardRequest을 받아와 데이터를 저장하고, 응답CreateBoardResponse)을 생성하는 함수를 작성하도록 하겠습니다.

boards.service.ts

import { Injectable } from '@nestjs/common';
import { Board } from './entities/board.entity';
import { CreateBoardRequest, CreateBoardResponse } from './dto/create-board.dto';
import { randomUUID } from 'crypto';
import { BoardStatus } from './entities/board-status.enum';

@Injectable()
export class BoardsService {
  private boards: Board[] = [];

  createBoard(createBoardDto: CreateBoardRequest): CreateBoardResponse {
    const { title, description } = createBoardDto;
    const board: Board = {
      id: randomUUID(),
      title,
      description,
      status: BoardStatus.PUBLIC,
    }

    this.boards.push(board);

    const response: CreateBoardResponse = {
      id: board.id,
      title: board.title,
      description: board.description,
      status: board.status,
    }
    return response;
  }
}

ID 는, 고유 식별자로써 활용 되어야 합니다.
즉, 수십 수백, 수억개의 데이터가 쌓인 상태에서도 id 는 중복이 없이 고유해야 합니다.

Controller 작성 - 진입점 생성

작성한 서비스를 활용해 저장을 진행하고, 외부에 오픈할 end-point 를 작성해주도록 하겠습니다.

boards.controller.ts

import { Body, Controller, Post } from '@nestjs/common';
import { BoardsService } from './boards.service';
import { CreateBoardRequest, CreateBoardResponse } from './dto/create-board.dto';

@Controller('boards')
export class BoardsController {
  constructor(private readonly boardsService: BoardsService) {}

  @Post()
  createBoard(@Body() createBoardDto: CreateBoardRequest): CreateBoardResponse {
    const response = this.boardsService.createBoard(createBoardDto);
    return response;
  }
}

저희는 현재 Post 로 필요한 데이터인, 제목(title) 과 내용(description)을 받아와야 합니다.

이때 @Body() decorator 를 통해 받아오도록 구성합니다.

🤔 데코레이터(Decorator) 란?
클래스, 메서드, 프로퍼티, 파라미터에 추가 동작을 붙이는 함수
TypeScript 문법입니다.

위에서 작성된 @Controller(), @Post() 등도 모두 데코레이터 입니다.

테스트 - Postman

postman 등을 통해 api 를 호출해 봅니다.

[POST] http://localhost:3000/boards

NestJS 에서는 POST 를 사용할 때, 응답 상태가 기본 201(created) 입니다.

만약 변경을 하고 싶다면 controller 코드에서 다음과 같이 @HttpCode(200) 을 지정하여 변경해 줍니다.

...
  @Post()
  @HttpCode(200) // 201이 기본이지만 200으로 설정
  createBoard(@Body() createBoardDto: CreateBoardRequest): CreateBoardResponse {
    const response = this.boardsService.createBoard(createBoardDto);
    return response;
  }
...

🚀 CRUD - Read 작업

생성이 완료되었다면, 조회를 진행해봐야겠죠.

2가지를 구현하도록 하겠습니다.

저장된 전체 목록 조회
id(고유식별자)를 활용한 특정 board 조회

전체 아이템 조회 - 서비스 코드 작성

기존 작성된 BoardsService 에 다음과 같은 함수를 추가해줍니다.

boards.service.ts

  createBoard(createBoardDto: CreateBoardRequest): CreateBoardResponse {//기존 코드...}

  findAllBoards(): FindBoardResponse[] {
    return this.boards.map(
      (board): FindBoardResponse => ({
        id: board.id,
        title: board.title,
        description: board.description,
        status: board.status,
      }),
    );
  }

현재 boards 들을 모두 가져와 배열 메서드인 map 을 통해 FindBoardResponse 로 변환해 반환합니다.

특정 아이템 조회 - 서비스 코드 작성

마찬가지로 service 에 추가합니다.

boards.service.ts

 findBoard(id: string): FindBoardResponse {
    const board = this.boards.find((board) => board.id === id);
    if (!board) {
      throw new Error('Board not found');
    }
    return board;
  }

Controller 작성

@Controller('boards')
export class BoardsController {
  constructor(private readonly boardsService: BoardsService) {}

  @Post()
  @HttpCode(200) // 201이 기본이지만 200으로 설정
  createBoard(@Body() createBoardDto: CreateBoardRequest): CreateBoardResponse {
    const response = this.boardsService.createBoard(createBoardDto);
    return response;
  }

  @Get()
  @HttpCode(200)
  findAllBoards(): FindBoardResponse[] {
    const response = this.boardsService.findAllBoards();
    return response;
  }

  @Get(':id')
  @HttpCode(200)
  findBoard(@Param('id') id: string): FindBoardResponse {
    const response = this.boardsService.findBoard(id);
    return response;
  }
}

2가지 API 를 작성합니다.

이때 특정 id 를 기반으로 가저오는 findBoard() 는 @Param 을 사용하여 URL 경로에 있는 동적인 값을 가져옵니다.

데코레이터의 :id와 @Param('id')의 이름이 일치해야 합니다.

💡 잠깐! Query String은 어떻게 받나요?
게시판 목록을 조회할 때, 페이지 번호나 검색어 같은 Query String(?page=1&keyword=nestjs)이 필요할 때가 있습니다.
그럴 땐 @Query() 데코레이터를 사용하면 됩니다.
@Get()
findAll(@Query('status') status: string) {
  console.log(status); // 'PUBLIC' 출력
}

테스트

두가지 End-point 를 테스트 합니다.

모든 boards 조회 http://localhost:3000/boards

특정 boards 조회 (http://localhost:3000/boards/10f5f078-3211-44e0-a4a6-5059f4036cf8)

현재, db 를 메모리로 관리하고 있기 때문에, 바로 조회하면 데이터가 [] 빈값으로 나올 수 있습니다.
그때는, post man 을 통해 이전에 만든 생성 api 를 통해 만드시면 됩니다.

🚀 CRUD - Update/Delete 작업

이 두개 작업은 DB 를 인메모리로 진행하기 때문에 큰 특이점이 없습니다.
코드만 전반적으로 제공하여 대체합니다.

DTO 작성

update-board.dto.ts

import { BoardStatus } from "../entities/board-status.enum";

export class UpdateBoardRequest {
  title?: string;
  description?: string;
  status?: BoardStatus;
}

export class UpdateBoardResponse {
  id: string;
  title: string;
  description: string;
  status: BoardStatus;
}

Service 코드 작성

boards.service.ts

  updateBoard(id: string, request: UpdateBoardRequest): UpdateBoardResponse {
    const board = this.findBoard(id);
    
    if (request.title) {
        board.title = request.title;
    }
    if (request.description) {
        board.description = request.description;
    }
    if (request.status) {
        board.status = request.status;
    }

    return {
      id: board.id,
      title: board.title,
      description: board.description,
      status: board.status,
    };
  }

  deleteBoard(id: string): void {
    const found = this.findBoard(id);
    this.boards = this.boards.filter((board) => board.id !== found.id);
  }

Controller 코드 작성

boards.controller.ts

  @Patch(':id')
  @HttpCode(200)
  updateBoard(
    @Param('id') id: string,
    @Body() updateBoardDto: UpdateBoardRequest
  ): UpdateBoardResponse {
    return this.boardsService.updateBoard(id, updateBoardDto);
  }

  @Delete(':id')
  @HttpCode(204) // 204 No Content
  deleteBoard(@Param('id') id: string): void {
    this.boardsService.deleteBoard(id);
  }

🎁 부록) API 문서 만들기 - With Swagger

저희가 작성하는 API 는 Open API 가 되었든, 아니면 내부 BE 서버가 되었든, API 스펙을 공개할 필요가 있습니다.

결국 사용자가 어떤식으로 API 를 활용 해야 하는지 알아야 하기 때문입니다.

Spring 사용자라면 익숙한 Swagger 를 동일하게 NestJS 에서도 사용하실 수 있습니다.

1. Swagger 설치

먼저 필요한 패키지를 설치합니다.

$ npm install --save @nestjs/swagger swagger-ui-express

2. 설정 활성화 (main.ts)

설치만 한다고 바로 뜨진 않습니다. main.ts에서 스웨거를 초기화해줘야 합니다.

Spring의 SwaggerConfig 클래스 설정과 비슷합니다.

main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('NestJS CRUD App')
    .setDescription('The boards API description')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

이제 http://localhost:3000/api로 접속하면 Swagger UI를 볼 수 있습니다.

하지만 아직 DTO나 응답 값들이 비어있을 겁니다. 데코레이터로 채워봅시다.

3. DTO Property 등록 (`@ApiProperty`)

Spring의 @Schema나 @ApiModelProperty와 같습니다.

TypeScript의 인터페이스나 클래스는 컴파일되면 사라지기 때문에, Swagger가 런타임에 타입을 알 수 있도록 데코레이터를 붙여줘야 합니다.

create-board.dto.ts

import { ApiProperty } from "@nestjs/swagger";
import { BoardStatus } from "../entities/board-status.enum";

export class CreateBoardRequest {
  @ApiProperty({ example: 'My Board', description: 'The title of the board' })
  title: string;

  @ApiProperty({ example: 'This is a description', description: 'The description of the board' })
  description: string;
}

export class CreateBoardResponse {
  @ApiProperty({ example: 'uuid', description: 'The unique identifier of the board' })
  id: string;

  @ApiProperty({ example: 'My Board', description: 'The title of the board' })
  title: string;

  @ApiProperty({ example: 'This is a description', description: 'The description of the board' })
  description: string;

  @ApiProperty({ enum: BoardStatus, example: BoardStatus.PUBLIC, description: 'The status of the board' })
  status: BoardStatus;
}

@ApiProperty: 이 필드를 Swagger 문서에 노출합니다.
example: 예시 값을 지정합니다. (Try it out 할 때 자동 입력됨)
description: 필드에 대한 설명을 적습니다.

4. Controller Operation 등록 (`@ApiOperation`, `@ApiResponse`)

컨트롤러 메서드에 상세한 설명을 덧붙입니다.

boards.controller.ts

import { Body, Controller, Delete, Get, HttpCode, Param, Patch, Post } from '@nestjs/common';
import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
import { BoardsService } from './boards.service';
import { CreateBoardRequest, CreateBoardResponse } from './dto/create-board.dto';
import { FindBoardResponse } from './dto/find-board.dto';
import { UpdateBoardRequest, UpdateBoardResponse } from './dto/update-board.dto';

@ApiTags('boards')
@Controller('boards')
export class BoardsController {
  constructor(private readonly boardsService: BoardsService) {}

  @Post()
  @ApiOperation({ summary: 'Create a board' })
  @ApiResponse({ status: 200, description: 'The board has been successfully created.', type: CreateBoardResponse })
  @HttpCode(200) // 201이 기본이지만 200으로 설정
  createBoard(@Body() createBoardDto: CreateBoardRequest): CreateBoardResponse {
    const response = this.boardsService.createBoard(createBoardDto);
    return response;
  }

  @Get()
  @ApiOperation({ summary: 'Find all boards' })
  @ApiResponse({ status: 200, description: 'Return all boards.', type: [FindBoardResponse] })
  @HttpCode(200)
  findAllBoards(): FindBoardResponse[] {
    const response = this.boardsService.findAllBoards();
    return response;
  }

  @Get(':id')
  @ApiOperation({ summary: 'Find a board by id' })
  @ApiResponse({ status: 200, description: 'Return the board.', type: FindBoardResponse })
  @HttpCode(200)
  findBoard(@Param('id') id: string): FindBoardResponse {
    const response = this.boardsService.findBoard(id);
    return response;
  }

  @Patch(':id')
  @ApiOperation({ summary: 'Update a board' })
  @ApiResponse({ status: 200, description: 'The board has been successfully updated.', type: UpdateBoardResponse })
  @HttpCode(200)
  updateBoard(
    @Param('id') id: string,
    @Body() updateBoardDto: UpdateBoardRequest
  ): UpdateBoardResponse {
    return this.boardsService.updateBoard(id, updateBoardDto);
  }

  @Delete(':id')
  @ApiOperation({ summary: 'Delete a board' })
  @ApiResponse({ status: 204, description: 'The board has been successfully deleted.' })
  @HttpCode(204) // 204 No Content
  deleteBoard(@Param('id') id: string): void {
    this.boardsService.deleteBoard(id);
  }
}

@ApiTags('boards'): Controller 단위로 API를 그룹화합니다.
@ApiOperation({ summary: ... }): 해당 API가 무엇을 하는지 요약합니다.
@ApiResponse({ status, type ... }): 응답 코드와 반환되는 객체 타입을 명시합니다. 이를 통해 프론트엔드 개발자는 직접 호출해보지 않아도 응답 구조를 알 수 있습니다.

🚀 다음으로

현재는 DB 없이 In-Memory로 데이터를 관리하고 있어, 서버가 재시작되면 데이터가 사라집니다.

다음 시간에는 진짜 백엔드답게 DB를 연결해보겠습니다.

다음 목표

DB 구축 (Postgres / Docker 예정)
TypeORM 연동 (Prisma가 트렌드지만, Spring 개발자에겐 TypeORM이 더 친숙하므로 먼저 다룹니다.)

[NestJS] 게시판(Board) 만들어보기 - In Memory CRUD

스택 시리즈NestJS 스택