Rust查询字符串处理库querystring的使用指南

querystring是Rust中一个轻量级但功能强大的库，专门用于解析和构建URL查询参数。它提供了简单直观的API来处理URL中的查询字符串部分。

安装

在Cargo.toml中添加依赖：

[dependencies]
querystring = "1.0"

基本用法

解析查询字符串

use querystring::{parse, QueryPair};

let query = "name=John&age=30&city=New+York";
let parsed: Vec<QueryPair> = parse(query).collect();

for pair in parsed {
    println!("Key: {}, Value: {}", pair.key, pair.value);
}
// 输出:
// Key: name, Value: John
// Key: age, Value: 30
// Key: city, Value: New York

构建查询字符串

use querystring::stringify;

let params = vec![
    ("name", "John Doe"),
    ("age", "25"),
    ("city", "San Francisco"),
];

let query_string = stringify(¶ms);
println!("{}", query_string); 
// 输出: name=John+Doe&age=25&city=San+Francisco

高级功能

处理重复键

use querystring::{parse, QueryPair};

let query = "color=red&color=green&color=blue";
let parsed: Vec<QueryPair> = parse(query).collect();

let colors: Vec<_> = parsed.iter()
    .filter(|p| p.key == "color")
    .map(|p| p.value)
    .collect();

println!("{:?}", colors); // 输出: ["red", "green", "blue"]

自定义分隔符

use querystring::{parse_with_config, QueryParseConfig};

let config = QueryParseConfig::new().pair_delimiter(';');
let query = "name=John;age=30;city=New+York";
let parsed: Vec<QueryPair> = parse_with_config(query, config).collect();

for pair in parsed {
    println!("{}: {}", pair.key, pair.value);
}

处理复杂数据结构

use querystring::{stringify, stringify_with_config, QueryStringifyConfig};

let params = vec![
    ("user[name]", "Alice"),
    ("user[age]", "28"),
    ("user[address][city]", "Boston"),
    ("user[address][zip]", "02108"),
];

// 默认方式
println!("{}", stringify(¶ms));

// 使用自定义配置
let config = QueryStringifyConfig::new()
    .array_format(querystring::ArrayFormat::Bracket);
println!("{}", stringify_with_config(¶ms, config));

错误处理

use querystring::{parse, ParseError};

let query = "name=John&age=thirty"; // 假设我们需要年龄是数字

match parse(query).collect::<Result<Vec<_>, _>>() {
    Ok(pairs) => {
        // 处理解析成功的键值对
    },
    Err(ParseError::InvalidEncoding) => {
        eprintln!("查询字符串包含无效的编码");
    },
    Err(ParseError::MalformedPair) => {
        eprintln!("查询字符串包含格式错误的键值对");
    }
}

完整示例demo

use querystring::{parse, stringify, parse_with_config, stringify_with_config, 
                 QueryParseConfig, QueryStringifyConfig, QueryPair, ParseError};

fn main() {
    // 基本解析示例
    println!("=== 基本解析示例 ===");
    let query = "name=John&age=30&city=New+York";
    let parsed: Vec<QueryPair> = parse(query).collect();
    for pair in parsed {
        println!("Key: {}, Value: {}", pair.key, pair.value);
    }

    // 基本构建示例
    println!("\n=== 基本构建示例 ===");
    let params = vec![
        ("name", "John Doe"),
        ("age", "25"),
        ("city", "San Francisco"),
    ];
    let query_string = stringify(¶ms);
    println!("构建的查询字符串: {}", query_string);

    // 处理重复键
    println!("\n=== 处理重复键示例 ===");
    let query = "color=red&color=green&color=blue";
    let parsed: Vec<QueryPair> = parse(query).collect();
    let colors: Vec<_> = parsed.iter()
        .filter(|p| p.key == "color")
        .map(|p| p.value)
        .collect();
    println!("所有颜色: {:?}", colors);

    // 自定义分隔符
    println!("\n=== 自定义分隔符示例 ===");
    let config = QueryParseConfig::new().pair_delimiter(';');
    let query = "name=John;age=30;city=New+York";
    let parsed: Vec<QueryPair> = parse_with_config(query, config).collect();
    for pair in parsed {
        println!("{}: {}", pair.key, pair.value);
    }

    // 复杂数据结构
    println!("\n=== 复杂数据结构示例 ===");
    let params = vec![
        ("user[name]", "Alice"),
        ("user[age]", "28"),
        ("user[address][city]", "Boston"),
        ("user[address][zip]", "02108"),
    ];
    println!("默认方式: {}", stringify(¶ms));
    let config = QueryStringifyConfig::new()
        .array_format(querystring::ArrayFormat::Bracket);
    println!("自定义配置方式: {}", stringify_with_config(¶ms, config));

    // 错误处理
    println!("\n=== 错误处理示例 ===");
    let query = "name=John&age=thirty";
    match parse(query).collect::<Result<Vec<_>, _>>() {
        Ok(pairs) => {
            println!("解析成功: {:?}", pairs);
        },
        Err(ParseError::InvalidEncoding) => {
            eprintln!("错误: 查询字符串包含无效的编码");
        },
        Err(ParseError::MalformedPair) => {
            eprintln!("错误: 查询字符串包含格式错误的键值对");
        }
    }
}

性能考虑

querystring库在设计时考虑了性能：

1. 零拷贝解析：尽可能避免分配新内存
2. 惰性解析：只在需要时处理查询字符串部分
3. 最小化分配：构建查询字符串时预计算所需空间

对于需要处理大量查询字符串的高性能应用，querystring是一个很好的选择。

替代方案比较

虽然Rust标准库和某些web框架提供了查询字符串处理功能，但querystring有以下优势：

• 更完整的RFC 3986合规性
• 更灵活的配置选项
• 更清晰的错误处理
• 更专注于查询字符串这一特定任务

总结

querystring库为Rust中的URL查询参数处理提供了简单而强大的解决方案。无论是解析现有查询字符串还是构建新的查询字符串，它都能提供高效且符合标准的方法。