小满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) { // 获取?page1中的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 处理特殊类型参数对于数组参数需要特别注意// 前端传参?ids1,2,3 Get(detail) getDetails(Query(ids) ids: string) { // ids是字符串1,2,3 const idArray ids.split(,) }更优雅的写法是使用class-transformerimport { 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对象 }但这种写法没有任何类型校验实际项目中我们应该定义明确的DTOclass CreateUserDto { username: string password: string age?: number // 可选参数 } Post(create) createUser(Body() createUserDto: CreateUserDto) { // 现在createUserDto有完整的类型提示 }3.2 结合class-validator做数据校验光有类型还不够我们还需要数据校验。NestJS完美支持class-validatorimport { 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/:idGet(: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: Recordstring, string) { // headers对象包含所有请求头 }在实际项目中我常用这种方式获取客户端信息、认证token等。比如移动端API可能需要区分iOS和AndroidGet(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接口。在我的实践中这种模式极大地提高了代码的可维护性和开发效率。