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 以使 WASM 后端能够工作，尽管存在 Send 边界。这是安全的，因为 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