Surf

畅游网络 - HTTP客户端框架

Surf是一个专为易用性和多HTTP后端灵活性而构建的Rust HTTP客户端。无论是快速脚本还是跨平台SDK，Surf都能使其工作。

• 通过强大的中间件系统进行扩展
• 可以选择多个HTTP后端
• 通过可配置的Client接口重用连接
• 完全流式请求和响应
• 默认启用TLS（原生TLS或rustls）
• 基于async-std（可选tokio支持）构建

示例

let mut res = surf::get("https://httpbin.org/get").await?;
dbg!(res.body_string().await?);

也可以跳过中间的Response，直接访问响应类型。

dbg!(surf::get("https://httpbin.org/get").recv_string().await?);

发送和接收JSON也非常简单。

#[derive(Deserialize, Serialize)]
struct Ip {
    ip: String
}

let uri = "https://httpbin.org/post";
let data = &Ip { ip: "129.0.0.1".into() };
let res = surf::post(uri).body_json(data)?.await?;
assert_eq!(res.status(), 200);

let uri = "https://api.ipify.org?format=json";
let Ip { ip } = surf::get(uri).recv_json().await?;
assert!(ip.len() > 10);

甚至创建流式代理也毫不费力。

let req = surf::get("https://img.fyi/q6YvNqP").await?;
let body = surf::http::Body::from_reader(req, None);
let res = surf::post("https://box.rs/upload").body(body).await?;

在客户端上设置配置也很直接。

use std::convert::TryInto;
use std::time::Duration;
use surf::{Client, Config};
use surf::Url;

let client: Client = Config::new()
    .set_base_url(Url::parse("http://example.org")?)
    .set_timeout(Some(Duration::from_secs(5)))
    .try_into()?;

let mut res = client.get("/").await?;
println!("{}", res.body_string().await?);

功能

以下功能可用。默认功能为 curl-client、middleware-logger 和 encoding

• curl-client（默认）：使用curl（通过isahc）作为HTTP后端。
• h1-client：使用async-h1作为HTTP后端，具有原生TLS进行HTTPS。
• h1-client-rustls：使用async-h1作为HTTP后端，使用rustls进行HTTPS。
• hyper-client：使用hyper（hyper.rs）作为HTTP后端。
• wasm-client：使用window.fetch作为HTTP后端。
• middleware-logger (默认): 使用中间件启用请求和响应的日志记录。
• encoding (默认): 启用对非utf-8编码体的支持。

安装

安装 OpenSSL -

• Ubuntu - sudo apt install libssl-dev
• Fedora - sudo dnf install openssl-devel

使用：rustup update 确保你的 rust 是最新的。

安装cargo add之后

$ cargo add surf

安全性

这个crate使用单个实例的unsafe，以便即使有Send限制也能使WASM后端工作。这是安全的，因为WASM目标目前无法访问线程。一旦它们能够这样做，我们将能够弃用此实现，并使用挂起的线程，并在过程中实现完全的多线程。

贡献

想加入我们？查看我们的“贡献”指南并查看一些这些问题

• 标记为“good first issue”的问题
• 标记为“help wanted”的问题

另请参阅

• http-rs/http-client
• http-rs/http-service
• http-rs/tide

谢谢

特别感谢prasannavl捐赠crate名称，以及sagebind创建了一个易于使用的async curl客户端，为我们节省了无数小时。

许可

MIT OR Apache-2.0