B컷전문 | 개발과 인생의 이야기

“그냥 GET, POST만 쓰면 된다고? 실무는 다릅니다”

 

NestJS에서 컨트롤러와 라우팅의 구조를 실전 예제로 설명합니다. HTTP 요청 처리, REST API 설계, 데코레이터 기반 라우팅, 그리고 컨트롤러 분리 전략까지 실무 중심으로 정리합니다.

 

---

 

🚪 컨트롤러는 API 입구다

 

NestJS에서 @Controller()는 클라이언트의 HTTP 요청을 받아들이는 입구 역할을 합니다.

Express의 라우터 개념과 유사하지만, 데코레이터 기반으로 더 구조화된 형태를 가집니다.

 

“라우팅의 혼란은 결국 컨트롤러 설계의 실패에서 시작됩니다.”

 

---

 

🧱 기본 구조 – 컨트롤러는 이렇게 생겼다

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { UsersService } from './users.service';

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

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

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

  @Post()
  create(@Body() createUserDto) {
    return this.usersService.create(createUserDto);
  }
}

 

 

---

 

🧩 주요 데코레이터 정리

데코레이터설명

@Controller('path')	엔드포인트 prefix (e.g., /users)
@Get(), @Post(), @Put(), @Delete()	HTTP 메서드 라우팅 지정
@Param()	URL 파라미터 (e.g., /users/:id)
@Body()	요청 본문(JSON 등) 추출
@Query()	쿼리 스트링 값 추출
@Req(), @Res()	Express 객체 직접 접근 (비권장)

 

 

---

 

🧭 RESTful 라우팅 설계 가이드

기능라우팅 예시메서드

전체 목록 조회	GET /users	@Get()
단일 조회	GET /users/:id	@Get(':id')
생성	POST /users	@Post()
수정	PUT /users/:id	@Put(':id')
삭제	DELETE /users/:id	@Delete(':id')

REST 설계 원칙을 지키면 프론트엔드와의 협업이 훨씬 원활해집니다.

 

---

 

💼 실무 기준 컨트롤러 분리 전략

 

NestJS에서 컨트롤러가 커지면 아래처럼 분리 설계를 고려합니다:

방식예시설명

기능 단위 컨트롤러	UsersController, AuthController	기본 방식
역할 기반 분리	AdminUsersController, ClientUsersController	권한/도메인에 따라 분리
버전 관리	UsersV1Controller, UsersV2Controller	API versioning 적용 시 유용

 

 

---

 

🚫 안티패턴: 라우팅 혼잡

 

• ❌ @Controller('api') 안에 모든 기능 라우팅 넣기
• ❌ 라우팅 경로를 문자열로 하드코딩해 중복
• ❌ 컨트롤러에서 서비스 로직 과도하게 포함 (→ 서비스 계층 분리 필수)

 

---

 

💡 마무리 인사이트

 

NestJS의 컨트롤러는 단순한 요청 핸들러가 아니라,

서비스 전체의 API 규약과 진입점을 설계하는 핵심 레이어입니다.

 

• 데코레이터를 적절히 활용하고
• RESTful 설계 원칙을 지키며
• 기능별로 모듈화한다면
• 컨트롤러 하나로 팀 전체의 생산성이 올라갑니다.

 

“컨트롤러는 프레임워크가 제공하는 게 아니라, 설계자가 만드는 품질이다.”

 

---

 

📎 다음 회차 예고

 

👉 5화. 서비스와 의존성 주입(DI) – 로직의 핵심을 어떻게 설계할 것인가

 

@Injectable, DI 컨테이너, 테스트 가능한 서비스 구조까지 단계별로 분석합니다.