Qs 和 Querystring：解析和格式化 URL query 字符串的工具库

今天介绍两个库 qs、querystring，但是作用一样，都是用来解析和格式化 URL query 字符串（URL query string）的工具库。

背景

在学习 express 的中间件 body-parser 的文档[1]时，bodyParser.urlencoded([options]) 的 options 参数有一个 extended 参数，是个布尔值。

// parse application/x-www-form-urlencoded
app.use(bodyParser.urlencoded({ extended: false }))

// parse application/x-www-form-urlencoded
app.use(bodyParser.urlencoded({ extended: true }))

extended 控制 body-parser 内部在解析  URL query 字符串时，内部使用哪个工具库：

• 为 false 时，body-parser 内部使用的是 querystring（只支持单层对象和数组的解析）
• 为 true 时，body-parser 内部使用的是 qs（能支持嵌套对象和数组的解析）

extended 默认值虽然为 true，但这个默认值已被弃用了。我们需要学习 qs 和 querystring 之间的区别并选择适当的进行设置。

我们下面就分别来学习。

querystring

querystring 开始是一个三方工具库，后面内置到了 Node.js 中[2]，querystring 支持单层对象和数组的解析和格式化

你可以通过下列方式引用 querystring：

const querystring = require('node:querystring');

querystring 提供的核心方法就 2 个：.parse() 和 .stringify() 有点类似与 JSON.parse()/JSON.stringify()。

querystring.parse()

.parse() 用来将 URL query 字符串转换成对象和数组。

const querystring = require('node:querystring'); 

querystring.parse('foo=bar&abc=xyz') // { foo: 'bar', abc: 'xyz'  }

URL query 字符串中，键值对采用 = 连接，每个键值对之间采用 & 连接。

如果 URL query 字符串包含一样的键名，那么会作为数组解析。

const querystring = require('node:querystring'); 

querystring.parse('foo=bar&abc=xyz&abc=123')
/*
{
  "foo": "bar",
  "abc": ["xyz", "123"]
}
*/

.parse() 方法的完整语法是：querystring.parse(str[, sep[, eq[, options]]]) 。

• 第 2 个参数 sep 用于控制键值对之间的间隔，默认值 '&'
• 第 3 个参数 eq 用于控制键值之间的间隔，默认值 '='

const querystring = require('node:querystring'); 

querystring.parse('foo:bar;abc:xyz;abc:123', ';', ':')
/*
{
  "foo": "bar",
  "abc": ["xyz", "123"]
}
*/

querystring.stringify()

.stringify() 用来将对象或数组转换成 URL query 字符串，是 .parse() 方法的逆向操作。

querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' });
// Returns 'foo=bar&baz=qux&baz=quux&corge='

.stringify() 方法的完整语法是：querystring.stringify(obj[, sep[, eq[, options]]])。

• 第 2 个参数 sep 用于控制键值对之间的间隔，默认值 '&'
• 第 3 个参数 eq 用于控制键值之间的间隔，默认值 '='

querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' }, ';', ':');
// Returns 'foo:bar;baz:qux;baz:quux;corge:'

qs

qs[3] 是对 querystring 工具库的扩展，能支持嵌套对象和数组的解析和格式化。

qs.parse()

.parse() 用来将 URL query 字符串转换成对象和数组·。

var qs = require('qs');

qs.parse('foo=bar&abc=xyz') // { foo: 'bar', abc: 'xyz'  }

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

可以发现，qs.parse() 对数组的解析是兼容 querystring.parse() 的，还可以在键中使用 [] 指定显式指定是数组。

此外，qs.parse() 还支持嵌套对象的解析。

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

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

键部分，[nestedProp] 中的 nestdProp 会被看作嵌套属性解析。

不过为了减少这个功能的滥用，qs.parse() 默认设置了 5 层的深度限制，可以通过 depth option 重置。

qs.parse('a[b][c][d][e][f][g][h][i]=j')
/*
{
    a: {
        b: {
            c: {
                d: {
                    e: {
                        f: {
                            '[g][h][i]': 'j'
                        }
                    }
                }
            }
        }
    }
}
*/

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

qs 嵌套属性语法跟数组语法是重复的。数组中的索引和对象中的键之间的唯一区别是括号之间的值必须是数字才能创建数组，否则就是对象。

qs.parse('a[1]=c&a[0]=b') // { a: ['b', 'c'] }
qs.parse('foo[bar]=baz') // { foo: { bar: 'baz' } }

不过为了减少这个功能的滥用，qs.parse() 默认将数组中指定的索引值限制到最大 20 ，任何索引大于 20 的索引都会作为对象属性使用。可以通过 arrayLimit option 重置。

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

qs.stringify()

qs.stringify() 用来将对象或数组转换成 URL query 字符串，是 qs.parse() 方法的逆向操作。

qs.stringify({ a: 'b' }) // 'a=b'
qs.stringify({ a: { b: 'c' } }) // 'a%5Bb%5D=c'

字符串化时，qs 默认对 URI 进行编码输出。当然，也可以通过指定 encode option 设置成 false 指定不用编码。

qs.stringify({ a: { b: 'c' } }, { encode: false }) // a[b]=c

还有字符串化数组。

qs.stringify({ a: ['b', 'c', 'd'] }) 
// 'a[0]=b&a[1]=c&a[2]=d'

注意，这里跟 querystring.stringify() 不同的是，数组默认会赋予索引标识（[]），可以通过将 indices option 设置为 false 来覆盖此设置。

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

delimiter 选项参数

qs.stringify()/qs.parse() 还支持通过 delimiter 选项参数自定义键值对分隔符。

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

不过，目前并不支持自定义键值之间的分隔符。

总结

本文介绍了两个库：qs 和 querystring。他们作用是一样的，都是用来解析和格式化 URL query 字符串的工具库。

qs 是对 querystring 工具库的扩展。querystring 支持单层对象和数组的解析和格式化；而 qs 则能支持嵌套对象和数组的解析和格式化。如果 URL query 字符串不是那种嵌套结构，那么使用 Node.js 内置的 querystring 模块就够了。

对应到 express 的 body-parser 中间件的使用，那就是在调用 bodyParser.urlencoded() 时，extended 选项设置成 false 就够了。

// express v4.16.0 之前
// ===

var express = require('express')
var bodyParser = require('body-parser')

var app = express()

// create application/x-www-form-urlencoded parser
var urlencodedParser = bodyParser.urlencoded({ extended: false })

// POST /login gets urlencoded bodies
app.post('/login', urlencodedParser, function (req, res) {
  res.send('welcome, ' + req.body.username)
})

// express v4.16.0 之后（包含）
// ===

var express = require('express')

var app = express()

// create application/x-www-form-urlencoded parser
var urlencodedParser = express.urlencoded({ extended: false })

// POST /login gets urlencoded bodies
app.post('/login', urlencodedParser, function (req, res) {
  res.send('welcome, ' + req.body.username)
})

希望本文内容对你有所帮助，感谢阅读，Happing Coding！

参考资料

[1]body-parser 的文档:https://www.npmjs.com/package/body-parser#body-parser

[2]内置到了 Node.js 中:https://nodejs.org/api/querystring.html

[3]qs:https://www.npmjs.com/package/qs