【NestJS】07 装饰器说明书

刚学 Nest 时我总犯迷糊：写接口分不清@Query和@Param？注入依赖时总忘加@Inject？Filter 和 Interceptor 的装饰器总搞混？更头疼的是——重复的装饰器堆成山，内置功能满足不了定制需求？

今天这篇文章，我把**Nest 装饰器的“基础用法”和“自定义技巧”**揉成一份「实战指南」：从模块定义到请求处理，从依赖注入到异常控制，再到如何用自定义装饰器解决重复代码问题，一次性讲透！

一、先搭个 Demo 项目：边写边试才会会#

学装饰器最好的方式是动手实践，先创建一个干净的 Nest 项目：

1
nest new nest-decorator-guide -p npm  # -p npm指定用npm安装依赖
2
cd nest-decorator-guide
3
npm run start:dev  # 启动开发服务器，修改代码自动热更新

二、基础篇：Nest 常用装饰器“说明书”#

Nest 的核心功能几乎都通过装饰器实现，先把常用基础装饰器的用法和坑点讲清楚！

1. 模块与组件的“基础标签”：@Module、@Controller、@Injectable#

Nest 的「模块系统」是组织代码的核心，这三个装饰器是模块的“基石”：

@Module：定义模块的“说明书”#

模块是 Nest 项目的「最小功能单元」，用@Module标记的类会被 Nest 识别为模块，负责组织 Controller、Provider 和依赖关系：

1
import { Module } from '@nestjs/common'
2
import { AppController } from './app.controller'
3
import { AppService } from './app.service'
4

5
@Module({
6
  imports: [], // 导入其他模块（比如数据库模块）
7
  controllers: [AppController], // 模块的请求处理入口
8
  providers: [AppService], // 模块的依赖（Service、Repository等）
9
  exports: [], // 导出给其他模块用的Provider
10
})
11
export class AppModule {}

💡 小技巧：imports是“进口”（用别人的模块），exports是“出口”（让别人用自己的模块），两者是模块间的“双向门”～

@Controller：请求的“处理入口”#

@Controller用来定义请求的路由前缀，比如@Controller('users')表示所有/users开头的请求（如/users/list）都由这个 Controller 处理：

1
import { Controller, Get } from '@nestjs/common'
2

3
@Controller('users') // 路由前缀：/users
4
export class UsersController {
5
  @Get('list') // 完整路由：/users/list
6
  getUsers() {
7
    return ['张三', '李四']
8
  }
9
}

@Injectable：可注入的“依赖对象”#

Nest 的**依赖注入（DI）**是核心功能，@Injectable告诉 Nest：这个类可以被注入到其他类中（比如 Service 层）。必须加这个装饰器，否则无法注入！

1
import { Injectable } from '@nestjs/common'
2

3
@Injectable()
4
export class UsersService {
5
  getUsers() {
6
    return ['张三', '李四'] // 实际项目中这里会调用数据库
7
  }
8
}

然后在 Controller 中构造器注入（推荐写法）：

1
import { Controller, Get } from '@nestjs/common'
2
import { UsersService } from './users.service'
3

4
@Controller('users')
5
export class UsersController {
6
  constructor(private readonly usersService: UsersService) {} // 构造器注入
7

8
  @Get('list')
9
  getUsers() {
10
    return this.usersService.getUsers() // 调用Service的方法
11
  }
12
}

2. 依赖注入的“进阶技巧”：@Inject、@Optional、@Global#

依赖注入不是只有构造器注入一种方式，这些装饰器帮你解决更复杂的依赖场景：

@Inject：非类依赖的“注入令牌”#

如果依赖不是类（比如常量配置、动态对象），需要用@Inject指定注入 token（字符串或 Symbol）。比如用useValue注入配置：

1
import { Module } from '@nestjs/common'
2

3
const config = {
4
  // 常量配置
5
  db: 'mongodb://localhost:27017/nest',
6
  port: 3000,
7
}
8

9
@Module({
10
  providers: [
11
    {
12
      provide: 'CONFIG', // token：字符串
13
      useValue: config, // 注入的值
14
    },
15
  ],
16
  exports: ['CONFIG'], // 导出给其他模块用
17
})
18
export class ConfigModule {}

在 Service 中注入配置：

1
import { Injectable, Inject } from '@nestjs/common'
2

3
@Injectable()
4
export class UsersService {
5
  constructor(@Inject('CONFIG') private readonly config: Record<string, any>) {} // 用@Inject指定token
6

7
  getDbUrl() {
8
    return this.config.db // 访问配置中的db地址
9
  }
10
}

@Optional：可选依赖的“安全锁”#

如果某个依赖不是必须的（比如可选的日志插件），加@Optional就不会因为找不到依赖而报错：

1
import { Injectable, Inject, Optional } from '@nestjs/common'
2

3
@Injectable()
4
export class UsersService {
5
  constructor(
6
    @Optional() @Inject('LOGGER') private readonly logger?: LoggerService // 可选依赖
7
  ) {}
8

9
  log(message: string) {
10
    this.logger?.log(message) // 有logger就打印，没有就跳过
11
  }
12
}

@Global：全局模块的“通行证”#

如果某个模块的 Provider全局都要用（比如数据库连接），用@Global标记为全局模块，不用每次都导入：

1
import { Module, Global } from '@nestjs/common'
2
import { DatabaseService } from './database.service'
3

4
@Global() // 全局模块
5
@Module({
6
  providers: [DatabaseService],
7
  exports: [DatabaseService], // 必须导出，否则全局无法注入
8
})
9
export class DatabaseModule {}

3. 请求处理的“参数提取器”：@Query、@Param、@Body、@Headers#

写接口时最常用的就是提取请求参数，这些装饰器帮你快速拿到数据，不用手动解析req对象：

@Query：提取 URL 查询参数（?后面的部分）#

比如请求/users/list?page=1&size=10，用@Query取page和size：

1
import { Controller, Get, Query } from '@nestjs/common'
2

3
@Controller('users')
4
export class UsersController {
5
  @Get('list')
6
  getUsers(
7
    @Query('page') page: number = 1, // 取查询参数page，默认值1
8
    @Query('size') size: number = 10 // 取查询参数size，默认值10
9
  ) {
10
    return `当前页：${page}，每页${size}条`
11
  }
12
}

@Param：提取 URL 路径参数（/ 部分）#

比如请求/users/123，用@Param取路径中的id：

1
import { Controller, Get, Param } from '@nestjs/common'
2

3
@Controller('users')
4
export class UsersController {
5
  @Get(':id') // 路径中的id参数
6
  getUserById(@Param('id') id: string) {
7
    // 取路径参数id
8
    return `用户ID：${id}`
9
  }
10
}

@Body：提取请求体（POST/PUT 数据）#

POST 请求的 JSON 数据用@Body提取，配合**DTO（数据传输对象）**更规范（约束请求体格式）：

1
// src/users/dto/create-user.dto.ts（定义DTO）
2
export class CreateUserDto {
3
  name: string // 用户名（必填）
4
  age?: number // 年龄（可选）
5
}

在 Controller 中接收请求体：

1
import { Controller, Post, Body } from '@nestjs/common'
2
import { CreateUserDto } from './dto/create-user.dto'
3

4
@Controller('users')
5
export class UsersController {
6
  @Post()
7
  createUser(@Body() createUserDto: CreateUserDto) {
8
    // 用DTO约束格式
9
    return `创建用户：${createUserDto.name}，年龄${createUserDto.age}`
10
  }
11
}

@Headers：提取请求头#

比如取Authorization头（token）：

1
import { Controller, Get, Headers } from '@nestjs/common'
2

3
@Controller('users')
4
export class UsersController {
5
  @Get('profile')
6
  getProfile(@Headers('authorization') token: string) {
7
    // 取Authorization头
8
    return `Token：${token}`
9
  }
10
}

4. 异常与响应的“控制工具”：@Catch、@UseFilters、@HttpCode、@Header#

处理异常和定制响应是接口开发的必经之路，这些装饰器帮你快速实现：

@Catch 与@UseFilters：处理未捕获异常#

Filter 用来处理未捕获的异常，@Catch指定要处理的异常类型，@UseFilters应用 Filter：

1
// src/common/filters/http-exception.filter.ts（定义Filter）
2
import { ExceptionFilter, Catch, HttpException } from '@nestjs/common'
3
import { Request, Response } from 'express'
4

5
@Catch(HttpException) // 只处理Http异常（如404、500）
6
export class HttpExceptionFilter implements ExceptionFilter {
7
  catch(exception: HttpException, host: ArgumentsHost) {
8
    const ctx = host.switchToHttp()
9
    const response = ctx.getResponse<Response>()
10
    const request = ctx.getRequest<Request>()
11
    const status = exception.getStatus() // 异常状态码
12

13
    response.status(status).json({
14
      // 自定义异常响应格式
15
      statusCode: status,
16
      timestamp: new Date().toISOString(),
17
      path: request.url,
18
      message: exception.message,
19
    })
20
  }
21
}

在 Controller 中应用 Filter：

1
import { Controller, Get, UseFilters } from '@nestjs/common'
2
import { HttpExceptionFilter } from '../common/filters/http-exception.filter'
3

4
@Controller('users')
5
@UseFilters(HttpExceptionFilter) // 应用到整个Controller
6
export class UsersController {
7
  @Get('error')
8
  throwError() {
9
    throw new HttpException('自定义错误', 400) // 抛出异常，由Filter处理
10
  }
11
}

@HttpCode：修改响应状态码#

接口默认返回200 OK，用@HttpCode修改状态码：

1
import { Controller, Post, HttpCode } from '@nestjs/common'
2

3
@Controller('users')
4
export class UsersController {
5
  @Post()
6
  @HttpCode(201) // 创建成功返回201 Created
7
  createUser() {
8
    return '用户创建成功'
9
  }
10
}

比如给响应加Cache-Control头，禁止浏览器缓存：

1
import { Controller, Get, Header } from '@nestjs/common'
2

3
@Controller('users')
4
export class UsersController {
5
  @Get('profile')
6
  @Header('Cache-Control', 'no-store') // 禁止缓存
7
  getProfile() {
8
    return '用户信息'
9
  }
10
}

5. 请求与响应的“直接操作”：@Req、@Res、@Next#

有时候需要直接操作req或res对象（比如自定义响应格式），这些装饰器帮你拿到原始对象：

@Req/@Request：注入请求对象#

@Req是@Request的别名，用来注入 Express 的req对象：

1
import { Controller, Get, Req } from '@nestjs/common'
2
import { Request } from 'express'
3

4
@Controller('users')
5
export class UsersController {
6
  @Get('info')
7
  getUserInfo(@Req() req: Request) {
8
    // 注入req对象
9
    return `请求IP：${req.ip}，请求方法：${req.method}`
10
  }
11
}

@Res/@Response：注入响应对象#

⚠️ 重点注意：注入@Res后，Nest不会自动返回响应（避免和你手动返回的响应冲突），必须自己用res.send()或res.json()返回：

1
import { Controller, Get, Res } from '@nestjs/common'
2
import { Response } from 'express'
3

4
@Controller('users')
5
export class UsersController {
6
  @Get('custom')
7
  customResponse(@Res() res: Response) {
8
    // 注入res对象
9
    res.status(200).json({
10
      // 手动返回响应
11
      code: 0,
12
      message: '自定义响应',
13
      data: null,
14
    })
15
  }
16
}

如果想让 Nest 继续处理返回值，加passthrough: true：

1
@Get('custom')
2
customResponse(@Res({ passthrough: true }) res: Response) {
3
  res.header('X-Custom-Header', 'value'); // 加自定义头
4
  return 'Nest会处理这个返回值'; // Nest会把返回值作为响应内容
5
}

@Next：请求转发#

当多个 Handler 处理同一个路由时，用@Next把请求转发到下一个 Handler：

1
import { Controller, Get, Next } from '@nestjs/common'
2
import { NextFunction } from 'express'
3

4
@Controller('users')
5
export class UsersController {
6
  @Get('multi')
7
  firstHandler(@Next() next: NextFunction) {
8
    // 第一个Handler
9
    console.log('第一个Handler执行')
10
    next() // 转发到下一个Handler
11
  }
12

13
  @Get('multi')
14
  secondHandler() {
15
    // 第二个Handler
16
    return '第二个Handler的返回值'
17
  }
18
}

三、进阶篇：自定义装饰器——从“重复造轮子”到“优雅封装”#

当内置装饰器不够用，或重复代码太多时，自定义装饰器就是解决之道！

1. 自定义方法装饰器：告别“原始”的@SetMetadata#

Nest 的@SetMetadata用来给 Handler 设置元数据（比如权限角色），但直接用太“裸”——我们可以封装成语义化的装饰器：

原始痛点：@SetMetadata 的“不优雅”#

比如一个需要“admin”权限的接口，原始写法：

1
import { Controller, Get, SetMetadata, UseGuards } from '@nestjs/common'
2
import { AuthGuard } from './auth.guard'
3

4
@Controller()
5
export class AppController {
6
  @Get('profile')
7
  @SetMetadata('role', 'admin') // 写死的元数据键名，容易拼错
8
  @UseGuards(AuthGuard) // 还要单独加Guard
9
  getProfile() {
10
    return '管理员专属页面'
11
  }
12
}

封装自定义装饰器：@Role#

把@SetMetadata封装成@Role，语义化更清晰：

1
import { SetMetadata } from '@nestjs/common'
2

3
export const ROLE_KEY = 'role' // 用常量避免拼错元数据键名
4

5
export function Role(role: string) {
6
  return SetMetadata(ROLE_KEY, role) // 相当于@SetMetadata('role', role)
7
}

使用自定义装饰器#

现在接口可以简化为：

1
import { Controller, Get, UseGuards } from '@nestjs/common'
2
import { Role } from './decorators/role.decorator'
3
import { AuthGuard } from './auth.guard'
4

5
@Controller()
6
export class AppController {
7
  @Get('profile')
8
  @Role('admin') // 语义化的装饰器，比@SetMetadata清爽10倍！
9
  @UseGuards(AuthGuard)
10
  getProfile() {
11
    return '管理员专属页面'
12
  }
13
}

2. 组合装饰器：用 applyDecorators 合并重复代码#

如果一个接口需要多个装饰器（比如@Get+@Role+@UseGuards），重复写三次太麻烦。Nest 的applyDecorators能帮我们把它们合并成一个装饰器，减少冗余！

合并前的“重复”写法#

比如三个接口都需要相同的装饰器组合：

1
@Controller()
2
export class AppController {
3
  @Get('profile')
4
  @Role('admin')
5
  @UseGuards(AuthGuard)
6
  getProfile() {
7
    return '管理员页面'
8
  }
9

10
  @Get('dashboard')
11
  @Role('admin')
12
  @UseGuards(AuthGuard)
13
  getDashboard() {
14
    return '控制台'
15
  }
16

17
  @Get('settings')
18
  @Role('admin')
19
  @UseGuards(AuthGuard)
20
  getSettings() {
21
    return '设置页'
22
  }
23
}

用 applyDecorators 合并：@Auth#

我们封装一个@Auth装饰器，把三个装饰器“打包”成一个：

1
import { applyDecorators, Get, UseGuards } from '@nestjs/common'
2
import { Role } from './role.decorator'
3
import { AuthGuard } from '../auth.guard'
4

5
// 传入接口路径和角色，返回组合后的装饰器
6
export function Auth(path: string, role: string) {
7
  return applyDecorators(
8
    Get(path), // 对应@Get(path)
9
    Role(role), // 对应@Role(role)
10
    UseGuards(AuthGuard) // 对应@UseGuards(AuthGuard)
11
  )
12
}

使用组合装饰器#

现在三个接口可以简化成一行装饰器，代码瞬间清爽：

1
import { Controller } from '@nestjs/common'
2
import { Auth } from './decorators/auth.decorator'
3

4
@Controller()
5
export class AppController {
6
  @Auth('profile', 'admin') // 一个装饰器顶三个！
7
  getProfile() {
8
    return '管理员页面'
9
  }
10

11
  @Auth('dashboard', 'admin')
12
  getDashboard() {
13
    return '控制台'
14
  }
15

16
  @Auth('settings', 'admin')
17
  getSettings() {
18
    return '设置页'
19
  }
20
}

💡 小技巧：applyDecorators支持任意多个装饰器，顺序和你传入的一致——比如先加Get，再加Role，最后加UseGuards，和手动写的顺序完全一样！

3. 自定义参数装饰器：实现自己的@Query/@Headers#

Nest 的内置参数装饰器（如@Query、@Headers）都是用createParamDecorator创建的。我们也能自己写一个，解决定制化需求！

需求：保持请求头的键名原样#

内置@Headers会把键名转成小写（比如Authorization变成authorization），但我们想保持键名原样——自己写个@MyHeaders！

实现自定义参数装饰器：@MyHeaders#

用createParamDecorator创建参数装饰器，它的回调函数能拿到装饰器参数和执行上下文（ExecutionContext）：

1
import { createParamDecorator, ExecutionContext } from '@nestjs/common'
2
import { Request } from 'express'
3

4
export const MyHeaders = createParamDecorator(
5
  (key: string, ctx: ExecutionContext) => {
6
    // 1. 从执行上下文拿到HTTP请求对象
7
    const request: Request = ctx.switchToHttp().getRequest()
8
    // 2. 有key就返回对应请求头，没有就返回所有请求头
9
    return key ? request.headers[key] : request.headers
10
  }
11
)

使用自定义参数装饰器#

和内置@Headers对比，看看效果：

1
import { Controller, Get, Headers } from '@nestjs/common'
2
import { MyHeaders } from './decorators/my-headers.decorator'
3

4
@Controller()
5
export class AppController {
6
  @Get('headers')
7
  getHeaders(
8
    @Headers('Authorization') auth1: string, // 内置装饰器：转小写→undefined
9
    @MyHeaders('Authorization') auth2: string // 自定义装饰器：保持原样→Bearer xxx
10
  ) {
11
    return { auth1, auth2 }
12
  }
13
}

再试一个：实现自己的@Query#

内置@Query能取 URL 查询参数，我们也能写个@MyQuery，逻辑完全一样：

1
import { createParamDecorator, ExecutionContext } from '@nestjs/common'
2
import { Request } from 'express'
3

4
export const MyQuery = createParamDecorator(
5
  (key: string, ctx: ExecutionContext) => {
6
    const request: Request = ctx.switchToHttp().getRequest()
7
    return key ? request.query[key] : request.query
8
  }
9
)

用起来和内置@Query一毛一样：

1
@Get('query')
2
getQuery(
3
  @Query('name') name1: string,  // 内置
4
  @MyQuery('name') name2: string, // 自定义
5
) {
6
  return { name1, name2 }; // 结果完全一致！
7
}

4. 自定义类装饰器：给 Controller 加“全局”元数据#

除了方法和参数装饰器，我们还能给类（比如 Controller）加自定义装饰器，用来设置全局元数据（比如模块标识）。

实现类装饰器：@ModuleTag#

用SetMetadata给类设置元数据：

1
import { SetMetadata } from '@nestjs/common'
2

3
export const MODULE_TAG_KEY = 'module_tag' // 元数据键名（常量避免拼错）
4

5
export function ModuleTag(tag: string) {
6
  return SetMetadata(MODULE_TAG_KEY, tag) // 给类设置模块标识
7
}

给 Controller 加类装饰器#

给AppController加@ModuleTag，标记它属于“user-module”：

1
import { Controller } from '@nestjs/common'
2
import { ModuleTag } from './decorators/module-tag.decorator'
3

4
@Controller()
5
@ModuleTag('user-module') // 给整个Controller加模块标识
6
export class AppController {
7
  /* ... */
8
}

在 Guard 中取类的元数据#

用Reflector的get方法，从 Controller 类中提取元数据：

1
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common'
2
import { Reflector } from '@nestjs/core'
3
import { MODULE_TAG_KEY } from './decorators/module-tag.decorator'
4

5
@Injectable()
6
export class AuthGuard implements CanActivate {
7
  constructor(private reflector: Reflector) {}
8

9
  canActivate(context: ExecutionContext): boolean {
10
    // 取Controller类的元数据：MODULE_TAG_KEY
11
    const moduleTag = this.reflector.get(MODULE_TAG_KEY, context.getClass())
12
    console.log('当前模块:', moduleTag) // 打印：user-module
13
    return true
14
  }
15
}

四、总结：自定义装饰器的“核心玩法”#

最后把所有常用装饰器整理成速查表，方便你快速查询：

装饰器	作用说明	常用场景
`@Module`	定义模块	组织 Controller、Provider
`@Controller`	定义请求处理的 Controller	处理 HTTP 请求
`@Injectable`	标记可注入的 Provider	Service、Repository 层
`@Inject`	指定注入的 token	非类依赖注入
`@Optional`	标记可选依赖	可选的插件或配置
`@Global`	标记全局模块	数据库连接、配置服务
`@Query`	提取 URL 查询参数	`/list?page=1`
`@Param`	提取 URL 路径参数	`/users/:id`
`@Body`	提取请求体	POST/PUT 请求
`@Headers`	提取请求头	取 Authorization token
`@Catch`	指定 Filter 处理的异常类型	自定义异常处理
`@UseFilters`	应用 Filter	处理 Controller/接口异常
`@HttpCode`	修改响应状态码	自定义状态码（如 201）
`@Header`	修改响应头	加自定义头（如 Cache-Control）
`@Req`/`@Request`	注入 req 对象	手动处理请求
`@Res`/`@Response`	注入 res 对象	手动处理响应

到这里，Nest 的常用装饰器就讲完啦！其实核心逻辑是用装饰器标记「元数据」，让 Nest 知道如何处理类、方法和参数。熟练掌握这些装饰器，写 Nest 接口会像搭积木一样轻松～

通过上面的实战，我们学会了 Nest 自定义装饰器的三大场景和关键技巧：

自定义装饰器的三大场景

装饰器类型	核心 API	常见用途
方法装饰器	`SetMetadata`、`applyDecorators`	封装权限校验（如`@Role`）、合并重复装饰器（如`@Auth`）
参数装饰器	`createParamDecorator`	定制请求参数提取（如`@MyHeaders`、`@MyQuery`）
类装饰器	`SetMetadata`	给 Controller/Module 设置全局元数据（如`@ModuleTag`）

关键技巧

语义化命名：装饰器名字要直观（比如@Role比@SetMetadata好懂）；
常量存元数据键名：用常量避免拼错（比如ROLE_KEY = 'role'）；
组合装饰器：用applyDecorators合并重复代码，减少冗余；
ExecutionContext：参数装饰器中用它拿到request/response，实现定制化提取。

最后一句提醒

自定义装饰器不是“花活”——它的核心是减少重复代码，提升代码可读性。如果一个装饰器能让你的代码少写 10 行重复逻辑，那就值得封装！

参考文档：Nest 官方自定义装饰器文档 参考文档：Nest 官方装饰器文档

到这里，Nest 的常用装饰器就讲完啦！其实核心逻辑是用装饰器标记「元数据」，😎 让 Nest 知道如何处理类、方法和参数。熟练掌握这些装饰器，写 Nest 接口会像搭积木一样轻松～

音乐

音乐