Isahc

欢迎来到Isahc（发音类似于Isaac），这是一个实用的HTTP客户端，使用起来非常有趣。

以前称为 chttp。

主要特性

• 完全支持HTTP/1.1和HTTP/2。
• 可配置的请求超时、重定向策略、Unix套接字以及更多设置。
• 提供了一个易于使用的同步API以及支持async/await的运行时无关异步API。
• 完全异步核心，具有请求和响应体的增量读取和写入以及连接复用。
• 会话和cookie持久化。
• 自动在丢弃时取消请求。
• 使用http crate作为请求和响应的接口。

什么是Isahc？

Isahc是缩写，代表 Incredible Streaming Asynchronous HTTP Client，正如其名所示，是一个Rust语言的异步HTTP客户端。它使用libcurl作为内部的HTTP引擎，并提供了与Rust惯用法集成的易于使用的API。

不，谁是Isahc？

哦，你是说Isahc这只狗！它是一只可爱的小西伯利亚雪橇犬，每天喜欢和web服务器玩接球游戏，尾巴非常curl。

如果你喜欢，你可以全天抚摸它，它并不介意。不过，它更喜欢你以标准合规的方式抚摸它！

文档

请查看文档以获取有关Isahc能做什么以及如何使用的详细信息。为了帮助你入门，这里有一个非常简单、完整的示例，它输出来自https://example.org的响应体。

use isahc::prelude::*;

fn main() -> Result<(), isahc::Error> {
    // Send a GET request and wait for the response headers.
    // Must be `mut` so we can read the response body.
    let mut response = isahc::get("https://example.org")?;

    // Print some basic info about the response to standard output.
    println!("Status: {}", response.status());
    println!("Headers: {:#?}", response.headers());

    // Read the response body as text into a string and print it.
    print!("{}", response.text()?);

    Ok(())
}

点击这里获取最新版本的文档。您还可以点击这里查看从最新未发布版本的master构建的构建文档。

获取帮助

需要一些关于Isahc的帮助吗？在我们的讨论页面上提问，我们很乐意尝试回答您的问题！

安装

通过在您的Cargo.toml文件中添加来安装

[dependencies]
isahc = "1.7"

最低支持的Rust版本

Isahc的最低支持Rust版本（或MSRV）是稳定版Rust 1.46或更高版本，这意味着我们只能保证如果您使用至少1.46版本的rustc，Isahc将能够编译。它可能可以使用较旧版本编译，但这可能在任何时候改变。

这个版本在CI中明确测试过，并且可能只在新的小版本中提升。任何对支持最低版本的改变都将在发布说明中列出。

项目目标

• 创建一个既易于初学者使用又适用于高级使用的舒适和创新型HTTP客户端API。
• 提供libcurl的高级包装。
• 保持轻量级的依赖树和小型二进制文件大小。
• 提供可选编译的附加客户端功能。

非目标

• 除了HTTP以外的协议支持。
• 除了libcurl以外的其他引擎。其他项目更适合这个。

为什么使用Isahc而不是X？

Isahc提供了一个易于使用、灵活和符合Rust风格的API，使得发送HTTP请求变得轻而易举。Isahc的目标是让简单的方式同时提供优秀的性能和适用于常见用例的正确性。

Isahc底层使用libcurl来处理HTTP协议和网络。使用curl作为HTTP客户端的引擎是一个很好的选择，原因有以下几点

• 它是一个稳定、积极开发且非常流行的库。
• 它在各种平台上都得到了很好的支持。
• HTTP协议在不同服务器之间存在许多意外的问题，而curl已经存在很长时间，能够处理其中许多问题。
• 它经过良好的优化，并提供了实现异步请求的能力。

curl crate提供了对libcurl的安全Rust绑定，您可以直接使用它。Isahc在vanilla curl之上提供了大量价值，通过提供更简单、更符合Rust风格的API，并完成了将强大的multi接口转换为基于futures的API的繁重工作。

何时不使用Isahc？

并非每个库都适合每个用例。虽然Isahc力求成为一个功能全面且通用的HTTP客户端，适用于许多项目，但Isahc不适用于以下几种情况

• 小型二进制文件：如果您正在创建一个对小型二进制文件大小至关重要的应用程序，您可能会发现Isahc对您来说太大。虽然Isahc的依赖项经过精心挑选，并且可以禁用许多功能，但Isahc的核心功能集包括异步这样的功能，确实会带来一些文件大小开销。您可能会发现像ureq这样的工具更适合。
• WebAssembly支持：如果您需要将项目编译为WebAssembly，那么Isahc可能不适合您。相反，您可能会喜欢支持多个后端的HTTP客户端，例如Surf。
• Rustls支持：我们希望将来有一天能够支持rustls作为TLS后端，但目前还不直接支持。如果您出于某种原因必须使用rustls，那么您现在需要使用不同的HTTP客户端。

赞助商

特别感谢支持我的开源工作的赞助商！

许可证

本项目的源代码和文档采用MIT许可证授权。有关详细信息，请参阅LICENSE文件。

Isahc标志和相关资产采用Creative Commons Attribution 4.0 International License授权。有关详细信息，请参阅LICENSE-CC-BY。