Reqwest 兼顾简洁与高性能的现代 HTTP 客户端

HTTP 客户端的选择往往面临易用性与性能的权衡，要么接口繁琐但性能出众，要么用法简洁却难以应对高并发场景。Reqwest 基于 Rust 异步运行时 tokio 构建，封装了简洁直观的 API，既能让新手快速上手，也能满足生产环境中高并发、低延迟的需求，成为 Rust 开发者处理 HTTP 请求的首选工具。

快速上手：3分钟实现第一个示例

reqwest 的入门门槛极低，只需简单几步配置，即可实现 HTTP 请求。以下是一个快速上手示例，涵盖异步、同步两种模式。

环境配置

首先在 Cargo.toml 中添加依赖，根据需求启用对应的特性，常用特性包括 json、blocking、multipart 等：

toml 复制代码

[dependencies]
reqwest = { version = "0.13", features = [
    "json",
    "blocking",
    "cookies",
] } # 启用JSON支持、同步模式、Cookie支持
tokio = { version = "1", features = ["full"] } # 异步运行时，reqwest异步模式依赖
serde = { version = "1.0", features = ["derive"] } # JSON序列化/反序列化需要
anyhow = "1.0" # 错误处理库

异步请求示例

异步模式是 reqwest 的推荐用法，适合高并发场景，借助 tokio::main 宏启动异步运行时：

rust 复制代码

use reqwest::Client;
use serde::Deserialize;

// 定义JSON响应对应的结构体用于反序列化
#[derive(Deserialize, Debug)]
struct IpResponse {
    origin: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建HTTP客户端
    let client = Client::new();

    // 发送GET请求
    let response = client
        .get("https://httpbin.org/ip") // 指定请求URL
        .header("User-Agent", "reqwest-demo/1.0") // 自定义请求头
        .send() // 发送请求
        .await?;

    // 检查响应状态码，解析响应体
    if response.status().is_success() {
        let ip_info: IpResponse = response.json().await?; // 自动反序列化为结构体
        println!("当前IP: {}", ip_info.origin);
    } else {
        eprintln!("请求失败，状态码: {}", response.status());
    }

    Ok(())
}

同步请求示例

对于简单脚本或低并发场景，可使用 reqwest::blocking 模块的同步 API，无需异步运行时：

rust 复制代码

use reqwest::blocking::get;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 发送同步GET请求
    let response = get("https://httpbin.org/get")?;
    // 读取响应体文本
    let body = response.text()?;
    println!("响应内容: {}", body);
    Ok(())
}

进阶用法

在实际开发中，仅靠基础请求无法满足复杂场景需求。reqwest 提供了丰富的进阶特性，可灵活应对超时控制、连接池调优、拦截器、文件上传等场景。

自定义客户端配置

通过 ClientBuilder 可自定义客户端的各项参数，如超时、连接池、代理、TLS 配置等，满足生产环境的个性化需求：

rust 复制代码

use reqwest::{Client, ClientBuilder, Proxy, redirect::Policy};
use std::time::Duration;

fn build_custom_client() -> Result<Client, Box<dyn std::error::Error>> {
    let client = ClientBuilder::new()
        // 超时配置（总超时、连接超时、读取超时）
        .timeout(Duration::from_secs(30))
        .connect_timeout(Duration::from_secs(10))
        .read_timeout(Duration::from_secs(20))
        // 连接池配置（空闲连接超时、每个主机最大空闲连接数）
        .pool_idle_timeout(Duration::from_secs(90))
        .pool_max_idle_per_host(10)
        // 重定向策略（最多重定向10次，也可禁用或自定义）
        .redirect(Policy::limited(10))
        // 代理配置（支持HTTP/HTTPS/SOCKS5代理）
        .proxy(Proxy::http("http://proxy.example.com:8080")?)
        // TLS配置（使用rustls替代系统原生TLS）
        .use_rustls_tls()
        // 自定义默认请求头
        .default_headers({
            let mut headers = reqwest::header::HeaderMap::new();
            headers.insert(
                reqwest::header::USER_AGENT,
                reqwest::header::HeaderValue::from_static("reqwest-advanced/1.0"),
            );
            headers
        })
        // 启用Cookie支持，需要开启 cookies feature
        .cookie_store(true)
        .build()?;

    Ok(client)
}

错误处理

reqwest 的 Error 结构体封装了所有可能的错误场景，并提供了便捷的判断方法，可快速识别错误类型，比如超时、连接失败、状态码错误等，同时支持错误链追踪，便于调试：

rust 复制代码

use reqwest::Error as ReqwestError;

async fn handle_error(err: ReqwestError) {
    eprintln!("请求失败: {}", err);
    // 提取错误关联的URL和状态码（如果有）
    if let Some(url) = err.url() {
        eprintln!("受影响的URL: {}", url);
    }
    if let Some(status) = err.status() {
        eprintln!("HTTP状态码: {}", status);
    }

    // 判断错误类型
    match (err.is_timeout(), err.is_connect(), err.is_status()) {
        (true, _, _) => eprintln!("错误类型: 超时（可尝试调整超时时间）"),
        (_, true, _) => eprintln!("错误类型: 连接失败（检查网络或目标服务）"),
        (_, _, true) => eprintln!("错误类型: 状态码错误（客户端或服务器异常）"),
        _ => eprintln!("错误类型: 其他错误"),
    }

    // 追踪错误链，打印底层错误原因
    let mut current_err: &dyn std::error::Error = &err;
    let mut depth = 1;
    while let Some(source) = current_err.source() {
        eprintln!("底层错误 {}: {}", depth, source);
        current_err = source;
        depth += 1;
    }
}

流式处理

对于大文件上传/下载场景，reqwest 支持流式处理，无需将整个文件加载到内存，大幅降低内存占用，体现其高性能优势。以下是大文件下载示例：

rust 复制代码

use reqwest::Client;
use tokio::fs::File;
use tokio::io::AsyncWriteExt;

async fn download_large_file(url: &str, save_path: &str) -> anyhow::Result<()> {
    let client = Client::new();
    // 发送请求，获取响应流
    let mut response = client.get(url).send().await?;
    // 创建文件
    let mut file = File::create(save_path).await?;
    // 流式写入文件，每次读取1024字节，避免占用过多内存
    while let Some(chunk) = response.chunk().await? {
        file.write_all(&chunk).await?;
    }
    println!("文件下载完成: {}", save_path);
    Ok(())
}

#[tokio::main]
async fn main() {
    download_large_file("https://httpbin.org/get", "downloaded_file.txt")
        .await
        .unwrap();
}

最佳实践

复用 Client 实例：避免频繁创建 Client，Client 会维护连接池，复用可大幅提升性能；
合理配置超时：根据业务场景设置合适的超时时间，避免请求长期阻塞，影响系统稳定性；
启用压缩：通过 gzip、brotli 等特性启用响应压缩，减少网络传输量；
优雅处理错误：利用 reqwest 提供的错误判断方法，针对性处理不同类型的错误，如超时重试、连接失败告警；
谨慎使用同步模式：同步模式会阻塞线程，适合低并发场景，高并发场景优先使用异步模式。

总结

reqwest 作为 Rust 生态中最流行的 HTTP 客户端，无论是简单的 API 调用、复杂的微服务通信，还是高性能的爬虫开发，它都能满足你的需求，如果你正在 Rust 项目中处理 HTTP 请求，不妨直接使用 reqwest。