Como o roteamento funciona em NestJS?

Question

Accepted Answer

**Roteamento** em NestJS é **baseado em decoradores**: você mapeia caminhos de URL e métodos HTTP para métodos de controlador usando decoradores. O prefixo de rota vem de `@Controller()` e o caminho específico + verbo HTTP vêm de decoradores de método como `@Get()` — combinados formam a rota completa.

## Como as rotas são compostas

```ts
@Controller("users")          // PREFIX: all routes start with /users
export class UsersController {
  @Get()                       // GET /users
  findAll() {}

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

@Get(":id")                  // GET /users/:id (dynamic parameter)
  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) {}
}
```

O prefixo do controlador + o caminho do decorador de método se combinam: `@Get(":id")` dentro de `@Controller("users")` → `GET /users/:id`. Cada verbo HTTP tem seu próprio decorador (`@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`).

## Parâmetros de rota e strings de consulta

```ts
@Get(":id")
example(
  @Param("id") id: string,        // path param: /users/123 → id = "123"
  @Query("sort") sort: string,    // query: /users?sort=name → sort = "name"
  @Query() allQuery: any,         // the whole query object
) {}
```

## Rotas aninhadas/curinga e sub-caminhos

```ts
@Controller("users")
export class UsersController {
  @Get(":id/posts")              // GET /users/:id/posts (nested resource)
  getUserPosts(@Param("id") id: string) {}

@Get("search/*")               // wildcard matching
  search() {}
}
```

## A ordem das rotas importa

```ts
@Get("active")    // ✅ specific route FIRST
findActive() {}
@Get(":id")        // dynamic route AFTER — else "active" would match :id
findOne() {}
```

Rotas específicas (estáticas) devem ser declaradas antes das dinâmicas (`:param`), caso contrário a rota dinâmica pode capturá-las.

## Por que isso importa

```ts
app.setGlobalPrefix("api/v1");   // all routes become /api/v1/...
// NestJS also supports API versioning (URI, header, media-type based)
```

Um prefixo global (por exemplo, `/api/v1`) se aplica a todas as rotas — comum para convenções de API.

Roteamento é fundamental — define a estrutura de URL da sua API e é como cada requisição chega ao manipulador correto.

Entender o **roteamento baseado em decoradores** do NestJS (o prefixo do controlador combinado com decoradores de método `@Get`/`@Post`/etc. para formar rotas completas, e `@Param`/`@Query` para extrair dados) é conhecimento essencial do dia a dia — é assim que você constrói cada endpoint, e o estilo declarativo mantém o roteamento limpo e legível comparado ao registro manual de rotas.

Conhecer os detalhes práticos — compor prefixos e caminhos, lidar com parâmetros de rota e strings de consulta, rotas de recursos aninhadas, a importância da **ordem das rotas** (estática antes da dinâmica) e prefixos globais/versionamento para convenções de API — é necessário para construir APIs REST bem estruturadas em NestJS.

Roteamento, controladores e decoradores de parâmetros juntos formam a base de manipulação de requisições do framework, tornando este material essencial que todo desenvolvedor NestJS deve conhecer.