NestJS 11 中查询字符串数组解析问题的解决方案

问题背景

在 NestJS 11 版本中，开发者在使用查询字符串传递数组参数时遇到了一个意外的行为变化。当使用类似 http://localhost:3000?names[]=John&names[]=Doe 这样的 URL 时，解析后的结果会变成 { 'names[]': [ 'John', 'Doe' ] }，而不是预期的 { names: [ 'John', 'Doe' ] }。

技术分析

这个问题源于 NestJS 11 版本内部对解析中间件的调整。在之前的版本中，NestJS 使用了 body-parser 包来处理 URL 编码的数据，而在 11 版本中改用了 Express 内置的 express.urlencoded 方法。

关键变化点在于：

1. 默认的查询解析器从 extended 模式变为了 simple 模式
2. simple 模式会保留数组语法中的方括号作为键名的一部分
3. extended 模式则会自动去除方括号，提供更简洁的对象结构

解决方案

要恢复之前版本的行为，开发者需要显式地设置查询解析器为 extended 模式。具体实现方式如下：

import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  app.set('query parser', 'extended');
  await app.listen(3000);
}
bootstrap();

注意事项

1. 必须使用 NestExpressApplication 泛型来获取完整的 Express 应用实例方法
2. 此设置需要在应用启动前完成，通常放在 bootstrap 函数中
3. 如果应用同时使用 Fastify 或其他平台，需要相应调整

最佳实践建议

1. 对于新项目，建议统一使用 extended 模式以获得更一致的解析行为
2. 在升级 NestJS 版本时，应该测试所有涉及查询字符串数组的接口
3. 考虑在文档中明确记录接口期望的查询字符串格式
4. 对于复杂的查询参数，可以考虑使用 DTO 和验证管道来确保数据格式正确

总结

NestJS 11 版本的这一变化虽然微小，但对依赖查询字符串数组参数的接口影响较大。通过理解底层解析机制的变化，开发者可以轻松调整应用配置来保持向后兼容性。这也提醒我们在框架升级时需要仔细阅读变更日志，并对关键功能进行充分测试。