NestJS 中路由如何工作？

Question

NestJS 中路由如何工作？

Accepted Answer

**Routing** 在 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 约定中很常见。

## 为什么这很重要

路由是基础性的 — 它定义了您的 API 的 URL 结构，以及每个请求如何到达正确的处理程序。

理解 NestJS 的**基于装饰器的路由**（`@Controller` 前缀与 `@Get`/`@Post`/等方法装饰器结合形成完整路由，以及 `@Param`/`@Query` 来提取数据）是日常必备知识 — 这就是您构建每个端点的方式，声明式风格相比手动路由注册保持路由清洁且易读。

了解实际细节是必需的 — 组合前缀和路径、处理路由参数和查询字符串、嵌套资源路由、**路由顺序**的重要性（静态在动态之前）以及用于 API 约定的全局前缀/版本控制 — 这些对于在 NestJS 中构建结构良好的 REST API 是必要的。

路由、控制器和参数装饰器共同构成框架的请求处理基础，使这成为任何 NestJS 开发者必知的核心内容。