[NestJS] Controllers

NestJS Controller, NestJS Controllers, @Controller decorator, @Get @Post @Put @Delete, @Param @Query @Body, NestJS 컨트롤러

정의

NestJS Controller 는 @Controller() 데코레이터가 붙은 클래스로, HTTP 요청을 라우팅하고 응답을 반환합니다. Method 별로 @Get, @Post, @Put, @Patch, @Delete 데코레이터를 붙여 URL + method 조합을 처리합니다.

기본

import { Controller, Get, Post, Body, Param, Query, HttpCode } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';

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

  @Get()
  findAll(@Query('page') page: number = 1) {
    return this.usersService.findAll(page);
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(id);
  }

  @Post()
  @HttpCode(201)
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }

  @Patch(':id')
  update(@Param('id') id: string, @Body() dto: UpdateUserDto) {
    return this.usersService.update(id, dto);
  }

  @Delete(':id')
  @HttpCode(204)
  remove(@Param('id') id: string) {
    return this.usersService.remove(id);
  }
}

URL prefix /users, method 별 하위 경로.

Path Parameter

@Get(':id')
find(@Param('id') id: string) { ... }

@Get(':id/posts/:postId')
findPost(
  @Param('id') id: string,
  @Param('postId') postId: string,
) { ... }

// 전체 params 객체
@Get(':id/posts/:postId')
findPost(@Param() params: {id: string; postId: string}) { ... }

Query Parameter

@Get()
list(
  @Query('page') page: number = 1,
  @Query('limit') limit: number = 10,
) { ... }

// 전체 query 객체
@Get()
list(@Query() query: {page?: string; limit?: string}) { ... }

// DTO 로 (검증 포함)
@Get()
list(@Query() query: ListUsersQuery) { ... }

DTO + ValidationPipe 로 자동 변환/검증:

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

export class ListUsersQuery {
  @IsInt()
  @Min(1)
  @Type(() => Number)
  @IsOptional()
  page: number = 1;

  @IsInt()
  @Min(1)
  @Max(100)
  @Type(() => Number)
  @IsOptional()
  limit: number = 10;
}

Request Body

@Post()
create(@Body() dto: CreateUserDto) { ... }

// 특정 필드만
@Post()
create(@Body('email') email: string, @Body('name') name: string) { ... }

Headers, Cookies, IP

@Get()
findAll(
  @Headers('authorization') auth: string,
  @Headers() allHeaders: Record<string, string>,
  @Ip() ip: string,
) { ... }

// Cookies (cookie-parser 필요)
@Get()
withCookie(@Req() req: Request) {
  return req.cookies;
}

Custom Decorator

자주 쓰는 파라미터를 decorator 로:

// common/decorators/user.decorator.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const User = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user;
    return data ? user?.[data] : user;
  },
);

// 사용
@Get('me')
me(@User() user: UserEntity) { ... }

@Get('me/email')
myEmail(@User('email') email: string) { ... }

Response

기본 (자동 직렬화)

Method return 값이 자동 JSON 직렬화 + 200 응답.

@Get()
findAll() {
  return {users: [...]};   // -> 200 {"users": [...]}
}

// async 도 OK
@Get(':id')
async find(@Param('id') id: string): Promise<User> {
  return await this.usersService.findOne(id);
}

// Observable 도 OK (RxJS)
@Get()
stream(): Observable<Data> {
  return this.dataService.stream();
}

Status Code

@Post()
@HttpCode(201)              // 명시적 code
create(@Body() dto: CreateUserDto) { ... }

@Delete(':id')
@HttpCode(HttpStatus.NO_CONTENT)   // 204
remove(@Param('id') id: string) { ... }

Headers

@Get()
@Header('Cache-Control', 'none')
@Header('X-Custom', 'value')
findAll() { ... }

Redirect

@Get('legacy')
@Redirect('/new-path', 301)
legacy() { ... }

@Get('dynamic')
dynamic() {
  return {url: '/new-path', statusCode: 301};   // Runtime redirect
}

Raw Response

세밀한 제어 필요 시 @Res():

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

@Get('download')
download(@Res() res: Response) {
  res.setHeader('Content-Type', 'application/pdf');
  res.sendFile('/path/to/file.pdf');
}

주의: @Res() 를 쓰면 자동 직렬화 못 함. Interceptor 도 우회. Passthrough option 으로 절충:

@Get()
findAll(@Res({passthrough: true}) res: Response) {
  res.setHeader('X-Custom', 'value');
  return {users: [...]};   // 여전히 자동 직렬화
}

Wildcard / Regex

@Get('a*b')          // /aXXb, /axb, ... 모두 매칭
handle() { ... }

@Get(':version(v[0-9]+)/*')   // /v1/anything
versioned(@Param('version') v: string) { ... }

Sub-domain routing

@Controller({ host: 'admin.example.com' })
export class AdminController { ... }

@Controller({ host: ':account.example.com' })
export class TenantController {
  @Get()
  index(@HostParam('account') account: string) { ... }
}

Async, Promise, Observable

세 스타일 모두 지원:

@Get()
sync() {
  return {ok: true};
}

@Get()
async asyncReturn() {
  return await this.service.get();
}

@Get()
observable(): Observable<Data> {
  return this.service.stream();
}

Streaming Response

import { StreamableFile } from '@nestjs/common';
import { createReadStream } from 'fs';

@Get('file')
file(): StreamableFile {
  const file = createReadStream('/path/to/file.txt');
  return new StreamableFile(file);
}

또는 @Sse() (Server-Sent Events):

import { Sse } from '@nestjs/common';
import { Observable, interval, map } from 'rxjs';

@Sse('events')
events(): Observable<MessageEvent> {
  return interval(1000).pipe(
    map(_ => ({data: {time: new Date()}}))
  );
}

Versioning

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

@Controller({path: 'users', version: '1'})
export class UsersV1Controller { ... }

@Controller({path: 'users', version: '2'})
export class UsersV2Controller { ... }

URL: /v1/users, /v2/users. Header, Media Type 방식도 있음.

Route Prefix

// main.ts
app.setGlobalPrefix('api');

모든 route 앞에 /api.

@Controller('users')
class UsersController {
  @Get()   // -> GET /api/users
}

특정 controller 는 예외:

app.setGlobalPrefix('api', {
  exclude: [{path: 'health', method: RequestMethod.GET}]
});

Guard / Interceptor / Pipe / Filter 부착

@Controller('users')
@UseGuards(AuthGuard)                       // controller 전체
export class UsersController {

  @Get()
  @UseInterceptors(CacheInterceptor)        // method 만
  @UsePipes(new ValidationPipe())
  @UseFilters(new HttpExceptionFilter())
  findAll() { ... }
}

Global 도 가능 (main.ts 참조).

함정

[!WARNING> @Res() 사용 시 자동 응답/interceptor 우회. passthrough: true 사용.

관련 위키

• NestJS - 상위 개요
• Modules - Controller 등록
• Providers & DI - Service 주입
• Pipes - Body/Query 검증
• Guards - @UseGuards()
• Interceptors - @UseInterceptors()
• Exception Filters - @UseFilters()
• Middleware
• TypeScript Decorators
• FastAPI Routing - 대비
• Koa.js - 대비