RESTful API 설계 원칙과 구현

nest g mo users
nest g co users
nest g s users
npm install class-validator class-transformer @nestjs/mapped-types

import { Transform } from 'class-transformer';
import { IsEmail, IsString, Length, MaxLength } from 'class-validator';

export class CreateUserDto {
  @Transform(({ value }) =>
    typeof value === 'string' ? value.trim() : value,
  )
  @IsString()
  @Length(1, 80)
  name!: string;

  @Transform(({ value }) =>
    typeof value === 'string' ? value.trim() : value,
  )
  @IsEmail()
  @MaxLength(254)
  email!: string;
}

import { PartialType } from '@nestjs/mapped-types';
import { CreateUserDto } from './create-user.dto';

export class UpdateUserDto extends PartialType(CreateUserDto, {
  skipNullProperties: false,
}) {}

import { Type } from 'class-transformer';
import { IsInt, Max, Min } from 'class-validator';

export class ListUsersQueryDto {
  @Type(() => Number)
  @IsInt()
  @Min(1)
  page = 1;

  @Type(() => Number)
  @IsInt()
  @Min(1)
  @Max(100)
  limit = 20;
}

import type { UserRecord } from '../users.service';

export class UserResponseDto {
  constructor(
    public readonly id: number,
    public readonly name: string,
    public readonly email: string,
  ) {}

  static from(user: UserRecord): UserResponseDto {
    return new UserResponseDto(user.id, user.name, user.email);
  }
}

export interface UsersPageResponse {
  items: UserResponseDto[];
  page: number;
  limit: number;
  total: number;
}

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

export interface UserRecord {
  readonly id: number;
  readonly name: string;
  readonly email: string;
}

export interface UsersPage {
  items: UserRecord[];
  total: number;
}

export class EmailAlreadyUsedError extends Error {}

type CreateUserInput = Pick<UserRecord, 'name' | 'email'>;
type UpdateUserInput = Partial<CreateUserInput>;

@Injectable()
export class UsersService {
  private users: UserRecord[] = [
    { id: 1, name: 'Alice', email: '[email protected]' },
    { id: 2, name: 'Bob', email: '[email protected]' },
  ];
  private nextId = 3;

  findAll(page: number, limit: number): UsersPage {
    const start = (page - 1) * limit;

    return {
      items: this.users.slice(start, start + limit),
      total: this.users.length,
    };
  }

  findOne(id: number): UserRecord | undefined {
    return this.users.find((user) => user.id === id);
  }

  create(input: CreateUserInput): UserRecord {
    this.assertEmailAvailable(input.email);

    const user: UserRecord = { id: this.nextId++, ...input };
    this.users.push(user);
    return user;
  }

  update(id: number, input: UpdateUserInput): UserRecord | undefined {
    const index = this.users.findIndex((user) => user.id === id);
    if (index === -1) return undefined;

    if (input.email !== undefined) {
      this.assertEmailAvailable(input.email, id);
    }

    const user: UserRecord = { ...this.users[index], ...input, id };
    this.users[index] = user;
    return user;
  }

  remove(id: number): boolean {
    const index = this.users.findIndex((user) => user.id === id);
    if (index === -1) return false;

    this.users.splice(index, 1);
    return true;
  }

  private assertEmailAvailable(email: string, exceptId?: number): void {
    const normalized = email.toLowerCase();
    const exists = this.users.some(
      (user) =>
        user.id !== exceptId && user.email.toLowerCase() === normalized,
    );

    if (exists) throw new EmailAlreadyUsedError();
  }
}

import {
  Body,
  ConflictException,
  Controller,
  Delete,
  Get,
  HttpCode,
  HttpStatus,
  NotFoundException,
  Param,
  ParseIntPipe,
  Patch,
  Post,
  Query,
  Res,
} from '@nestjs/common';
import type { Response } from 'express';
import { CreateUserDto } from './dto/create-user.dto';
import { ListUsersQueryDto } from './dto/list-users-query.dto';
import {
  UserResponseDto,
  type UsersPageResponse,
} from './dto/user-response.dto';
import { UpdateUserDto } from './dto/update-user.dto';
import {
  EmailAlreadyUsedError,
  UsersService,
} from './users.service';

@Controller({ path: 'users', version: '1' })
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  findAll(@Query() query: ListUsersQueryDto): UsersPageResponse {
    const result = this.usersService.findAll(query.page, query.limit);

    return {
      items: result.items.map(UserResponseDto.from),
      page: query.page,
      limit: query.limit,
      total: result.total,
    };
  }

  @Get(':id')
  findOne(
    @Param('id', ParseIntPipe) id: number,
  ): UserResponseDto {
    const user = this.usersService.findOne(id);
    if (!user) throw new NotFoundException('User not found');

    return UserResponseDto.from(user);
  }

  @Post()
  create(
    @Body() dto: CreateUserDto,
    @Res({ passthrough: true }) response: Response,
  ): UserResponseDto {
    try {
      const user = this.usersService.create(dto);
      response.setHeader('Location', '/v1/users/' + user.id);
      return UserResponseDto.from(user);
    } catch (error) {
      this.rethrowConflict(error);
    }
  }

  @Patch(':id')
  update(
    @Param('id', ParseIntPipe) id: number,
    @Body() dto: UpdateUserDto,
  ): UserResponseDto {
    try {
      const user = this.usersService.update(id, dto);
      if (!user) throw new NotFoundException('User not found');

      return UserResponseDto.from(user);
    } catch (error) {
      this.rethrowConflict(error);
    }
  }

  @Delete(':id')
  @HttpCode(HttpStatus.NO_CONTENT)
  remove(@Param('id', ParseIntPipe) id: number): void {
    if (!this.usersService.remove(id)) {
      throw new NotFoundException('User not found');
    }
  }

  private rethrowConflict(error: unknown): never {
    if (error instanceof EmailAlreadyUsedError) {
      throw new ConflictException('Email already in use');
    }
    throw error;
  }
}

import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

import { Module } from '@nestjs/common';
import { UsersModule } from './users/users.module';

@Module({
  imports: [UsersModule],
})
export class AppModule {}

import {
  ValidationPipe,
  VersioningType,
} from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

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

  app.enableVersioning({
    type: VersioningType.URI,
    defaultVersion: '1',
  });

  app.useGlobalPipes(
    new ValidationPipe({
      transform: true,
      whitelist: true,
      forbidNonWhitelisted: true,
    }),
  );

  await app.listen(3000);
}

void bootstrap();

curl -i -X POST http://localhost:3000/v1/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"David","email":"[email protected]"}'