Axios如何处理列表与「展开式（exploded）」查询字符串参数？

首先明确：Axios确实内置了处理数组查询参数的灵活方式，它默认依赖qs库来序列化params，我们可以通过配置paramsSerializer来控制数组的序列化格式，完全不需要手动拼接URL或者预解析数组，也能完美区分「逗号列表式」和「展开式」两种格式。

一、实现逗号分隔的列表式格式（key=value1,value2） #

如果你需要将数组序列化为逗号分隔的字符串，可以利用qs的arrayFormat: 'comma'选项。在Axios请求中配置paramsSerializer即可：

axios.get('whatever.com', {
  params: { key: ['value1', 'value2'] },
  paramsSerializer: {
    serialize: (params) => {
      return qs.stringify(params, { arrayFormat: 'comma' });
    }
  }
});

这样生成的URL就是whatever.com?key=value1,value2。不过正如你担心的，如果数组元素本身包含逗号，这种方式会导致后端解析错误，所以这种格式只适合确定元素不含逗号的场景。

二、实现展开式格式（key=value1&key=value2） #

这是更安全的格式，即使元素包含特殊字符也能正确解析。Axios同样支持通过qs的配置来实现，不需要手动拼接URL：

axios.get('whatever.com', {
  params: { key: ['value1', 'value2'] },
  paramsSerializer: {
    serialize: (params) => {
      return qs.stringify(params, { arrayFormat: 'repeat' });
    }
  }
});

此时生成的URL就是whatever.com?key=value1&key=value2，而且你依然可以正常通过params属性传递数组，完全不会破坏现有的工具链——因为qs会帮你将数组序列化为重复的键值对，Axios会正确处理这个序列化后的字符串。

三、全局配置（避免重复写配置） #

如果你的项目中大量请求需要统一的数组序列化规则，可以直接配置Axios全局实例：

const axiosInstance = axios.create({
  paramsSerializer: {
    serialize: (params) => qs.stringify(params, { arrayFormat: 'repeat' }) // 全局用展开式
  }
});

// 后续请求直接用这个实例
axiosInstance.get('whatever.com', { params: { key: ['v1', 'v2'] } });

四、关键注意点与建议 #

• 关于qs依赖：Axios已经内置了qs，不需要额外安装，直接在代码中使用即可。
• 格式选择：优先使用展开式（repeat），因为它能兼容所有场景，包括元素含特殊字符的情况；只有在后端明确要求逗号分隔格式，且能保证元素不含逗号时，才选择逗号列表式。
• 自定义序列化逻辑：如果有特殊的序列化需求，还可以完全自定义paramsSerializer的函数，比如针对特定字段单独处理格式。

内容的提问来源于stack exchange，提问作者Sasha