小满nestjs（第八章 控制器参数解析实战：从装饰器到业务应用）

1. 控制器参数装饰器基础入门

刚开始接触NestJS时，最让我困惑的就是如何优雅地获取前端传递的参数。传统Express开发中我们需要手动从req对象里提取数据，而NestJS提供的一系列参数装饰器简直就像开了外挂。记得我第一次用@Query()直接拿到URL参数时，那种"原来还能这样"的惊喜感至今难忘。

先来看个最简单的例子。假设我们要开发一个用户搜索接口，传统Express写法是这样的：

@Get('search') searchUser(req) { const keyword = req.query.keyword const page = req.query.page // ...业务逻辑 }

而在NestJS中，我们可以简化为：

@Get('search') searchUser(@Query('keyword') keyword: string, @Query('page') page: number) { // ...直接使用keyword和page }

这种写法不仅更简洁，还能利用TypeScript的类型提示。实际开发中我发现，合理使用这些装饰器能让代码可读性提升至少50%。常用的基础装饰器包括：

• @Query()：获取URL查询参数
• @Body()：获取POST请求体
• @Param()：获取路由参数
• @Headers()：获取请求头信息
• @HttpCode()：设置响应状态码

每个装饰器都可以单独使用，也可以组合使用。比如处理用户登录接口时，我通常会同时用到@Body()获取账号密码和@Headers()获取设备信息。

2. GET请求参数处理实战

在实际项目中，GET请求的参数处理看似简单却暗藏玄机。先分享一个我踩过的坑：有次接口突然报错，排查半天发现是前端传了个数组参数，而我没有做特殊处理。后来才知道@Query()对数组参数需要特殊配置。

2.1 基础查询参数处理

最基本的用法就是获取单个查询参数：

@Get('list') getUserList(@Query('page') page: number) { // 获取?page=1中的page值 }

但实际业务中，我们经常需要获取多个参数。这时可以有两种写法：

// 方式一：逐个获取 @Get('list') getUserList( @Query('page') page: number, @Query('size') size: number ) {...} // 方式二：获取整个query对象 @Get('list') getUserList(@Query() params: {page: number; size: number}) {...}

我个人的经验是：当参数少于3个时用方式一更清晰，参数多时用方式二更合适。特别是需要把参数直接传递给service层时，方式二会更方便。

2.2 处理特殊类型参数

对于数组参数，需要特别注意：

// 前端传参：?ids=1,2,3 @Get('detail') getDetails(@Query('ids') ids: string) { // ids是字符串"1,2,3" const idArray = ids.split(',') }

更优雅的写法是使用class-transformer：

import { Type } from 'class-transformer' class GetDetailsDto { @Type(() => Number) ids: number[] } @Get('detail') getDetails(@Query() query: GetDetailsDto) { // query.ids已经是number数组[1,2,3] }

3. POST请求体处理技巧

POST请求的参数处理是API开发的重头戏。这里我强烈推荐结合DTO（数据传输对象）来使用@Body()装饰器，这能让代码更健壮、更易维护。

3.1 基础表单数据处理

最简单的POST接口可以这样写：

@Post('create') createUser(@Body() body: any) { // body就是前端传来的JSON对象 }

但这种写法没有任何类型校验，实际项目中我们应该定义明确的DTO：

class CreateUserDto { username: string password: string age?: number // 可选参数 } @Post('create') createUser(@Body() createUserDto: CreateUserDto) { // 现在createUserDto有完整的类型提示 }

3.2 结合class-validator做数据校验

光有类型还不够，我们还需要数据校验。NestJS完美支持class-validator：

import { IsString, IsNotEmpty, IsOptional, IsInt } from 'class-validator' class CreateUserDto { @IsString() @IsNotEmpty() username: string @IsString() @IsNotEmpty() password: string @IsOptional() @IsInt() age?: number } @Post('create') createUser(@Body() createUserDto: CreateUserDto) { // 参数会自动校验，无效请求会被拦截 }

这种组合使用DTO和校验装饰器的模式，在我的项目中减少了约70%的参数校验代码。校验失败时，NestJS会自动返回400错误和详细的错误信息。

4. 动态路由与请求头处理

动态路由参数和请求头信息在RESTful API中也很常见，NestJS提供了专门的装饰器来处理这些场景。

4.1 动态路由参数处理

假设我们要实现一个用户详情接口，路由是/user/:id：

@Get(':id') getUserDetail(@Param('id') id: string) { // 获取路由中的id参数 }

这里有个实用技巧：如果路由中有多个参数，可以一次性获取：

@Get(':type/:id') getDetail( @Param() params: {type: string; id: string} ) { // params包含type和id两个属性 }

4.2 请求头信息获取

获取请求头信息同样简单：

@Get('profile') getProfile(@Headers('authorization') token: string) { // 获取Authorization头 }

或者获取全部请求头：

@Get('profile') getProfile(@Headers() headers: Record<string, string>) { // headers对象包含所有请求头 }

在实际项目中，我常用这种方式获取客户端信息、认证token等。比如移动端API可能需要区分iOS和Android：

@Get('version') checkVersion(@Headers('user-agent') ua: string) { if (ua.includes('Android')) { // 返回Android专用逻辑 } // ... }

5. 响应状态码与高级技巧

控制响应状态码是API开发的重要环节，NestJS提供了多种方式来实现。

5.1 使用@HttpCode设置状态码

最简单的设置状态码的方式：

@Post('create') @HttpCode(201) // 设置创建成功的状态码 createUser(@Body() createUserDto: CreateUserDto) { // ... }

5.2 动态状态码处理

有时我们需要根据业务逻辑动态返回状态码。这时可以注入@Res()装饰器：

@Post('login') async login(@Body() loginDto: LoginDto, @Res() res) { const user = await this.authService.validateUser(loginDto) if (!user) { return res.status(401).json({message: '认证失败'}) } return res.status(200).json(user) }

不过要注意，使用@Res()后会接管整个响应对象，NestJS的许多响应拦截特性将失效。所以除非必要，我建议尽量使用@HttpCode()。

5.3 自定义装饰器实战

当标准装饰器不能满足需求时，我们可以创建自定义装饰器。比如实现一个获取客户端IP的装饰器：

import { createParamDecorator } from '@nestjs/common' export const ClientIp = createParamDecorator((data, ctx) => { const request = ctx.switchToHttp().getRequest() return request.headers['x-forwarded-for'] || request.connection.remoteAddress }) // 使用 @Get('ip') getIp(@ClientIp() ip: string) { console.log(`客户端IP: ${ip}`) }

这个技巧在我做风控系统时特别有用，可以轻松获取各种客户端信息。自定义装饰器的可能性几乎是无限的，你可以根据业务需求创造各种便利工具。

6. 综合实战：用户管理API开发

现在我们把所有知识综合起来，开发一个完整的用户管理API。这个例子来自我的真实项目经验，包含了最常见的API开发场景。

6.1 用户CRUD接口实现

@Controller('users') export class UsersController { constructor(private readonly usersService: UsersService) {} @Get() @HttpCode(200) async listUsers(@Query() query: PaginationDto) { return this.usersService.findAll(query) } @Post() @HttpCode(201) async createUser(@Body() createUserDto: CreateUserDto) { return this.usersService.create(createUserDto) } @Get(':id') @HttpCode(200) async getUser(@Param('id') id: string) { return this.usersService.findOne(id) } @Patch(':id') @HttpCode(200) async updateUser( @Param('id') id: string, @Body() updateUserDto: UpdateUserDto ) { return this.usersService.update(id, updateUserDto) } @Delete(':id') @HttpCode(204) async deleteUser(@Param('id') id: string) { return this.usersService.remove(id) } }

6.2 复杂查询接口示例

实际项目中经常需要实现复杂查询，比如带过滤、排序和分页的用户列表：

class UserListQueryDto { @IsOptional() @IsString() name?: string @IsOptional() @IsInt() @Min(1) page?: number = 1 @IsOptional() @IsIn(['ASC', 'DESC']) order?: 'ASC' | 'DESC' = 'DESC' } @Get('complex-list') async complexList(@Query() query: UserListQueryDto) { // 实际项目中这里通常会调用service方法 return { data: [], pagination: { page: query.page, total: 100 } } }

这个例子展示了如何通过组合多个装饰器和DTO，构建出既健壮又易用的API接口。在我的实践中，这种模式极大地提高了代码的可维护性和开发效率。