EnlightenCode

qs 库完全指南 🚀 ​

qs 是一个功能强大的查询字符串解析和字符串化的 JavaScript 库。它能够帮助我们在对象和 URL 查询字符串之间进行转换。

📦 安装与使用 ​

bash
npm install qs

📝 注意：如果你使用 axios，无需单独安装，因为 axios 已经内置了 qs。

🛠️ 核心功能 ​

1. 基础操作 ​

qs.parse() - 解析查询字符串 ​

javascript
const qs = require('qs');
const url = 'user=alice&age=25&hobby=coding';
console.log(qs.parse(url));
// 输出: { user: 'alice', age: '25', hobby: 'coding' }

qs.stringify() - 序列化对象 ​

javascript
const obj = {
    user: 'alice',
    age: 25,
    hobby: 'coding'
};
console.log(qs.stringify(obj));
// 输出: 'user=alice&age=25&hobby=coding'

2. 🎯 数组处理 ​

javascript
// 1. 默认格式（indices）
qs.stringify({ colors: ['red', 'blue'] });
// 输出: 'colors[0]=red&colors[1]=blue'

// 2. brackets 格式
qs.stringify({ colors: ['red', 'blue'] }, { arrayFormat: 'brackets' });
// 输出: 'colors[]=red&colors[]=blue'

// 3. repeat 格式
qs.stringify({ colors: ['red', 'blue'] }, { arrayFormat: 'repeat' });
// 输出: 'colors=red&colors=blue'

// 4. comma 格式（新增）
qs.stringify({ colors: ['red', 'blue'] }, { arrayFormat: 'comma' });
// 输出: 'colors=red,blue'

3. 🔧 嵌套对象处理 ​

javascript
const nested = {
    user: {
        info: {
            name: 'alice',
            age: 25
        }
    }
};

// 默认方式
console.log(qs.stringify(nested));
// 输出: 'user[info][name]=alice&user[info][age]=25'

// 使用点符号
console.log(qs.stringify(nested, { allowDots: true }));
// 输出: 'user.info.name=alice&user.info.age=25'

💡 高级特性 ​

1. 自定义分隔符 ​

javascript
qs.stringify({ a: 1, b: 2 }, { delimiter: ';' });
// 输出: 'a=1;b=2'

2. 编码控制 ​

javascript
// 禁用编码
qs.stringify({ name: 'john doe' }, { encode: false });
// 输出: 'name=john doe'

// 自定义编码函数
qs.stringify({ name: 'john doe' }, {
    encoder: (str) => str.toUpperCase()
});
// 输出: 'name=JOHN DOE'

3. 空值处理 ​

javascript
const data = {
    name: 'alice',
    age: null,
    address: undefined
};

// 默认会忽略 undefined，保留 null
console.log(qs.stringify(data));
// 输出: 'name=alice&age='

// 严格模式
console.log(qs.stringify(data, { strictNullHandling: true }));
// 输出: 'name=alice&age&address='

⚠️ 注意事项 ​

  1. 在处理大型嵌套对象时要注意性能影响
  2. URL 长度限制：某些浏览器对 URL 长度有限制，使用 qs 生成长查询字符串时需要注意
  3. 特殊字符处理：默认会进行 URL 编码，如有特殊需求可以通过配置项调整

🔍 最佳实践 ​

javascript
// 推荐配置
const options = {
    arrayFormat: 'brackets',
    encode: true,
    allowDots: true,
    sort: (a, b) => a.localeCompare(b)
};

const data = {
    filters: ['active', 'verified'],
    user: {
        details: {
            name: 'alice',
            age: 25
        }
    }
};

console.log(qs.stringify(data, options));

这样的配置可以确保：

  • 数组使用方括号表示
  • 正确处理 URL 编码
  • 使用点符号表示嵌套对象
  • 参数按字母顺序排序，提高可读性