NestJS에서 controller란 무엇인가요?

Question

Accepted Answer

**Controller**는 들어오는 **HTTP 요청**을 처리하고 응답을 반환합니다. 애플리케이션의 라우트를 정의하며 진입점 역할을 합니다 — 요청을 받고, 데이터를 추출하고, service에 위임하고, 결과를 반환합니다. 라우팅 관심사를 비즈니스 로직과 분리해 줍니다.

## controller 정의하기

```ts
import { Controller, Get, Post, Body, Param } from "@nestjs/common";

@Controller("users")          // 라우트 PREFIX → 모든 라우트가 /users로 시작
export class UsersController {
  constructor(private usersService: UsersService) {}   // DI로 service 주입

@Get()                       // GET /users
  findAll() {
    return this.usersService.findAll();
  }

@Get(":id")                  // GET /users/:id
  findOne(@Param("id") id: string) {        // 라우트 파라미터 추출
    return this.usersService.findOne(id);
  }

@Post()                      // POST /users
  create(@Body() dto: CreateUserDto) {       // 요청 본문 추출
    return this.usersService.create(dto);
  }
}
```

## 동작 방식: decorator가 메서드를 라우트에 매핑

```text
@Controller("users") → 라우트 prefix /users
@Get() / @Post() / @Put() / @Patch() / @Delete() → HTTP 메서드 + 하위 경로
조합: @Controller("users") 안의 @Get(":id") → GET /users/:id
```

Decorator는 클래스 메서드를 HTTP 라우트에 선언적으로 바인딩합니다 — 깔끔하고 읽기 쉬우며 수동 라우트 등록이 필요 없습니다.

## 파라미터 decorator가 요청 데이터를 추출

```ts
@Get(":id")
example(
  @Param("id") id: string,        // 라우트 파라미터 (/users/:id)
  @Query("sort") sort: string,    // 쿼리 문자열 (?sort=name)
  @Body() body: CreateUserDto,    // 요청 본문
  @Headers("authorization") auth: string,  // 헤더
  @Req() req: Request,            // 원시 request 객체 (거의 필요 없음)
) {}
```

Nest의 파라미터 decorator(`@Param`, `@Query`, `@Body`, `@Headers`)는 필요한 데이터만 깔끔하게 추출합니다 — `req`를 수동으로 파싱할 필요가 없습니다.

## controller는 얇아야(THIN) 합니다

```ts
// ✅ controller가 service에 위임 — 얇게 유지
@Post()
create(@Body() dto: CreateUserDto) {
  return this.usersService.create(dto);   // 비즈니스 로직은 SERVICE에 존재
}
// ❌ controller에 데이터베이스 쿼리/비즈니스 로직을 직접 넣지 마세요
```

모범 사례: controller를 **얇게** 유지하세요 — controller는 HTTP 관심사(라우팅, 데이터 추출, 응답 반환)를 처리하고 모든 비즈니스 로직을 **service**에 위임합니다. 이 분리는 코드를 테스트 가능하고 체계적으로 유지합니다.

## 왜 중요한가

Controller는 NestJS의 기본 구성 요소입니다 — 모든 HTTP 요청의 진입점이자 API의 라우트가 정의되는 곳입니다.

Decorator(`@Controller`, `@Get`/`@Post`, `@Param`/`@Body`/`@Query`)가 어떻게 메서드를 라우트에 매핑하고 요청 데이터를 선언적으로 추출하는지 이해하는 것은 필수적인 일상 NestJS 지식입니다 — 모든 엔드포인트를 구축하는 방법이기 때문입니다.

마찬가지로 중요한 것은 controller를 **얇게** 유지하는 원칙(HTTP 관심사만 처리하고 비즈니스 로직은 주입된 service에 위임)으로, 이는 NestJS의 관심사 분리 철학을 구현하며 코드를 유지보수 가능하고 테스트 가능하게 유지합니다.

Controller는 service, module과 함께 모든 NestJS 애플리케이션의 핵심 구조를 형성하므로 처음부터 반드시 이해해야 합니다.