Rust 翻译计划——网络编程 curl 库 (上)

本文目录:

1. 简介
2. 快速通道
3. 翻译--curl库
   • easy模块
   • multi模块

1. 简介

虽然这个系列是属于Rust使用库翻译计划的系列之一，可是因为该库官网提供的使用文档几乎等于没有，因此本文其实是简单翻译一下api文档后小生本身写的使用文档，Orz。

2. 快速通道

全部的翻译文章将集中导航于:Rust经常使用库翻译计划

3.翻译——curl库

curl库github快速通道
配套翻译之curl中文api

该库主要实现了网络通讯中做为客户端会使用到的几乎全部的函数，其中经常使用的遇到的需求，几乎均可以使用easy模块来实现。在easy模块中总共定义了八个Struct,十个枚举以及数不清的函数，其中函数按照功能大概能够分为如下几类：

• 配置类函数
• 构建类函数
• 信息获取类
• 纯粹操做类
• 回调类函数

其中配置类函数占了绝大多数，这类函数主要用于设置发送请求时的请求头、验证信息等等一系列的配置选项，几乎所有是返回 Result<(), Error>,因此几乎等于没有返回值，直接每一个函数调用后unwrap一下就能够了。构建类函数主要就是new和transfer，返回一个结构体实例。信息获取类函数即调用后获取头信息之类的相关信息的函数.纯粹操做类的函数即相似于perform这类，调用后会直接将请求发出，返回无心义的Result<(), Error>，也不须要传入参数，只是单纯的提示系统该执行某个操做了。最后回调类函数即便相似write_function这类，接受一个闭包做为参数，在执行固定操做完成后便会调用该闭包函数。

示例一：简单入门

extern crate curl;
use curl::easy::Easy;
use std::io::{
   Write,
   stdout
};
fn main() {
    let mut easy = Easy::new();
    easy.url("http://juejin.im").unwrap();
    easy.write_function(|data| {
        Ok(stdout().write(data).unwrap())
    }).unwrap();
    easy.perform().unwrap();
}复制代码

这个例子中使用了curl库，而且使用了easy模块的命名空间，首先使用new函数新建了一个easy实例，而后经过url函数设置了访问的主机地址，而后继续设置了拉取到数据后的回调函数write_function,传入一个闭包函数，参数data即为服务器返回的数据，该闭包返回一个Result + Send + 'static,因此直接一条语句顺便输出了服务器返回的data，而后调用perform函数，让请求正式发出。结果以下：

upload successful

能够看出确实获取到了服务器的返回的数据，不过因为服务器作了3xx重定向，致使拉取到了一个无心义的重定向之前的页面，因此要设置让系统跟随头文件的设置一块儿跳转

示例二：跟随重定向

extern crate curl;
use curl::easy::Easy;
use std::io::{
   Write,
   stdout
};
fn main() {
    let mut easy = Easy::new();
    easy.nobody(true).unwrap();
    easy.url("http://juejin.im").unwrap();
    easy.follow_location(true).unwrap();
    easy.write_function(|data| {
        Ok(stdout().write(data).unwrap())
    }).unwrap();
    easy.perform().unwrap();
    println!("last_Url:{:?}",easy.effective_url().unwrap().unwrap());
    println!("response_code:{:?}",easy.response_code().unwrap());
    println!("http_connectcode:{:?}",easy.http_connectcode().unwrap());
    println!("filetime:{:?}",easy.filetime().unwrap());
    println!("total_time:{:?}",easy.total_time().unwrap());
}复制代码

这个例子中，经过follow_location配置设置了跟随重定向跳转，因此能够获取到掘金首页的html，不过因为内容过大，影响观看，因此这里调用了nobody函数，配置不返回body体，而后顺便在结束后打印出一部分相关的信息。

upload successful

示例三：关于回调函数

fn main() {
    let mut easy = Easy::new();
    easy.url("http://www.yzyxw.online/api/round/getQuestion").unwrap();
    easy.post(true).unwrap();
    //easy.nobody(true).unwrap();
    easy.header_function(|data| {
        print!("header: {}", str::from_utf8(data).unwrap());
        true
    }).unwrap();
    easy.write_function(|data| {
        Ok(stdout().write(data).unwrap())
    }).unwrap();
    easy.read_function(|into| {
        Ok(stdin().read(into).unwrap())
    }).unwrap();
    easy.perform().unwrap();

}复制代码

这里分别实现了读写和头三个回调，其中头回调函数会在得到http头的是后将头信息做为参数传入闭包中，这里打印出了头信息，write回调会在得到服务器返回数据后调用闭包，将服务器返回数据传入闭包参数中。特别说明：若是设置了show_header(true)，那么返回信息中会同时包含头信息。。关于读回调，主要是用于设置访问服务器时携带数据的方式之一，将标准输入数据拷贝仅回调的参数中，该数据将会被携带至服务器，为了能携带数据，这里将访问模式这是成了post。

固然，因为这里的操做都是从标准输入输出中读取的，在回调闭包中，对外部变量的借用是不被容许的，在回调外定义一个数据，在读回调中使用时不容许的，就像这样：
{% codeblock lang:rust %}
let mut info = &b"tasdasdadad"[..];
easy.read_function(|data| {
Ok(info.read(data).unwrap())
}).unwrap();
easy.perform().unwrap();
{% endcodeblock %}
结果：

upload successful

对于这种状况，该库引入了Transfer，使用transfer()会返回一个transfer实例，该实例拥有着对easy实例的一个可变借用，因此在调用该函数后一直到transfer生命周期结束前都不能够再使用easy句柄来进行一些操做，因此能够选择用大括弧将对应语句段包括起来，人为控制其生命周期。transfer一样实现了easy中全部的回调函数，用transfer能够实现上述不能实现的功能：

关于Transfer：

fn main() {
    let mut easy = Easy::new();
    easy.url("http://www.yzyxw.online/api/round/getQuestion").unwrap();
    easy.post(true).unwrap();
    //easy.nobody(true).unwrap();
    easy.header_function(|data| {
        print!("header: {}", str::from_utf8(data).unwrap());
        true
    }).unwrap();
    easy.write_function(|data| {
        Ok(stdout().write(data).unwrap())
    }).unwrap();
   let mut info = &b"tasdasdadad"[..];
    let mut tran=easy.transfer();
    tran.read_function(|data| {
        Ok(info.read(data).unwrap())
    }).unwrap();
    tran.perform().unwrap();

}复制代码

这时即可以在闭包内获取外部上下文引用

伪结语

在easy模块中共定义了七个回调设置函数，使用方式大同小异，剩下即是相关ssl验证，代理设置等等一系列的操做，基本全是经过一系列的设置函数实现的，就不一一赘述了。感兴趣的pong友们能够参考我简单翻译的api传送门,也能够参考官网比较详尽的英文api传送门.
对于该库另外一个模块multi将在本文的下篇部分详细解释，同时也将整合各个api制做一份综合实例给喜欢Rust这门目前比较小众的语言的pong友们。
另外，更多Rust库翻译请关注Rust实用库翻译计划