Rust语言从入门到精通系列 - 轻量级Http客户端Hyper

Hyper 是一个用于构建 HTTP 客户端和服务器的 Rust 语言库。它提供了一个简单易用的 API，使得开发者可以轻松地构建高性能、可靠的 HTTP 应用程序。Hyper 的设计目标是安全、高效和易于使用。

Hyper 的主要特点包括：

支持 HTTP/1 和 HTTP/2 协议
纯 Rust 实现，无需外部依赖
支持异步 I/O 和多线程
提供简单易用的 API

在本教程中，我们将介绍 Hyper 的基础用法和进阶用法，并提供一些最佳实践。

相比于系列文章中介绍的 reqwest, Hyper 设计的更底层，模块化的设计，可以最大限度的允许用户在硬件配置较低的嵌入式设备上使用。假如只是需要一个“好用”的 Http 客户端，推荐使用 reqwest 模块

基础用法#

发送 HTTP 请求#

使用 Hyper 发送 HTTP 请求非常简单。下面是一个简单的示例，它使用 Hyper 发送一个 GET 请求并打印响应的内容：

注意: 以下示例已更新为 reqwest（推荐用于 HTTP 客户端场景）。Hyper 0.10.x 同步 API 已废弃，Hyper 1.x 仅支持异步且 API 完全不同。如需底层 HTTP 控制，请参考 Hyper 1.x 文档。

1
use reqwest::blocking::Client;
2

3
fn main() {
4
    let client = Client::new();
5
    let res = client.get("http://example.com").send().unwrap();
6
    println!("{}", res.status());
7
    println!("{:?}", res.headers());
8
    println!("{}", res.text().unwrap());
9
}

在这个示例中，我们使用 reqwest::blocking::Client 创建了一个 HTTP 客户端，发送 GET 请求并打印响应的状态码、头和内容。Hyper 0.10.x 的同步 API（Client::new(), client.get().send()）已不再可用。

发送 POST 请求#

Hyper 还支持发送 POST 请求。下面是一个简单的示例，它使用 Hyper 发送一个 POST 请求并打印响应的内容：

1
use reqwest::blocking::Client;
2

3
fn main() {
4
    let client = Client::new();
5
    let res = client.post("http://example.com")
6
        .body("hello world")
7
        .send()
8
        .unwrap();
9
    println!("{}", res.status());
10
    println!("{:?}", res.headers());
11
    println!("{}", res.text().unwrap());
12
}

在这个示例中，我们使用 reqwest 发送 POST 请求。Hyper 0.10.x 的 Request::post().body() 同步模式已废弃。

使用代理服务器#

Hyper 还支持使用代理服务器发送 HTTP 请求。下面是一个简单的示例，它使用 Hyper 发送一个通过代理服务器的 HTTP 请求并打印响应的内容：

1
use reqwest::blocking::Client;
2

3
fn main() {
4
    let client = Client::builder()
5
        .proxy(reqwest::Proxy::http("http://proxy.example.com").unwrap())
6
        .build()
7
        .unwrap();
8
    let res = client.get("http://example.com").send().unwrap();
9
    println!("{}", res.status());
10
    println!("{:?}", res.headers());
11
    println!("{}", res.text().unwrap());
12
}

在这个示例中，我们使用 reqwest 设置代理服务器。Hyper 0.10.x 的 Client::builder().proxy() 同步模式已废弃。

使用自定义头#

Hyper 还支持使用自定义头发送 HTTP 请求。下面是一个简单的示例，它使用 Hyper 发送一个带有自定义头的 HTTP 请求并打印响应的内容：

1
use reqwest::blocking::Client;
2
use reqwest::header::{USER_AGENT, HeaderValue};
3

4
fn main() {
5
    let client = Client::new();
6
    let res = client.get("http://example.com")
7
        .header(USER_AGENT, HeaderValue::from_static("my-user-agent"))
8
        .send()
9
        .unwrap();
10
    println!("{}", res.status());
11
    println!("{:?}", res.headers());
12
    println!("{}", res.text().unwrap());
13
}

在这个示例中，我们使用 reqwest 设置自定义请求头。Hyper 0.10.x 的同步请求构建模式已废弃。

使用异步 I/O#

Hyper 支持异步 I/O，这使得它可以处理大量的并发请求。下面是一个简单的示例，它使用 Hyper 异步发送 HTTP 请求并打印响应的内容：

1
use reqwest::Client;
2

3
#[tokio::main]
4
async fn main() {
5
    let client = Client::new();
6
    let res = client.get("http://example.com").send().await.unwrap();
7
    println!("{}", res.status());
8
    println!("{:?}", res.headers());
9
    println!("{}", res.text().await.unwrap());
10
}

在这个示例中，我们使用 reqwest 异步客户端。Hyper 1.x 异步客户端示例（需 hyper_util + http_body_util）：

1
use hyper_util::client::legacy::Client;
2
use hyper_util::rt::TokioExecutor;
3
use http_body_util::BodyExt;
4
use hyper::Request;
5

6
#[tokio::main]
7
async fn main() {
8
    let client: Client<_, String> = Client::builder(TokioExecutor::new()).build_http();
9
    let req = Request::builder()
10
        .uri("http://example.com")
11
        .body(String::new())
12
        .unwrap();
13
    let res = client.request(req).await.unwrap();
14
    println!("{}", res.status());
15
    let body = res.into_body().collect().await.unwrap().to_bytes();
16
    println!("{}", String::from_utf8_lossy(&body));
17
}

Hyper 0.10.x 的 client.get(uri).await 模式已废弃，Hyper 1.x 需通过 hyper_util::client::legacy::Client 构建请求。

使用 Cookies#

Hyper 还支持使用 Cookies 发送 HTTP 请求。下面是一个简单的示例，它使用 Hyper 发送一个带有 Cookies 的 HTTP 请求并打印响应的内容：

1
use reqwest::blocking::Client;
2
use reqwest::header::{COOKIE, SET_COOKIE};
3

4
fn main() {
5
    let client = Client::new();
6
    let res = client.get("http://example.com")
7
        .header(COOKIE, "name=value")
8
        .send()
9
        .unwrap();
10
    println!("{}", res.status());
11
    if let Some(cookie) = res.headers().get(SET_COOKIE) {
12
        println!("{}", cookie.to_str().unwrap());
13
    }
14
    println!("{}", res.text().unwrap());
15
}

在这个示例中，我们使用 reqwest 通过 Header 方式发送 Cookie。Hyper 0.10.x 的同步 Cookie 模式已废弃。

处理错误#

Hyper 的 API 返回的结果类型是Result，因此我们可以使用标准的 Rust 错误处理机制来处理错误。下面是一个简单的示例，它使用 Hyper 发送一个 HTTP 请求并处理错误：

1
use reqwest::blocking::Client;
2
use std::error::Error;
3

4
fn main() -> Result<(), Box<dyn Error>> {
5
    let client = Client::new();
6
    let res = client.get("http://example.com").send()?;
7
    println!("{}", res.status());
8
    println!("{:?}", res.headers());
9
    println!("{}", res.text()?);
10
    Ok(())
11
}

在这个示例中，我们使用 reqwest 并通过 ? 操作符处理错误。Hyper 0.10.x 的同步 client.get(uri)?.send()? 模式已废弃。

进阶用法#

使用连接池#

Hyper 支持使用连接池来提高 HTTP 请求的性能。下面是一个简单的示例，它使用 Hyper 连接池发送 HTTP 请求并打印响应的内容：

1
use reqwest::blocking::Client;
2
use std::time::Duration;
3

4
fn main() {
5
    let client = Client::builder()
6
        .pool_idle_timeout(Duration::from_secs(30))
7
        .build()
8
        .unwrap();
9
    let res = client.get("https://example.com").send().unwrap();
10
    println!("{}", res.status());
11
    println!("{}", res.text().unwrap());
12
}

在这个示例中，我们使用 reqwest 连接池配置。Hyper 0.10.x 的 HttpConnector/HttpsConnector/rt::run/concat2 模式已全部废弃，Hyper 1.x 需通过 hyper_util 管理。

使用 WebSocket#

Hyper 还支持使用 WebSocket 协议。下面是一个简单的示例，它使用 Hyper 创建一个 WebSocket 连接并发送消息：

注意: Hyper 本身不提供 WebSocket 客户端 API。以下示例使用 tokio-tungstenite 直接连接 WebSocket。

1
use tokio_tungstenite::tungstenite::Message;
2
use futures_util::StreamExt;
3
use tokio_tungstenite::connect_async;
4

5
#[tokio::main]
6
async fn main() {
7
    let (ws_stream, _) = connect_async("ws://example.com").await.unwrap();
8
    let (mut write, mut read) = ws_stream.split();
9
    write.send(Message::Text("hello world".into())).await.unwrap();
10
    while let Some(msg) = read.next().await {
11
        let msg = msg.unwrap();
12
        println!("{}", msg.to_text().unwrap());
13
    }
14
}

在这个示例中，我们使用 tokio-tungstenite 创建 WebSocket 连接。Hyper 0.10.x 的 client.websocket(uri) 方法不存在，WebSocket 需使用专用库如 tokio-tungstenite。

处理连接超时#

Hyper 支持设置连接和请求的超时时间。下面是一个简单的示例，它使用 Hyper 发送一个 HTTP 请求，并设置连接和请求的超时时间：

1
use reqwest::blocking::Client;
2
use std::time::Duration;
3

4
fn main() {
5
    let client = Client::builder()
6
        .timeout(Duration::from_secs(10))
7
        .pool_idle_timeout(Duration::from_secs(30))
8
        .build()
9
        .unwrap();
10
    let res = client.get("http://example.com").send().unwrap();
11
    println!("{}", res.status());
12
    println!("{}", res.text().unwrap());
13
}

在这个示例中，我们使用 reqwest 设置请求超时和连接池超时。Hyper 0.10.x 的 keep_alive_timeout()/timeout().send().map()/tokio::run() 模式已废弃。

使用自定义 TLS 配置#

Hyper 支持使用自定义的 TLS 配置来发送 HTTPS 请求。下面是一个简单的示例，它使用 Hyper 发送一个带有自定义 TLS 配置的 HTTPS 请求并打印响应的内容：

1
use reqwest::blocking::Client;
2
use std::error::Error;
3
use std::path::Path;
4

5
fn main() -> Result<(), Box<dyn Error>> {
6
    let client = Client::builder()
7
        .add_root_certificate(reqwest::Certificate::from_pem(
8
            &std::fs::read(Path::new("cert.pem"))?,
9
        )?)
10
        .build()?;
11
    let res = client.get("https://example.com").send()?;
12
    println!("{}", res.status());
13
    println!("{}", res.text()?);
14
    Ok(())
15
}

在这个示例中，我们使用 reqwest 加载自定义 TLS 证书。Hyper 0.10.x 的 hyper_tls::HttpsConnector::with_connector() 模式已废弃，现代 Rust 推荐使用 reqwest 的 add_root_certificate() 或 hyper-rustls。

最佳实践#

使用连接池提高性能

Hyper 提供了连接池的功能，可以有效地提高 HTTP 请求的性能。在实际开发中，我们应该尽可能地使用连接池来发送 HTTP 请求，以提高性能和减少资源消耗。

使用异步 I/O 提高并发性能

Hyper 使用异步 I/O 实现了高性能的 HTTP 客户端和服务器端，我们应该尽可能地使用异步 I/O 来提高并发性能。

使用 HTTPS 保证安全性

在发送 HTTP 请求时，我们应该尽可能地使用 HTTPS 来保证通信的安全性。Hyper 提供了对 HTTPS 的支持，可以轻松地实现 HTTPS 通信。

使用请求/响应拦截器进行处理

Hyper 提供了请求/响应拦截器的功能，可以对 HTTP 请求和响应进行处理。在实际开发中，我们应该尽可能地使用请求/响应拦截器来实现一些通用的处理逻辑，例如日志记录、错误处理等。

总结#

Hyper 是 Rust 语言中一个非常流行的 HTTP 客户端和服务器端开发库，它提供了一套简单易用的 API，可以轻松地构建高性能的 Web 应用程序。在本教程中，我们介绍了 Hyper 的基础用法和进阶用法，并提供了一些最佳实践和示例代码。希望这个教程能够帮助你更好地了解 Hyper，并在实际开发中使用它。

音乐

音乐