Rust URI解析与操作库re_uri的使用

简介

re_uri是一个专注于URI/URL解析和操作的Rust库，提供高效且符合标准的Web链接和资源定位符处理能力。它支持RFC 3986定义的URI规范，能够解析、构建、修改和验证URI。

主要特性

• 完整的URI解析和验证
• URI组件分解和访问
• URI构建和修改
• 相对URI解析
• 百分号编码(Percent-encoding)处理
• 轻量级且无依赖

安装

在Cargo.toml中添加依赖：

[dependencies]
re_uri = "0.3"

基本使用示例

解析URI

use re_uri::Uri;

fn main() {
    // 解析URI字符串
    let uri_str = "https://example.com:8080/path/to/resource?query=value#fragment";
    let uri = Uri::parse(uri_str).expect("Invalid URI");
    
    // 输出各个组件
    println!("Scheme: {}", uri.scheme());
    println!("Authority: {}", uri.authority().unwrap());
    println!("Path: {}", uri.path());
    println!("Query: {:?}", uri.query());
    println!("Fragment: {:?}", uri.fragment());
}

构建URI

use re_uri::UriBuilder;

fn main() {
    // 使用构建器模式创建URI
    let uri = UriBuilder::new()
        .scheme("https")
        .authority("example.com:8080")
        .path("/api/v1/users")
        .query("page=2&limit=10")
        .fragment("results")
        .build()
        .unwrap();
    
    println!("Constructed URI: {}", uri);
}

修改URI

use re_uri::Uri;

fn main() {
    // 解析现有URI
    let mut uri = Uri::parse("https://example.com/path").unwrap();
    
    // 修改scheme部分
    uri.set_scheme("http").unwrap();
    
    // 添加查询参数
    uri.set_query(Some("param=value"));
    
    println!("Modified URI: {}", uri);
}

相对URI解析

use re_uri::{Uri, UriRef};

fn main() {
    // 基础URI
    let base = Uri::parse("https://example.com/base/").unwrap();
    // 相对路径
    let relative = UriRef::parse("../resource").unwrap();
    
    // 解析为绝对URI
    let resolved = relative.resolve(&base).unwrap();
    println!("Resolved URI: {}", resolved);  // 输出: https://example.com/resource
}

高级用法示例

处理查询参数

use re_uri::Uri;
use std::collections::HashMap;

// 将查询字符串解析为HashMap
fn parse_query(uri: &Uri) -> HashMap<String, String> {
    uri.query()
        .map(|q| {
            q.split('&')
                .filter_map(|pair| {
                    let mut kv = pair.splitn(2, '=');
                    match (kv.next(), kv.next()) {
                        (Some(k), Some(v)) => Some((k.to_string(), v.to_string())),
                        _ => None,
                    }
                })
                .collect()
        })
        .unwrap_or_default()
}

fn main() {
    let uri = Uri::parse("https://example.com?name=John&age=30").unwrap();
    let params = parse_query(&uri);
    
    println!("Query params: {:?}", params);
}

百分号编码处理

use re_uri::percent_encode;

fn main() {
    // 编码特殊字符
    let encoded = percent_encode("user@example.com");
    println!("Encoded: {}", encoded);  // 输出: user%40example.com
    
    // 解码
    let decoded = re_uri::percent_decode(encoded.as_bytes());
    println!("Decoded: {}", String::from_utf8(decoded).unwrap());
}

错误处理示例

use re_uri::Uri;

fn main() {
    // 处理可能失败的URI解析
    match Uri::parse("invalid uri") {
        Ok(uri) => println!("Valid URI: {}", uri),
        Err(e) => println!("Error parsing URI: {}", e),
    }
}

完整示例demo

下面是一个综合使用re_uri库的完整示例，展示了从创建、修改到解析URI的全过程：

use re_uri::{Uri, UriBuilder, UriRef};
use std::collections::HashMap;

fn main() {
    // 1. 构建一个新URI
    let api_uri = UriBuilder::new()
        .scheme("https")
        .authority("api.example.com")
        .path("/v1/data")
        .query("format=json&limit=100")
        .build()
        .unwrap();
    println!("API URI: {}", api_uri);

    // 2. 修改现有URI
    let mut modified_uri = api_uri.clone();
    modified_uri.set_query(Some("format=xml&offset=50"));
    println!("Modified URI: {}", modified_uri);

    // 3. 解析相对路径
    let base_uri = Uri::parse("https://example.com/docs/tutorial/").unwrap();
    let relative_ref = UriRef::parse("../reference").unwrap();
    let resolved_uri = relative_ref.resolve(&base_uri).unwrap();
    println!("Resolved URI: {}", resolved_uri);

    // 4. 处理查询参数
    let query_params = parse_query(&api_uri);
    println!("Query Parameters: {:?}", query_params);

    // 5. 编码/解码示例
    let raw_str = "data@test/value";
    let encoded = re_uri::percent_encode(raw_str);
    println!("Encoded: {}", encoded);
    let decoded = re_uri::percent_decode(encoded.as_bytes());
    println!("Decoded: {}", String::from_utf8(decoded).unwrap());
}

// 解析查询字符串到HashMap
fn parse_query(uri: &Uri) -> HashMap<String, String> {
    uri.query()
        .map(|q| {
            q.split('&')
                .filter_map(|pair| {
                    let mut kv = pair.splitn(2, '=');
                    match (kv.next(), kv.next()) {
                        (Some(k), Some(v)) => Some((k.to_string(), v.to_string())),
                        _ => None,
                    }
                })
                .collect()
        })
        .unwrap_or_default()
}

性能提示

re_uri在设计上注重性能：

• 尽可能避免不必要的内存分配
• 延迟计算某些组件直到首次访问
• 提供零拷贝解析选项

对于需要处理大量URI的高性能场景，建议重用Uri实例而不是重复创建。

re_uri是处理URI相关操作的强大工具，特别适合Web开发、网络编程和资源定位等场景。