Rust HTTP链接头解析库 parse_link_header 使用指南

parse_link_header 是一个专门用于解析 HTTP Link 头字段的 Rust 库，它可以帮助开发者高效处理 Web API 中的分页链接和资源关系。

功能特点

• 符合 RFC 5988 标准
• 支持解析复杂 Link 头
• 提供便捷的查询方法
• 零拷贝解析
• 无运行时分配

安装

在 Cargo.toml 中添加依赖：

[dependencies]
parse_link_header = "0.3"

基本用法

解析 Link 头

use parse_link_header::parse;

let link_header = r#"<https://api.example.com/users?page=2>; rel="next", 
                     <https://api.example.com/users?page=5>; rel="last""#;

let links = parse(link_header).unwrap();

for link in links {
    println!("URI: {}, Rel: {:?}", link.uri, link.rel);
}

查找特定关系链接

use parse_link_header::{parse, Relation};

let link_header = r#"<https://api.github.com/user/repos?page=2>; rel="next",
                     <https://api.github.com/user/repos?page=3>; rel="last""#;

let links = parse(link_header).unwrap();

if let Some(next) = links.find(|l| l.rel == Some(Relation::Next)) {
    println!("Next page: {}", next.uri);
}

if let Some(last) = links.find(|l| l.rel == Some(Relation::Last)) {
    println!("Last page: {}", last.uri);
}

高级用法

处理多个关系

let link_header = r#"<https://example.com>; rel="start prefetch""#;

let links = parse(link_header).unwrap();

for link in links {
    if let Some(rels) = link.rel {
        println!("URI: {}, Relations: {:?}", link.uri, rels);
    }
}

处理自定义关系

let link_header = r#"<https://api.example.com/users/123>; rel="user""#;

let links = parse(link_header).unwrap();

if let Some(user_link) = links.find(|l| l.rel == Some("user".into())) {
    println!("User resource: {}", user_link.uri);
}

处理多个参数

let link_header = r#"<https://example.com>; rel="next"; title="Next Page"; type="text/html""#;

let links = parse(link_header).unwrap();

for link in links {
    println!("URI: {}", link.uri);
    println!("Rel: {:?}", link.rel);
    println!("Title: {:?}", link.title);
    println!("Type: {:?}", link.media_type);
}

错误处理

use parse_link_header::ParseError;

let invalid_link = "<https://example.com>; invalid";

match parse(invalid_link) {
    Ok(links) => {
        // 处理链接
    },
    Err(ParseError::Malformed) => {
        eprintln!("Malformed Link header");
    },
    Err(e) => {
        eprintln!("Error parsing Link header: {:?}", e);
    }
}

实际应用示例

GitHub API 分页处理

use reqwest;
use parse_link_header::{parse, Relation};

async fn get_github_repos() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let response = client.get("https://api.github.com/user/repos")
        .header("User-Agent", "MyApp")
        .send()
        .await?;
    
    if let Some(link_header) = response.headers().get("link") {
        let links = parse(link_header.to_str()?)?;
        
        if let Some(next) = links.find(|l| l.rel == Some(Relation::Next)) {
            println!("Next page available at: {}", next.uri);
            // 可以在这里继续请求下一页
        }
    }
    
    Ok(())
}

性能提示

• parse_link_header 使用零拷贝解析，避免不必要的内存分配
• 解析结果中的 Link 结构体借用原始字符串数据
• 如果需要长期存储链接，可以考虑将 uri 和参数转换为 String

parse_link_header 是处理 HTTP Link 头的轻量级解决方案，特别适合需要处理 Web API 分页和资源关系的 Rust 应用程序。

完整示例代码

use parse_link_header::{parse, Relation};
use reqwest;
use std::error::Error;

// 完整的分页处理示例
async fn handle_pagination() -> Result<(), Box<dyn Error>> {
    // 1. 创建HTTP客户端
    let client = reqwest::Client::new();
    
    // 2. 发送初始请求
    let mut current_url = "https://api.github.com/user/repos";
    let mut page_count = 1;
    
    loop {
        println!("Fetching page {}: {}", page_count, current_url);
        
        // 3. 发送请求并获取响应
        let response = client.get(current_url)
            .header("User-Agent", "PaginationDemo")
            .send()
            .await?;
        
        // 4. 处理响应数据
        let repos: serde_json::Value = response.json().await?;
        println!("Page {} contains {} repositories", page_count, repos.as_array().unwrap().len());
        
        // 5. 解析Link头处理分页
        if let Some(link_header) = response.headers().get("link") {
            let links = parse(link_header.to_str()?)?;
            
            // 6. 检查是否有下一页
            if let Some(next) = links.find(|l| l.rel == Some(Relation::Next)) {
                current_url = next.uri;
                page_count += 1;
            } else {
                println!("No more pages available");
                break;
            }
        } else {
            println!("No Link header found, assuming single page");
            break;
        }
    }
    
    Ok(())
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // 调用分页处理函数
    handle_pagination().await?;
    
    // 另一个示例：解析自定义Link头
    let custom_link = r#"<https://api.example.com/data/123>; rel="item"; type="application/json""#;
    let parsed = parse(custom_link)?;
    
    for link in parsed {
        println!("Found link: {}", link.uri);
        println!("Relation: {:?}", link.rel);
        println!("Media type: {:?}", link.media_type);
    }
    
    Ok(())
}

代码说明

1. 分页处理：

   • 使用reqwest库发送HTTP请求
   • 自动跟踪Link头中的"next"关系
   • 处理JSON响应数据
   • 支持多页遍历直到没有下一页

2. 自定义Link头解析：

   • 演示如何解析包含自定义关系和媒体类型的Link头
   • 展示如何访问Link结构体的各个字段

3. 错误处理：

   • 使用Rust的标准错误处理方式
   • 自动向上传播错误

4. 异步支持：

   • 使用async/await语法
   • 需要tokio运行时

这个完整示例展示了如何在实际项目中使用parse_link_header库处理API分页和解析复杂Link头，包含了错误处理、异步请求等生产环境需要的功能。