GET请求传递数组参数时的编码问题

Question

在Web开发中，使用GET请求传递数组参数时，常因编码方式不当导致后端无法正确解析。常见问题如：前端将数组`[1,2,3]`拼接为`ids=1,2,3`或重复键名`ids=1&ids=2&ids=3`，但未进行URL编码或格式不统一，导致后端接收时丢失数据或解析错误。特别是在中文或特殊字符场景下，若未对参数进行`encodeURIComponent`处理，易引发乱码或截断。此外，不同框架（如Spring、Express）对数组参数的默认解析规则不同，进一步加剧兼容性问题。如何规范编码格式并确保前后端协同，成为关键挑战。

Answer 1

1. 问题背景与常见现象

在Web开发中，使用GET请求传递数组参数是一个高频场景，例如分页查询、多选筛选、标签过滤等。然而，开发者常因编码方式不当导致后端无法正确解析参数。典型的错误包括：

• 将数组[1,2,3]直接拼接为ids=1,2,3，未进行URL编码，导致特殊字符（如空格、中文）被截断或转义异常。
• 采用重复键名形式ids=1&ids=2&ids=3，但未考虑后端框架的默认解析行为差异。
• 前端未调用encodeURIComponent处理含中文或符号的数组元素，引发乱码问题。

这些问题在跨团队协作或微服务架构中尤为突出，尤其当前后端由不同技术栈实现时，兼容性挑战加剧。

2. 深层原因分析

GET请求的参数最终以查询字符串（query string）形式附加在URL上，而URL对字符有严格限制。根据RFC 3986标准，以下字符必须被百分号编码：

字符类型	示例	是否需编码
空格		是 → %20
中文	张三	是 → %E5%BC%A0%E4%B8%89
逗号	,	否（但在某些上下文中建议编码）
方括号	[ ]	是 → %5B %5D

此外，不同后端框架对相同格式的解析逻辑存在分歧：

// Express.js (Node.js)
req.query.ids // 若为 ids=1&ids=2 → ['1','2']；若为 ids=1,2,3 → '1,2,3'

// Spring Boot (Java)
@RequestParam("ids") List<String> ids // 支持 comma-separated 或 multiple params

3. 主流编码模式对比

目前业界主要有三种数组传参方式，各有适用场景：

1. 逗号分隔法（comma-separated）：ids=1,2,3，简洁高效，适合数字和英文标识符。
2. 重复键名法（repeated keys）：ids=1&ids=2&ids=3，符合HTML表单提交规范，兼容性好。
3. 带索引的键名法（indexed notation）：ids[0]=1&ids[1]=2 或 ids[]=1&ids[]=2，结构清晰，便于嵌套数据传输。

选择哪种方式应基于后端框架的支持能力及团队约定。

4. 前端编码实践规范

为确保安全传输，前端必须对所有参数值执行encodeURIComponent。以下是一个健壮的数组序列化函数：

function serializeArrayParam(key, arr) {
  return arr.map(value => 
    `${key}=${encodeURIComponent(value)}`
  ).join('&');
}
// 示例：serializeArrayParam('tag', ['前端', 'JavaScript']) 
// 输出：tag=%E5%89%8D%E7%AB%AF&tag=JavaScript

对于复杂结构，可引入成熟库如qs.js进行统一处理：

import qs from 'qs';
const query = qs.stringify({ ids: [1,2,3], tags: ['web','中文'] }, { arrayFormat: 'repeat' });
// 结果：ids=1&ids=2&ids=3&tags=web&tags=%E4%B8%AD%E6%96%87

5. 后端解析策略适配

不同框架需配置相应解析规则以支持数组参数：

框架	默认行为	推荐配置
Express.js	多个同名参数自动转为数组	启用qs中间件以支持复杂格式
Spring Boot	支持List<T>自动绑定	使用@RequestParam并明确指定类型
Django	需手动提取getlist('ids')	避免依赖单值获取方法

6. 协同设计流程图

为保障前后端一致性，建议建立标准化沟通机制：

graph TD A[前端确定数组参数] --> B{是否含中文/特殊字符?} B -- 是 --> C[使用encodeURIComponent编码] B -- 否 --> D[选择传输格式: repeat/comma/indexed] C --> E[生成query string] D --> E E --> F[后端定义接收类型List/Array] F --> G[测试边界用例: 空值, 特殊字符, 长数组] G --> H[输出API文档并归档]