curl-rust

libcurl 的Rust绑定

快速入门

use std::io::{stdout, Write};

use curl::easy::Easy;

// Print a web page onto stdout
fn main() {
    let mut easy = Easy::new();
    easy.url("https://www.rust-lang.net.cn/").unwrap();
    easy.write_function(|data| {
        stdout().write_all(data).unwrap();
        Ok(data.len())
    }).unwrap();
    easy.perform().unwrap();

    println!("{}", easy.response_code().unwrap());
}

use curl::easy::Easy;

// Capture output into a local `Vec`.
fn main() {
    let mut dst = Vec::new();
    let mut easy = Easy::new();
    easy.url("https://www.rust-lang.net.cn/").unwrap();

    let mut transfer = easy.transfer();
    transfer.write_function(|data| {
        dst.extend_from_slice(data);
        Ok(data.len())
    }).unwrap();
    transfer.perform().unwrap();
}

Post / Put请求

Easy 上的 put 和 post 方法可以配置HTTP请求的方法，然后可以使用 read_function 来指定如何填充数据。此接口与实现 Read 的类型配合得很好。

use std::io::Read;
use curl::easy::Easy;

fn main() {
    let mut data = "this is the body".as_bytes();

    let mut easy = Easy::new();
    easy.url("http://www.example.com/upload").unwrap();
    easy.post(true).unwrap();
    easy.post_field_size(data.len() as u64).unwrap();

    let mut transfer = easy.transfer();
    transfer.read_function(|buf| {
        Ok(data.read(buf).unwrap_or(0))
    }).unwrap();
    transfer.perform().unwrap();
}

自定义头

可以在请求中指定自定义头

use curl::easy::{Easy, List};

fn main() {
    let mut easy = Easy::new();
    easy.url("http://www.example.com").unwrap();

    let mut list = List::new();
    list.append("Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==").unwrap();
    easy.http_headers(list).unwrap();
    easy.perform().unwrap();
}

保持连接

可以在多个请求之间重用句柄。Curl将尝试保持连接活跃。

use curl::easy::Easy;

fn main() {
    let mut handle = Easy::new();

    handle.url("http://www.example.com/foo").unwrap();
    handle.perform().unwrap();

    handle.url("http://www.example.com/bar").unwrap();
    handle.perform().unwrap();
}

多个请求

libcurl库通过“multi”接口提供支持，可以同时发送多个请求。这目前在crate的 multi 模块中实现，并提供同时执行多个传输的能力。有关更多信息，请参阅该模块。

构建

默认情况下，此crate将尝试动态链接到系统范围内的libcurl和系统范围内的SSL库。可以使用各种Cargo功能自定义一些此行为

• ssl：使用平台默认的TLS后端启用SSL/TLS支持。在Windows上这是 Schannel，在macOS上是 Secure Transport，在其他所有平台上是 OpenSSL（或等效）。默认启用。

• rustls 通过 Rustls 启用SSL/TLS支持，这是一个用Rust编写的广受欢迎的替代TLS后端。Rustls始终是静态链接。默认禁用。

  请注意，Rustls 在 Curl 中的支持是实验性的，并且可能存在重大错误，因此我们不会对这项功能提供任何稳定性保证。

• http2：通过 libnghttp2 启用 HTTP/2 支持。默认禁用。

• static-curl：使用捆绑的 libcurl 版本并将其静态链接。默认禁用。

• static-ssl：使用捆绑的 OpenSSL 版本并将其静态链接。仅适用于使用 OpenSSL 的平台。默认禁用。

• spnego：启用 SPNEGO 支持。默认禁用。

• upkeep_7_62_0：启用 curl_easy_upkeep() 支持，该支持在 curl 7.62.0 中引入。默认禁用。

• poll_7_68_0：启用 curl_multi_poll()/curl_multi_wakeup() 支持，需要 curl 7.68.0 或更高版本。默认禁用。

• ntlm：在 curl 中启用 NTLM 支持。默认禁用。

• windows-static-ssl：通过 vcpkg 提供的静态构建启用 Windows 上的 Openssl 支持。与 ssl 不兼容（使用 --no-default-features）。默认禁用。

  请注意，要在 Windows 上通过 vcpkg 安装 openssl，需要运行以下命令

  git clone https://github.com/microsoft/vcpkg
  cd vcpkg
  ./bootstrap-vcpkg.bat -disableMetrics
  ./vcpkg.exe integrate install
  ./vcpkg.exe install openssl:x64-windows-static-md
  

版本支持

这些绑定是在 curl 版本 7.24.0 下开发的。它们应该与任何新的 curl 版本兼容，并且可能也与旧版本兼容，但这尚未经过测试。

故障排除

Curl 链接了 NSS SSL 库

如果您遇到以下错误信息

  [77] Problem with the SSL CA cert (path? access rights?)

这意味着最有可能的情况是，由于已安装的 libcurl NSS 开发文件，curl 链接到了 libcurl-nss.so，并且所需的库 libnsspem.so 丢失。另请参阅 curl 的 man 页面：“如果 curl 是针对 NSS SSL 库构建的，则 NSS PEM PKCS#11 模块（libnsspem.so）需要可用才能使此选项正常工作。”

为了避免这种失败，您可以选择

• 安装缺失的库（例如 Debian：nss-plugin-pem），或者
• 删除 libcurl NSS 开发文件（例如 Debian：libcurl4-nss-dev）并重新构建 curl-rust。

许可

curl-rust 软件包遵循 MIT 许可证，有关更多详细信息，请参阅 LICENSE。