💡 02. 모듈과 컨트롤러 — 애플리케이션의 뼈대와 출입문

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 모듈 (Module) — 건물의 층과 부서 🟡
• 🧩 컨트롤러 (Controller) — 안내데스크 직원 🟢
• 🧪 따라해보기: 실전 주식 컨트롤러 만들기
• 💼 베스트 프랙티스와 실무 팁
• 💥 에러 해결 카탈로그
• 🗂️ 치트시트
• 📝 마무리 퀴즈

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 20분 (전체) / 핵심 파트만: 10분

🧳 전제 지식 체크리스트
아래 항목을 모두 알면 바로 [모듈 섹션]부터 읽어도 돼:

• 데코레이터(@) 문법을 보면 함수나 클래스에 속성을 부여하는 것임을 안다.
• HTTP 메서드(GET, POST, PUT, DELETE)의 차이를 안다.
• 01장 'NestJS 소개'의 웨이터/셰프 비유를 기억한다.

🗺️ 이 문서의 흐름
모듈로 영역 나누기 → 컨트롤러로 요청 받기 → 리퀘스트 데이터(@Body, @Query) 뽑아내기 → 라우팅 규칙 → 에러 해결 및 퀴즈

🎯 이 문서를 다 읽으면 할 수 있는 것

• 용도별로 모듈을 쪼개서(UsersModule, StocksModule) 정리할 수 있다.
• URL 주소나 본문에 담긴 데이터를 컨트롤러에서 정확히 빼낼 수 있다.
• 라우팅 순서 오류로 인한 404 에러 원인을 스스로 찾을 수 있다.

🤔 왜 알아야 하는가

건물을 지을 때 설계도 없이 무작정 벽돌만 쌓으면, 나중에 화장실 배관을 고치려고 건물 전체를 부숴야 해.
NestJS에서 모듈 은 건물을 '층(Floor)'과 '구역(Zone)'으로 나누는 설계도 역할을 하고, 컨트롤러 는 각 구역에 들어가는 출입문 역할을 해.
이 두 가지를 제대로 알면, 코드가 수천 줄로 늘어나도 어디를 고쳐야 할지 단 3초 만에 찾을 수 있게 돼.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면?

커다란 종합병원을 상상해봐.
모듈(Module) 은 '소아과', '내과', '정형외과' 같은 진료과(부서)야. 서로 하는 일이 완벽하게 나뉘어 있지.
컨트롤러(Controller) 는 각 진료과 앞에 있는 '안내데스크'야. "배가 아파서 왔어요(요청)" 하면 "내과 3번 방으로 가세요" 하고 길을 안내해 주지. (안내데스크 직원이 직접 배를 수술하지 않아!)

🧩 모듈 (Module) — 건물의 층과 부서 🟡

🎯 이 섹션을 읽고 나면:

• 모듈의 4가지 핵심 배열(imports, controllers, providers, exports)을 구별할 수 있다.
• 왜 하나의 AppModule에 다 때려박으면 안 되는지 설명할 수 있다.

🤔 잠깐, 먼저 생각해봐
유저 관리 기능, 주식 검색 기능, 결제 기능이 모두 한 파일에 섞여 있다고 상상해봐. 결제 기능을 수정하다가 유저 기능이 고장나면 어떻게 될까?

이게 뭔가?

연관된 코드(웨이터와 셰프)를 하나의 울타리로 묶어주는 단위야.

import { Module } from '@nestjs/common';
import { StocksController } from './stocks.controller';
import { StocksService } from './stocks.service';
import { DatabaseModule } from '../database/database.module';
 
@Module({
  imports: [DatabaseModule],       // 1. 남의 부서(모듈)에서 빌려올 것
  controllers: [StocksController], // 2. 우리 부서의 웨이터(접수처)
  providers: [StocksService],      // 3. 우리 부서의 셰프(실제 로직)
  exports: [StocksService],        // 4. 남의 부서에 빌려줄 것
})
export class StocksModule {}

왜 이게 따로 존재하는가?

❌ 이게 없었다면?
모든 코드가 AppModule 하나에 다 몰려있을 거야. 100명의 웨이터와 100명의 셰프가 벽도 없는 거대한 강당 하나에서 일한다고 생각해봐. 누가 누구랑 일하는지 아무도 모를 거야 (강한 결합도).

✅ 이게 생긴 뒤에는?
"주식 부서(StocksModule)", "유저 부서(UsersModule)"가 독립된 사무실을 가져. 주식 부서를 다른 프로젝트에 그대로 복사해서 써도 완벽하게 동작해 (재사용성/캡슐화).

모듈 설정 4대장 뜯어보기

🔗 연결 고리
공유 모듈이나 글로벌 모듈(@Global()) 설정은 나중에 아키텍처를 깊게 짤 때 다시 나와. 일단은 "관련된 것끼리 묶는다"만 기억해!

🧩 컨트롤러 (Controller) — 안내데스크 직원 🟢

🎯 이 섹션을 읽고 나면:

• HTTP 요청에서 파라미터(@Query, @Param, @Body)를 뽑아내는 방법을 알 수 있다.
• @Controller 데코레이터를 이용해 경로를 깔끔하게 설계할 수 있다.

1. 라우팅과 메서드 매핑

컨트롤러는 URL 주소와 HTTP 메서드를 확인하고, 적절한 처리 함수로 연결해줘.

import { Controller, Get, Post, Param, Body, HttpCode, HttpStatus } from '@nestjs/common';
 
@Controller('stocks')  // 👈 이 컨트롤러는 '/stocks'로 시작하는 요청만 담당해!
export class StocksController {
  
  // GET /stocks
  @Get()
  findAll() {
    return '모든 주식 목록을 반환합니다.';
  }
 
  // GET /stocks/AAPL
  @Get(':symbol') 
  findOne(@Param('symbol') symbol: string) {
    // URL에 있는 'AAPL' 글자를 symbol 변수로 쏙 빼옴!
    return `${symbol} 주식의 정보입니다.`;
  }
 
  // POST /stocks
  @Post()
  @HttpCode(HttpStatus.CREATED) // 성공하면 201 코드를 쏴줌
  create(@Body() dto: CreateStockDto) {
    // 요청 본문(JSON) 전체를 dto라는 객체로 받아옴!
    return '주식이 생성되었습니다.';
  }
}

2. 요청 데이터 추출 데코레이터 총정리

고객(클라이언트)이 안내데스크에 넘겨주는 정보의 형태는 여러 가지야. 주소창에 적어서 줄 수도 있고, 봉투에 담아서 줄 수도 있지.

3. 응답(Response) 처리 방식

Express에서는 res.status(200).json(...) 처럼 일일이 응답을 보냈지만, NestJS는 훨씬 똑똑해.
컨트롤러 함수에서 그냥 return 객체만 던지면:

1. 알아서 JSON 문자열로 바꿔줌!
2. 알아서 상태 코드 200(성공)을 달아줌! (POST는 201)

💡 한 줄로 기억하기

컨트롤러는 길라잡이야. 어떤 URL로 들어온 어떤 데이터인지만 뽑아서 서비스(셰프)에게 던져주고 뒷일은 신경 쓰지 마.

🧪 따라해보기: 실전 주식 컨트롤러 만들기

단순한 예시를 넘어, 실제 실무에서 쓸 법한 주식 검색용 복합 파라미터 컨트롤러를 만들어보자.

👇 아래 코드를 눈으로 쭉 따라가며 읽어봐.

@Get('search')
// 주소: GET /stocks/search?exchange=NASDAQ&sector=Tech&page=1
search(
  @Query('exchange') exchange?: string,
  @Query('sector') sector?: string,
  @Query('page', ParseIntPipe) page: number = 1,
  @Query('limit', ParseIntPipe) limit: number = 20,
) {
  // 1. 필요한 요소를 다 뽑았으니 셰프(서비스)에게 요리 의뢰!
  return this.stocksService.search(exchange, sector, page, limit);
}

🔍 코드 한 줄씩 뜯어보기:

✅ 실습 후 체크리스트

• @Param과 @Query가 각각 URL의 어느 부분에서 값을 뽑아오는지 구별할 수 있다.
• ParseIntPipe가 왜 필요한지 설명할 수 있다.

아직 아리송하다면 [요청 데이터 추출 총정리 표]를 다시 한번 스윽 훑고 오자!

💼 베스트 프랙티스와 실무 팁 🟡

1. 라우트 순서 주의 (치명적 실수 방지)

REST API를 짤 때 제일 많이 당하는 함정 중 하나야. 구체적인 경로를 동적 매개변수(:id)보다 무조건 먼저 써야 해.

// ✅ 좋은 예: 구체적인 'trending'이 먼저 나옴
@Get('trending')
getTrending() { return '인기 주식'; }
 
@Get(':symbol')
getBySymbol(@Param('symbol') symbol: string) { return symbol; }
 
 
// ❌ 나쁜 역순 예:
@Get(':symbol') // 모든 것을 다 빨아들임
getBySymbol() { ... }
 
@Get('trending') // 이 코드는 평생 실행되지 못함 (위에 막혀서)
getTrending() { ... }

2. 컨트롤러는 "종잇장처럼 얇게" 유지해라

웨이터가 주방에 들어가서 고기 구우면 안 돼. 컨트롤러에 const user = await db.query... 같은 데이터베이스 로직이 1줄이라도 보인다면 설계가 망가진 거야. 오직 유효성 체크, 의뢰, 응답만 담당해!

3. API 글로벌 접두사 (Global Prefix) 추가

실무에서는 API 주소 앞에 /api/v1 같은 걸 붙여. 클라이언트와 리액트 앱 경로가 겹치지 않게 하기 위해서야.
main.ts 수정 한 줄이면 앱 전체에 적용돼:

// main.ts
app.setGlobalPrefix('api/v1');
// 이제 localhost:3000/api/v1/stocks 로 요청해야 해!

💥 에러 해결 카탈로그

에러 메시지가 뜨면 Ctrl+F로 검색해봐.

❌ 404 Not Found (라우팅 문제)

언제 나오는가?

{ "statusCode": 404, "message": "Cannot GET /stocks/trending", "error": "Not Found" }

원인:

1. 모듈을 AppModule의 imports에 등록하지 않아서 NestJS가 컨트롤러 자체를 모름.
2. 위에서 설명한 라우트 순서(순위) 문제 때문에, /:symbol이 /trending을 삼켜버려서 에러 처리기로 빠짐.

해결책:

• app.module.ts의 imports: [StocksModule]이 들어있는지 확인.
• 컨트롤러 내 함수 배치 순서에서 고정된 영단어 경로가 콜론(:)이 붙은 변수 경로보다 위에 있는지 확인.

❌ Validation failed (numeric string is expected)

언제 나오는가?

{ "statusCode": 400, "message": "Validation failed (numeric string is expected)", "error": "Bad Request" }

원인: @Query('id', ParseIntPipe)를 썼는데 클라이언트가 ?id=abc 처럼 문자를 보냈다.

해결책:
정상적인 동작이다. 프론트엔드 개발자에게 "숫자를 보내세요!" 라고 알려주면 된다. 파이프가 서버 다운을 막아준 고마운 상황.

🗂️ 치트시트 — 실무 요약 카드

이것만 복붙해서 써!

📋 요청 받기 3총사

⚠️ 절대 하지 말 것

📝 마무리 퀴즈

Q1. 당신은 고객의 프로필을 업데이트하는 라우터를 만들고 싶다. URL 경로 규칙과 HTTP 메서드 데코레이터 조합으로 올바른 것은?

• A) @Post('/user/update')
• B) @Put(':id')
• C) @Get('/update/:id')
• D) @Controller(':id')

✅ 정답: B

💡 **설명:**REST API 규약에 따라 데이터의 업데이트(수정)는 PUT 또는 PATCH를 쓰며, 수정할 대상의 식별자는 @Param으로 넘기는 것이 정석이야.

Q2. 아래 빈칸을 채워봐.

컨트롤러에서 클라이언트가 보낸 JSON 데이터(예: 회원가입 양식) 전체를 하나의 객체로 이쁘게 가져오고 싶을 때 사용하는 데코레이터는?

@Post()
signup( [         ] body: SignupDto ) {
  return this.authService.register(body);
}

✅ 정답: @Body()
📌 핵심 기억법: 택배 상자(HTTP 통신) 안에 들어있는 내용물(본문 = Body)!

Q3. 디버깅 퀴즈: 아래 컨트롤러에서 발생할 문제를 찾아봐.

@Controller('files')
export class FilesController {
  
  @Get(':filename')
  downloadFile(@Param('filename') name: string) {
    return `파일 다운로드: ${name}`;
  }
 
  @Get('download-logs')
  downloadAllLogs() {
    return '모든 로그 압축 다운로드';
  }
}

이 코드를 실행하고 /files/download-logs 주소로 들어가면 어떤 일이 생길까?

• A) 원하던 대로 '모든 로그 압축 다운로드'가 나온다.
• B) '파일 다운로드: download-logs' 라는 문구가 뜬다.
• C) 500 에러 서버 크래시가 발생한다.

✅ 정답: B

💡 설명: 가장 징그럽게 겪을 라우팅 순서 오류야! 구체적인 경로인 @Get('download-logs')를 @Get(':filename') 보다 위로 올려야 해. 안 그러면 NestJS는 "아, 니가 요청한 파일 이름이 download-logs 구나!" 하고 착각해버려.

🔗 더 알아보기

• NestJS 공식 문서 - Controllers
• NestJS 공식 문서 - Modules
• 03. 서비스와 프로바이더 심화 가이드