qs

qs

安全性的查询字符串解析和序列化字符串的库。

安装

npm i qs

使用

var qs = require('qs');
var assert = require('assert');
 
var obj = qs.parse('a=c');
assert.deepEqual(obj, { a: 'c' });
 
var str = qs.stringify(obj);
assert.equal(str, 'a=c');

1. 解析对象

qs.parse(string, [options])

• 查询字符串的时候，可以使用 [] 的方式创建嵌套对象。

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

• 解析URL编码
• 嵌套对象：foo[bar][baz]=foobarbaz

assert.deepEqual(qs.parse('foo[bar][baz]=foobarbaz'), {
    foo: {
        bar: {
            baz: 'foobarbaz'
        }
    }
});

• 解析对象时，最多解析深度为5层
• 可以传入一个depth参数覆盖默认值

qs.parse(string, [options])

• qs解析用户输入的时候，深度最好尽可能的小
• qs最多解析1000个参数
• 忽略查询字符串开头的？可以使用ignoreQueryPrefix

var prefixed = qs.parse('?a=b&c=d', { ignoreQueryPrefix: true });
assert.deepEqual(prefixed, { a: 'b', c: 'd' });

• 自定义的分隔符

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

• 分隔符也可以用正则表达式

var regexed = qs.parse('a=b;c=d,e=f', { delimiter: /[;,]/ });
assert.deepEqual(regexed, { a: 'b', c: 'd', e: 'f' });

• allowDots可以被用作点表示法

var withDots = qs.parse('a.b=c', { allowDots: true });
assert.deepEqual(withDots, { a: { b: 'c' } });

2、解析数组

• qs可以用[]解析数组

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

• 也可以指定数组的索引

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

• 注意：空字符串也是一个值，要保留

var withEmptyString = qs.parse('a[]=&a[]=b');
assert.deepEqual(withEmptyString, { a: ['', 'b'] });
 
var withIndexedEmptyString = qs.parse('a[0]=b&a[1]=&a[2]=c');
assert.deepEqual(withIndexedEmptyString, { a: ['b', '', 'c'] });

• qs会限制数组的最大索引为20，任何数组的成员的索引，如果大于20就会被转化为一个把索引作为键的对象

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

• arrayLimit选项可以覆盖默认限制

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

• 禁用字符串解析为数组，使用parseArrays：false

var noParsingArrays = qs.parse('a[]=b', { parseArrays: false });
assert.deepEqual(noParsingArrays, { a: { '0': 'b' } });

• 如果你想混合，qs将合并这两种为一个对象

var mixedNotation = qs.parse('a[0]=b&a[b]=c');
assert.deepEqual(mixedNotation, { a: { '0': 'b', b: 'c' } });

• 也可以创建对象的数组

var arraysOfObjects = qs.parse('a[][b]=c');
assert.deepEqual(arraysOfObjects, { a: [{ b: 'c' }] });

• 也用comma去连接一个数组，qs可以解析它

var arraysOfObjects = qs.parse('a=b,c', { comma: true })
assert.deepEqual(arraysOfObjects, { a: ['b', 'c'] })

3、序列化字符串

qs.stringify(object, [options]);

• 默认情况下，对象序列化后进行url编码后输出

assert.equal(qs.stringify({ a: 'b' }), 'a=b');
assert.equal(qs.stringify({ a: { b: 'c' } }), 'a%5Bb%5D=c');
Th

• 设置encode选项为false可以禁用url编码

var unencoded = qs.stringify({ a: { b: 'c' } }, { encode: false });
assert.equal(unencoded, 'a[b]=c');

• 设置encodeValuesOnly为true，禁用key进行url编码

var encodedValues = qs.stringify(
    { a: 'b', c: ['d', 'e=f'], f: [['g'], ['h']] },
    { encodeValuesOnly: true }
);
assert.equal(encodedValues,'a=b&c[0]=d&c[1]=e%3Df&f[0][0]=g&f[1][0]=h');

• 通过设置encoder自定义方法，可以取代enciding（注意：当encode被设置为false的时候，这个encoder不适用）

var encoded = qs.stringify({ a: { b: 'c' } }, { encoder: function (str) {
    // Passed in values `a`, `b`, `c`
    return // Return encoded string
}})

• 和encoder类似的还有decoder
• 当数组被解析时，默认是会显示索引

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

• 设置indices为false，可以不显示索引

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

• 设置arrayFormat选项指定数组的输出格式

qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'indices' })
// 'a[0]=b&a[1]=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'brackets' })
// 'a[]=b&a[]=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'repeat' })
// 'a=b&a=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'comma' })
// 'a=b,c'

• 对象序列化时，默认使用[]表示法

qs.stringify({ a: { b: { c: 'd', e: 'f' } } });
// 'a[b][c]=d&a[b][e]=f'

• 设置allowDots：true，修改为点表示法

qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { allowDots: true });
// 'a.b.c=d&a.b.e=f'

• 空字符和null的值会被省略，但=会保留

assert.equal(qs.stringify({ a: '' }), 'a=');

• 没有值的键将什么也不返回，如空对象或数组

assert.equal(qs.stringify({ a: [] }), '');
assert.equal(qs.stringify({ a: {} }), '');
assert.equal(qs.stringify({ a: [{}] }), '');
assert.equal(qs.stringify({ a: { b: []} }), '');
assert.equal(qs.stringify({ a: { b: {}} }), '');

• 值为undefined的会被完全忽略

assert.equal(qs.stringify({ a: null, b: undefined }), 'a=');

• addQueryPrefix设置为true可以在查询字符串前面加？

assert.equal(qs.stringify({ a: 'b', c: 'd' }, { addQueryPrefix: true }), '?a=b&c=d');

• 也可以设置分隔符

assert.equal(qs.stringify({ a: 'b', c: 'd' }, { delimiter: ';' }), 'a=b;c=d');

• 如果你只想序列化日期对象，你可以使用serializeDate选项

var date = new Date(7);
assert.equal(qs.stringify({ a: date }), 'a=1970-01-01T00:00:00.007Z'.replace(/:/g, '%3A'));
assert.equal(
    qs.stringify({ a: date }, { serializeDate: function (d) { return d.getTime(); } }),
    'a=7'
)

• 使用sort选项修改键的顺序

function alphabeticalSort(a, b) {
    return a.localeCompare(b);
}
assert.equal(qs.stringify({ a: 'c', z: 'y', b : 'f' }, { sort: alphabeticalSort }), 'a=c&b=f&z=y');

• filter选项可以过滤序列化的输出的键。filter传递一个函数时，每个键调用一次该函数并用返回的值替换原来的值；如果filter传递一个数组时，将用于选择对象的key和数组的索引。

function filterFunc(prefix, value) {
    if (prefix == 'b') {
        // Return an `undefined` value to omit a property.
        return;
    }
    if (prefix == 'e[f]') {
        return value.getTime();
    }
    if (prefix == 'e[g][0]') {
        return value * 2;
    }
    return value;
}
qs.stringify({ a: 'b', c: 'd', e: { f: new Date(123), g: [2] } }, { filter: filterFunc });
// 'a=b&c=d&e[f]=123&e[g][0]=4'
qs.stringify({ a: 'b', c: 'd', e: 'f' }, { filter: ['a', 'e'] });
// 'a=b&e=f'
qs.stringify({ a: ['b', 'c', 'd'], e: 'f' }, { filter: ['a', 0, 2] });
// 'a[0]=b&a[2]=d'

4、处理null值

• 默认，null值被认为一个空字符串

var withNull = qs.stringify({ a: null, b: '' });
assert.equal(withNull, 'a=&b=');

• 解析字符串时，不区分参数有没有等号，没有值的话，都会被解析为空字符串

var equalsInsensitive = qs.parse('a&b=');
assert.deepEqual(equalsInsensitive, { a: '', b: '' });

• 使用strictNullHandling来区分null和空字符，序列化的null值没有=号

var strictNull = qs.stringify({ a: null, b: '' }, { strictNullHandling: true });
assert.equal(strictNull, 'a&b=');

• 可以使用strictNullHandling，来解析不带=号的值返回null

var parsedStrictNull = qs.parse('a&b=', { strictNullHandling: true });
assert.deepEqual(parsedStrictNull, { a: null, b: '' });

• 使用skipNulls可以完全跳过值为null的键不进行解析

var nullsSkipped = qs.stringify({ a: 'b', c: null}, { skipNulls: true });
assert.equal(nullsSkipped, 'a=b');