¿Cómo funciona el enrutamiento en NestJS?

Question

Accepted Answer

El **enrutamiento** en NestJS es **basado en decoradores**: asignas rutas de URL y métodos HTTP a métodos de controlador usando decoradores. El prefijo de ruta viene de `@Controller()` y la ruta específica + verbo HTTP de decoradores de método como `@Get()` — se combinan para formar la ruta completa.

## Cómo se componen las rutas

```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) {}
}
```

El prefijo del controlador + la ruta del decorador del método se combinan: `@Get(":id")` dentro de `@Controller("users")` → `GET /users/:id`. Cada verbo HTTP tiene su propio decorador (`@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`).

## Parámetros de ruta y cadenas 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
) {}
```

## Rutas anidadas/comodín y subrutas

```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() {}
}
```

## El orden de las rutas importa

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

Las rutas específicas (estáticas) deben declararse antes que las dinámicas (`:param`), de lo contrario la ruta dinámica podría capturarlas.

## Prefijo global y versionado

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

Un prefijo global (p. ej. `/api/v1`) se aplica a todas las rutas — común para convenciones de API.

## Por qué es importante

El enrutamiento es fundamental — define la estructura de URL de tu API y es cómo cada solicitud llega al controlador correcto.

Comprender el **enrutamiento basado en decoradores de NestJS** (el prefijo `@Controller` combinado con decoradores de método `@Get`/`@Post`/etc. para formar rutas completas, y `@Param`/`@Query` para extraer datos) es conocimiento esencial cotidiano — es cómo construyes cada punto final, y el estilo declarativo mantiene el enrutamiento limpio y legible en comparación con el registro manual de rutas.

Conocer los detalles prácticos — composición de prefijos y rutas, manejo de parámetros de ruta y cadenas de consulta, rutas de recursos anidadas, la importancia del **orden de las rutas** (estática antes de dinámica) y prefijos globales/versionado para convenciones de API — es necesario para crear REST APIs bien estructuradas en NestJS.

El enrutamiento, los controladores y los decoradores de parámetros juntos forman la base del manejo de solicitudes del framework, lo que convierte esto en material fundamental que todo desarrollador de NestJS debe conocer.