Rust URL处理库deno_url的使用指南

介绍

deno_url是Rust中一个高效且符合标准的URL解析和操作库，它源自Deno项目的URL处理实现。这个库提供了符合WHATWG URL标准的解析功能，支持各种URL操作，包括解析、序列化、修改URL各部分等。

主要特性

• 符合WHATWG URL标准
• 高性能解析
• 支持相对URL解析
• 完整的URL组成部分访问和修改
• 支持IDNA(国际化域名)
• 严格的错误处理

使用方法

首先在Cargo.toml中添加依赖：

[dependencies]
deno_url = "0.4"

基本URL解析

use deno_url::Url;

fn main() {
    let url = Url::parse("https://www.example.com/path?query=123#fragment").unwrap();
    
    println!("Scheme: {}", url.scheme());
    println!("Host: {}", url.host_str().unwrap());
    println!("Path: {}", url.path());
    println!("Query: {:?}", url.query());
    println!("Fragment: {:?}", url.fragment());
}

构建URL

use deno_url::Url;

fn main() {
    let mut url = Url::parse("https://example.com").unwrap();
    url.set_path("/api/v1/users");
    url.set_query(Some("page=2&limit=10"));
    
    println!("Constructed URL: {}", url);
}

相对URL解析

use deno_url::Url;

fn main() {
    let base = Url::parse("https://example.com/api/v1").unwrap();
    let relative = "../v2/users";
    
    let resolved = base.join(&relative).unwrap();
    println!("Resolved URL: {}", resolved); // 输出: https://example.com/api/v2/users
}

URL验证

use deno_url::Url;

fn main() {
    match Url::parse("not a valid url") {
        Ok(url) => println!("Valid URL: {}", url),
        Err(e) => println!("Invalid URL: {}", e),
    }
}

修改URL各部分

use deno_url::Url;

fn main() {
    let mut url = Url::parse("https://example.com/old/path").unwrap();
    
    // 修改协议
    url.set_scheme("http").unwrap();
    
    // 修改主机
    url.set_host(Some("newexample.com")).unwrap();
    
    // 修改端口
    url.set_port(Some(8080)).unwrap();
    
    // 修改路径
    url.set_path("/new/path");
    
    println!("Modified URL: {}", url);
}

处理查询参数

use deno_url::Url;

fn main() {
    let mut url = Url::parse("https://example.com/search").unwrap();
    
    // 添加查询参数
    url.query_pairs_mut()
        .append_pair("q", "rust programming")
        .append_pair("lang", "en");
    
    println!("URL with query: {}", url);
    
    // 解析查询参数
    let query: Vec<(String, String)> = url.query_pairs().into_owned().collect();
    println!("Query pairs: {:?}", query);
}

性能提示

deno_url在解析URL时已经做了大量优化，但以下做法可以进一步提高性能：

1. 重用Url对象而不是重复创建
2. 对于已知有效的URL，可以使用unwrap()而不是模式匹配
3. 批量修改URL属性而不是多次单独修改

错误处理

deno_url提供了详细的错误信息，建议在生产代码中妥善处理错误：

use deno_url::{Url, ParseError};

fn parse_url(input: &str) -> Result<Url, ParseError> {
    Url::parse(input)
}

fn main() {
    match parse_url("invalid url") {
        Ok(url) => println!("Parsed URL: {}", url),
        Err(e) => println!("Error parsing URL: {}", e),
    }
}

完整示例代码

use deno_url::{Url, ParseError};

fn main() {
    // 示例1: 基本URL解析
    println!("=== 基本URL解析 ===");
    let url = Url::parse("https://www.example.com:8080/path/to/resource?name=ferret&color=purple#section1").unwrap();
    println!("完整URL: {}", url);
    println!("协议: {}", url.scheme());
    println!("主机: {}", url.host_str().unwrap());
    println!("端口: {:?}", url.port());
    println!("路径: {}", url.path());
    println!("查询字符串: {:?}", url.query());
    println!("片段: {:?}", url.fragment());
    println!();

    // 示例2: 构建URL
    println!("=== 构建URL ===");
    let mut url = Url::parse("https://api.example.com").unwrap();
    url.set_path("/v2/users");
    url.set_query(Some("page=1&per_page=20"));
    println!("构建的URL: {}", url);
    println!();

    // 示例3: 相对URL解析
    println!("=== 相对URL解析 ===");
    let base = Url::parse("https://example.com/docs/tutorial").unwrap();
    let relative = "../reference/guide";
    let resolved = base.join(relative).unwrap();
    println!("解析后的URL: {}", resolved);
    println!();

    // 示例4: URL验证
    println!("=== URL验证 ===");
    match Url::parse("htp://invalid url") {
        Ok(url) => println!("有效的URL: {}", url),
        Err(e) => println!("URL解析错误: {}", e),
    }
    println!();

    // 示例5: 修改URL
    println!("=== 修改URL ===");
    let mut url = Url::parse("https://old.example.com:8080/old/path").unwrap();
    url.set_scheme("http").unwrap();
    url.set_host(Some("new.example.com")).unwrap();
    url.set_port(None).unwrap(); // 移除端口
    url.set_path("/new/path");
    url.set_query(Some("param=value"));
    println!("修改后的URL: {}", url);
    println!();

    // 示例6: 查询参数处理
    println!("=== 查询参数处理 ===");
    let mut url = Url::parse("https://search.example.com").unwrap();
    {
        let mut pairs = url.query_pairs_mut();
        pairs.append_pair("q", "Rust编程");
        pairs.append_pair("sort", "desc");
        pairs.append_pair("page", "1");
    }
    println!("带查询参数的URL: {}", url);
    
    // 解析查询参数
    let query_pairs: Vec<_> = url.query_pairs().collect();
    println!("查询参数键值对:");
    for (key, value) in query_pairs {
        println!("  {}: {}", key, value);
    }
    println!();

    // 示例7: 错误处理
    println!("=== 错误处理 ===");
    fn process_url(url_str: &str) -> Result<(), ParseError> {
        let url = Url::parse(url_str)?;
        println!("成功解析URL: {}", url);
        Ok(())
    }

    match process_url("https://valid.url") {
        Ok(_) => println!("URL处理成功"),
        Err(e) => println!("URL处理失败: {}", e),
    }

    match process_url(":invalid.url") {
        Ok(_) => println!("URL处理成功"),
        Err(e) => println!("URL处理失败: {}", e),
    }
}

这个完整示例演示了deno_url库的主要功能，包括URL解析、构建、修改、相对URL解析、查询参数处理和错误处理等。每个示例都有清晰的注释说明其功能。

deno_url是Rust生态中处理URL的一个强大选择，特别适合需要严格遵循标准和高性能的场景。