Как работает маршрутизация в NestJS?

Question

Accepted Answer

**Маршрутизация** в NestJS **основана на декораторах**: вы сопоставляете пути URL и методы HTTP с методами контроллера, используя декораторы. Префикс маршрута берётся из `@Controller()`, а конкретный путь + HTTP-глагол из декораторов методов, таких как `@Get()` — в сочетании они формируют полный маршрут.

## Как компонуются маршруты

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

Префикс контроллера + путь декоратора метода объединяются: `@Get(":id")` внутри `@Controller("users")` → `GET /users/:id`. Каждый HTTP-глагол имеет собственный декоратор (`@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`).

## Параметры маршрута и строки запроса

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

## Вложенные/подстановочные маршруты и подпути

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

## Порядок маршрутов имеет значение

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

Специфические (статические) маршруты должны объявляться перед динамическими (`:param`), иначе динамический маршрут может их перехватить.

## Почему это важно

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

Глобальный префикс (например `/api/v1`) применяется ко всем маршрутам — распространённый вариант для API соглашений.

Маршрутизация является фундаментальной — она определяет структуру URL вашего API и определяет, как каждый запрос достигает правильного обработчика.

Понимание **маршрутизации на основе декораторов** в NestJS (префикс контроллера, объединённый с декораторами методов `@Get`/`@Post`/и т.д. для формирования полных маршрутов, и `@Param`/`@Query` для извлечения данных) — это необходимые повседневные знания — так вы создаёте каждую конечную точку, и декларативный стиль сохраняет маршрутизацию чистой и понятной по сравнению с ручной регистрацией маршрутов.

Знание практических деталей — композиция префиксов и путей, обработка параметров маршрута и строк запроса, вложенные маршруты ресурсов, важность **порядка маршрутов** (статические перед динамическими) и глобальные префиксы/версионирование для API соглашений — необходимо для создания хорошо структурированных REST API в NestJS.

Маршрутизация, контроллеры и декораторы параметров вместе образуют фундамент обработки запросов фреймворка, делая это основным материалом, который должен знать любой разработчик NestJS.