背景

Web 项目中经常会遇到处理 URLQuery 的情况，处理方式众多，在项目中也发现有 qs、query-string、URLSearchParams 等多种方式来处理 query，真是老鼠老虎傻傻分不清楚。

于是梳理一下关于URL编码的相关知识点，用来去伪解惑。

URL QueryString

首先介绍下 QueryString 的基本概念，这是一切问题的开始。下面是 wiki 的描述：

A query string is a part of a uniform resource locator (URL) that assigns values to specified parameters.

通常的理解就是 URL 中 ? 后面的部分，其设计最初是用做 HTML form 提交时的数据传参。

基本结构

下面我们看下 query 的基本结构 field1=value1&field2=value2&field3=value3...

包含了如下标准：

1. Query string 由一组键值对(feild-value)组成；
2. 每组键值对的 feild 和 value 用=分割；
3. 每组数据用&分割；

补充个冷知识：除了使用&分割每对数据外，W3C 曾在 1999版 建议所有 Web 服务器同时支持分号;分割符

We recommend that HTTP server implementors, and in particular, CGI implementors support the use of ";" in place of "&" to save authors the trouble of escaping "&" characters in this manner.

但在 2014 年以来，就只建议使用 & 作为分隔符了。也就目前我们用到的方式。

1. 允许多个value被关联到同一个field上。但 field 如何取值，并无明确的处理标准；

例如：field=a&field=b，关于 field 的值应该是 a、b、['a', 'b']、'a, b' 并无任何权威解释。 关于处理标准这点实在令人出乎意料。通常这类情况会按照数组的方式处理，即 field 值为 ['a', 'b']，但这仅是不同的框架的决定了如何实现而已。 关于这个问题可以前往这里查看

数据编码

接下来我们看下数据是如何在 query 中传输的。 由于某些字符集(如中文)和在 URL 中有特殊含义的字符(如 空格、%、&、=、?、# 等)无法直接使用在 querystring 中，因此使用了一种叫做「百分号编码」的方式先将这类特殊字符进行编码后，再进行传输。

具体规则如下：

• 对保留字符进行编码，具体对应如下

!	#	$	&	'	(	)	*	+	,	/	:	;	=	?	@	[	]
%21	%23	%24	%26	%27	%28	%29	%2A	%2B	%2C	%2F	%3A	%3B	%3D	%3F	%40	%5B	%5D

• 非保留字符不进行编码。[A-Z]、[a-z]、[0-9]、- 、_、.、~
• %百分号编码为%25
• 空格编码为+或%20
• 其余字符数据使用某种编码方式转换为字节流，再用百分号编码%HH方式表示； 这里需要注意的是，由于早期规范中未明确应使用何种编码，所以会导致如果不明确说明使用何种编码，数据的解析会有歧义。因此在2005年发布的 RFC 3986 建议是先转成 UTF-8 编码，再对每个字节进行%HH的编码。

注意：这里字符数据的编码不一定就是 UTF-8 格式的，使用 from 表单方式时，具体编码会根据 meta 头的 charset 的选择！

当然上述只是标准，实践中 JS 内置了使用 UTF-8 编码的 encodeURIComponent 函数，大大简化的编码过程。

关于指定编码，这里有个有趣的事情：

在使用百度时，你会发现 url 中有个 ie 参数，其实含义就是 Input Encoding（对，不是 IE 浏览器），目的就是指定关键词 wd 的编码格式。曾默认是 gb2312（因为当时很多网站还使用 gb2312 编码），当然现在已经默认成 utf-8 。（不过百度结果里依然有不少文章还在说 ie 的默认是是 gb2312 😂）

可以用 www.baidu.com/s?wd=%E4%B8… 和 www.baidu.com/s?wd=%E4%B8… 来感受下他们的差异吧~

编码实践

这一节我们挑重点的对比下老虎(qs)、老鼠(query-string)的差异，避免开发时傻傻分不清楚。

瑞士军刀 qs

github

A querystring parsing and stringifying library with some added security.

官方介绍很简单：一个增加了安全性的 querystring 解析和序列化的函数库

.parse(string, [options])

1. 对于简单 querystring，可以进行常规的转换，同时会对 field 和 value 进行 decode，例如：

qs.parse('a=c&b%201=d%26e');
// { a: 'c', 'b 1': 'd&e' }

qs不会忽略头部的 ?，需要自行去掉，否则会当做 key 的一部分，例如：?a=b => { '?a': 'b' }

1. 支持 querystring 中的嵌套对象

qs.parse('foo[bar]=baz');
// { foo: { bar: 'baz' } }

但默认子元素最多嵌套 5 层，需要通过 parse(string, [options]) 的 opinion.depth 来指定。 （注意埋坑 * 1）

// defalut
qs.parse('a[b][c][d][e][f][g][h][i]=j');

{a: {b: {c: {d: {e: {f: {'[g][h][i]': 'j'}}}}}}}

// set depth
qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1 });
{ a: { b: { '[c][d][e][f][g][h][i]': 'j' } } }

1. 支持自定义除&以外的分隔符

var delimited = qs.parse('a=b;c=d', { delimiter: ';' });
// { a: 'b', c: 'd' };

这点符合 W3C 对;支持的建议，但大部分情况应该不会用到。

1. 支持各种 array 的解析，使用 [] 作为数组标识

var withArray = qs.parse('a[]=b&a[]=c');
// { a: ['b', 'c'] };

同时也支持指定数组指定索引

var withIndexes = qs.parse('a[1]=c&a[0]=b');
// { a: ['b', 'c'] };

并行支持 allowSparse 获取抽稀形式的数组

var sparseArray = qs.parse('a[1]=2&a[3]=5', { allowSparse: true });
// { a: [, '2', , '5'] };

但是默认指定的 index 最大值为 20，如果超过最大值，则按照 object 形式解析；使用 arrayLimit控制最大值 （注意埋坑 * 2）

var withMaxIndex = qs.parse('a[100]=b');
// { a: { '100': 'b' } }

var withArrayLimit = qs.parse('a[1]=b', { arrayLimit: 0 });
// { a: { '1': 'b' } }

.stringify(object, [options])

这里主要介绍下数组类型的 query，默认会对 field 和 value 都进行编码，同时会使用[]作为数据的标识（且默认对[]进行编码），需指定 encodeValuesOnly: true才仅对 value 编码。

qs.stringify({key: ['a', 'b']});
// key%5B0%5D=a&key%5B1%5D=b

qs.stringify({key: ['a', 'b']}, { encodeValuesOnly: true });
// key[0]=a&key[1]=b

去掉[]标识，可使用 { indices: false }

qs.stringify({key: ['a', 'b']}, { indices: false });
// key=a&key=b

支持配置 charset

默认使用 UTF-8，内置了 iso-8859-1，也可以支持 encoder 扩展。

而接下来的库仅支持 UTF-8 的编码方式。

简洁专注 query-string

github

Parse and stringify URL query strings

For browser usage, this package targets the latest version of Chrome, Firefox, and Safari.

官方名字看起来，依旧是处理 URL querystring 的。 同时还贴心友(wei)情(xian)提示，各位同学不要看走眼

Not npm install querystring !!!!!

.parse(string, [options])

头部的?和#的部分将被忽略，因此可以直接将 location.search 和 location.hash 传入。

1. 基本的解析和 qs 一样，会对 field 和 value 进行 decode。

queryString.parse('a=c&b%201=d%26e');

// { a: 'c', 'b 1': 'd&e' }

1. 不支持嵌套，官方建议可以使用 JSON 序列化的方式传值

This module intentionally doesn't support nesting as it's not spec'd and varies between implementations, which causes a lot of edge cases.

You're much better off just converting the object to a JSON string:

1. query 中多个相同 field 的解析，默认不支持[]形式，需要指定 { arrayFormat: 'bracket' }

queryString.parse('key=a&key=b');
// { key: ['a', 'b'] };

queryString.parse('key[]=a&key[]=b');
// { 'key[]': ['a', 'b'] };

queryString.parse('key[]=a&key[]=b', { arrayFormat: 'bracket' });
// { key: ['a', 'b'] };

当然 query-string 也支持索引的方式标记的数组，{arrayFormat: 'index'}

queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'});
// { foo: ['1', '2', '3'] }

.stringify(object, [options])

对于数组类型，默认不使用[]标识。这点和qs是相反的，需要特别注意！

queryString.stringify({key: ['a', 'b']});
// key=a&key=b

需要[]的话，使用 {arrayFormat: 'bracket'}开启，默认[]也不会被 encode

queryString.stringify({key: ['a', 'b']}, {arrayFormat: 'bracket'});
// key[]=a&key[]=b

历史废弃 querystring

The querystring API is considered Legacy. New code should use the URLSearchParams API instead.

曾经为 nodejs 解析 querystring 的 API，目前已经废弃，官方推荐URLSearchaParms代替。 这里主要提一点：不支持嵌套对象的解析。

血统纯正 URL / URLSearchParams

URL 和 URLSearchParams 是 URL API规范 中的两个标准的接口。其提供了访问、操作 URL 的 API。 URL 定义了像域名、主机和 IP 地址等概念， URLSearchParams 定义了一些常用的方法来处理 QueryString。

URLSearchParams

两种方式创建 URLSearchParams 对象，URLSearchParams构造函数会忽略 search 中的?

const url = new URL('https://www.baidu.com/path/v1?key=a&key=b%26c');
const search1 = url.searchParams;

const search2 = new URLSearchParams(location.search);

.get(name)

获取的值已 decode，如果 name 不存在返回 null，如果值不存在返回空字符串

const search = new URLSearchParams('key=b%26c&key2');
search.get('key'); // b&c
search.get('key2'); // ''

.getAll(name)

需要特别注意，如果 key 有多个值，get() 只能获取第一个值。获取全部需要使用 getAll()，该函数返回数组

const search = new URLSearchParams('key=a&key=b');
search.get('key'); // a
search.getAll('key'); // ['a', 'b']

.set(key, string) / .append(name, string)

set 会覆盖原有值。如果添加重复的 name，需要使用 append()。 set 和 append 仅支持 string 类型的 value。同时 key 和 value 都会被 encode，无需额外处理了。

const search = new URLSearchParams();
search.append('key', 'a');
search.append('key', 'b');
search.toString(); // key=a&key=b

.keys()

返回一个 IterableIterator迭代器，可以使用for...of遍历。需要注意，重复的 key 会出现多次

const search = new URLSearchParams('key=a&key=b');
for (const key of search.keys()) {
  console.log(key);
}
// key
// key

.toString()

获取的 QueryString，会被 encode 处理。空格转成+。对于重复 key，使用了 key=a&key=b 的方式展示。

const search = new URLSearchParams();
search.set('key', '?&=')
search.set('key2', 'a b');
search.toString(); // key=%3F%26%3D&&key2=a+b

兼容

关于兼容，目前浏览器占比基本上没有问题。实际开发中遇到 iOS10 以下不兼容的情况，使用 polyfill 即可。

总结对比

从上面的总结来看，我们发现 qs 和 query-string / URLSearchParams 最大的差异在于对于多层嵌套对象（Nested object）的支持与否。

• qs被设计用于解析x-www-form-urlencoded数据，拥有强大的序列化能力，可以处理复杂的类JSON数据。
• query-string 和 URLSearchParams 则使用简单的序列化算法，适合常规的 web 浏览器数据传输，适合处理平面数据结构(flat data)。
• 对于平面数据，这几个库的效果是一样的。

在实际业务中使用复杂的 JSON 数据结构时，我们通常会使用JSON.stringify() 方法先将数据进行序列化（也称字符串化），将复杂数据转换成基本的字符串数据后，再进行传输。 另外如果有特殊编码需求，除qs外都仅支持 utf-8 的编码。

因此通常情况下，解析 URL 中的 query 内容，使用 URLSearchParams （代替 query-string ） 就足够了。

当然了解了他们差异后，选择哪种方式就要根据你的实际情况而定了。

延伸话题

整理资料过程中，引申出更多有趣的问题，也稍作整理。

空格编码问题

还记得前面提到的编码规则里， 空格的编码可以是 + 或者%20，这里描述的就很模糊。

我们先来看下上面不同 API 是如何处理的？

qs

parse 解析识别 + 和 %20

qs.parse('a+b=c%20d'); // { 'a b': 'c d' }

stringify 序列化转成 %20

qs.stringify({ 'a b': 'c d' }); // 'a%20b=c%20d'

query-string

parse 解析识别 + 和 %20

queryString.parse('a+b=c%20d'); // { 'a b': 'c d' }

stringify 序列化转成 %20

queryString.stringify({ 'a b': 'c d' }); // 'a%20b=c%20d'

URL

解析识别 + 和 %20

u = new URL('http://host/p?k=a b+c%20d');
u.searchParams.get('k');
// a b c d

序列化 空格转成 %20，+ 保持不变

u = new URL('http://host/p t?k=a b+c%20d');
u.toString();
// /p%20t?k=a%20b+c%20d

URLSearchParams

解析识别 + 和 %20

search = new URLSearchParams('a+b=c%20d');
search.get('a b'); 
// 'c d'

序列化成 +

search = new URLSearchParams('k=a b+c%20d');
search.toString();
// k=a+b+c+d
search.set('a b', 'c d');
// 'a+b=c+d'

对+和%20的识别都没问题（毕竟兼容还是能做到的），但是转换空格URLSearchParams就有不同的逻辑了。至于为什么会有两种编码结果？

这里要特别说明的是URLSearchParams采用了 application/x-www-form-urlencoded 编码模式，而这个编码采用了一个非常早期（RFC 1738）的通用的URI百分号编码方法——就是将 空格转换为+。

至于为什么 URLSearchParams会采用 *application/x-www-form-urlencoded*编码，我猜想是因为要考虑到历史兼容问题——生成的 URL 需要被仅支持+的程序识别。当然+已经不推荐了，在 RFC 3986 中已推荐使用%20。

特别说明

这里特别说明下 decodeURIComponent，是无法解析 + 成 空格，因此实际处理过程中，如果无法保证空格的编码方式，还是使用URLSearchParams或者query-string来解析数据吧。

decodeURIComponent('a+%20b');
// a+ b

encodeURIComponent('a b');
// a%20b

扩展参考

URLSearchParams中 +的问题，具体细节可参考 whatwg 的描述：

As a URLSearchParams object uses the application/x-www-form-urlencoded format underneath there are some difference with how it encodes certain code points compared to a URL object (including href and search ). This can be especially surprising when using searchParams to operate on a URL ’s query .

和 whatwg 中关于 application/x-www-form-urlencoded的描述

1. Control names and values are escaped. Space characters are replaced by +', and then reserved characters are escaped as described in [[RFC1738]](https://www.w3.org/TR/html4/references.html#ref-RFC1738), section 2.2: Non-alphanumeric characters are replaced by %HH', a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks are represented as "CR LF" pairs (i.e., `%0D%0A').

Content-type 中的 x-www-form-urlencoded

当我们在HTTP中使用 MIME 类型为x-www-form-urlencoded格式提交数据时，所使用的就是前文所介绍的编码方式。

只是如果发送的是 GET 请求，数据会拼接在 Query 中；而发送 POST 请求则会将数据放置在消息体（body）中，通过Header中的Content-Type 来指定 MIME 类型。

至于 x-www-form-urlencoded 的局限性： 通常有二进制数据时，urlencoded使用百分号%HH和UTF-8的编码方式，会大大增加了数据的长度。为了节省传输数据的空间，会选择form-data代替。

参考资料

• en.wikipedia.org/wiki/Query_…
• en.wikipedia.org/wiki/Percen…
• url.spec.whatwg.org/#interface-…
• datatracker.ietf.org/doc/html/rf…
• datatracker.ietf.org/doc/html/rf…
• www.w3.org/Internation…
• www.w3.org/TR/html4/in…
• stackoverflow.com/questions/2…
• stackoverflow.com/questions/1…
• www.baeldung.com/postman-for…