NestJS에서 라우팅은 어떻게 동작하나요?

Question

Accepted Answer

NestJS의 **라우팅**은 **decorator 기반**입니다: decorator를 사용하여 URL 경로와 HTTP 메서드를 controller 메서드에 매핑합니다. 라우트 prefix는 `@Controller()`에서, 구체적인 경로 + HTTP 동사는 `@Get()` 같은 메서드 decorator에서 옵니다 — 이들이 결합하여 전체 라우트를 형성합니다.

## 라우트가 구성되는 방식

```ts
@Controller("users")          // PREFIX: 모든 라우트가 /users로 시작
export class UsersController {
  @Get()                       // GET /users
  findAll() {}

@Get("active")               // GET /users/active
  findActive() {}

@Get(":id")                  // GET /users/:id (동적 파라미터)
  findOne(@Param("id") id: string) {}

@Post()                      // POST /users
  create(@Body() dto: CreateUserDto) {}

@Put(":id")                  // PUT /users/:id
  update(@Param("id") id: string, @Body() dto: UpdateUserDto) {}

@Delete(":id")               // DELETE /users/:id
  remove(@Param("id") id: string) {}
}
```

controller prefix + 메서드 decorator의 경로가 결합됩니다: `@Controller("users")` 안의 `@Get(":id")` → `GET /users/:id`. 각 HTTP 동사는 고유한 decorator(`@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`)를 가집니다.

## 라우트 파라미터와 쿼리 문자열

```ts
@Get(":id")
example(
  @Param("id") id: string,        // 경로 파라미터: /users/123 → id = "123"
  @Query("sort") sort: string,    // 쿼리: /users?sort=name → sort = "name"
  @Query() allQuery: any,         // 전체 쿼리 객체
) {}
```

## 중첩/와일드카드 라우트와 하위 경로

```ts
@Controller("users")
export class UsersController {
  @Get(":id/posts")              // GET /users/:id/posts (중첩 리소스)
  getUserPosts(@Param("id") id: string) {}

@Get("search/*")               // 와일드카드 매칭
  search() {}
}
```

## 라우트 순서가 중요합니다

```ts
@Get("active")    // ✅ 구체적인 라우트 먼저
findActive() {}
@Get(":id")        // 동적 라우트 나중에 — 아니면 "active"가 :id에 매칭됨
findOne() {}
```

구체적인(정적) 라우트는 동적(`:param`) 라우트보다 먼저 선언되어야 합니다. 그렇지 않으면 동적 라우트가 이를 가로챌 수 있습니다.

## 전역 prefix와 버전 관리

```ts
app.setGlobalPrefix("api/v1");   // 모든 라우트가 /api/v1/...이 됨
// NestJS는 API 버전 관리도 지원합니다 (URI, 헤더, 미디어 타입 기반)
```

전역 prefix(예: `/api/v1`)는 모든 라우트에 적용됩니다 — API 규칙에 흔합니다.

## 왜 중요한가

라우팅은 기본적입니다 — API의 URL 구조를 정의하며 모든 요청이 올바른 핸들러에 도달하는 방법입니다.

NestJS의 **decorator 기반 라우팅**(`@Controller` prefix와 `@Get`/`@Post` 등 메서드 decorator를 결합하여 전체 라우트를 형성하고, `@Param`/`@Query`로 데이터 추출)을 이해하는 것은 필수적인 일상 지식입니다 — 모든 엔드포인트를 구축하는 방법이며, 선언적 스타일은 수동 라우트 등록에 비해 라우팅을 깔끔하고 읽기 쉽게 유지합니다.

실무적 세부 사항 — prefix와 경로 조합, 라우트 파라미터와 쿼리 문자열 처리, 중첩 리소스 라우트, **라우트 순서**의 중요성(정적이 동적보다 먼저), API 규칙을 위한 전역 prefix/버전 관리 — 를 아는 것은 NestJS에서 잘 구조화된 REST API를 구축하는 데 필요합니다.

라우팅, controller, 파라미터 decorator는 함께 프레임워크의 요청 처리 기반을 형성하므로, 이는 모든 NestJS 개발자가 반드시 알아야 할 핵심 자료입니다.