关于本书

目录

指南目标读者

本指南适用于 Rust 程序员新手,以便于他们可以快速了解 Rust crate 生态系统的功能。同时,本指南也适用于经验丰富的 Rust 程序员,他们可以在本指南中找到如何完成常见任务的简单提示。

如何阅读指南

指南的索引包含完整的实例列表,组织为数个章节:基础、编码、并发等。这些章节基本是按照顺序排列的;后面的章节更深入一些,并且有些实例是在前面章节的概念之上构建。

索引中,每个章节都包含实例列表。实例名称是要完成任务的简单描述,比如“在一个范围内生成随机数”;每个实例都有标记指示所使用的 crates,比如 rand-badge;以及 crate 在 crates.io 上的分类,比如 cat-science-badge

Rust 程序员新手应该按照由第一章节直至最后章节的顺序来阅读,这种方式易于理解书中的实例。同时,这样也可以对 crate 生态系统有一个全面的了解。点击索引中的章节标题,或者在侧边栏中导航到指南的章节页面。

如果你只是在简单地为一个任务的寻找解决方案,那么指南就较难以导航。找到特定实例的最简单的方法是详细查看索引,寻找感兴趣的 crate 及其类别,然后点击实例的名称来阅读它。指南的导航和浏览还在改进,以后或许会有所改善。

如何使用实例

指南的设计是为了让你能够即时访问可工作的代码,以及对其正在做什么有一个完整阐述,并指导你了解如何更进一步的信息。

指南中的所有实例都是完整的、可独立运行的程序,因此你可以直接复制它们到自己的项目中进行试验。为此,请按照以下说明进行操作。

考虑这个实例:“在一个范围内,生成随机数”:

rand-badge cat-science-badge

use rand::Rng;

fn main() {
    let mut rng = rand::thread_rng();
    println!("Random f64: {}", rng.gen::<f64>());
}

欲在本地使用,我们可以运行以下命令来创建一个新的 cargo 项目,并切换到该目录:

cargo new my-example --bin
cd my-example

然后,我们还需要添加必要的 crate 到 Cargo.toml 中(译者注:了解更多请阅读 Cargo 中文文档,关于 Cargo.toml 详细信息也可参阅 Cargo.toml 与 Cargo.lock 中文文档),如上面实例代码顶部的 crate 标志所示,在本例中仅使用了 “rand” crate。为了增加 “rand” crate,我们将使用 cargo add 命令,该命令由 cargo-edit crate 提供,我们需要先安装它:

cargo install cargo-edit
cargo add rand

接下来,可以使用实例代码替换 src/main.rs 文件的全部内容,并通过如下命令运行:

cargo run

亲,成功执行了吧?你已经是一个 Rustacean(Rust 开发者)了!——此处应该有掌声 :-)

上面实例代码顶部的 crate 标志,链接到了 crate 在站点 docs.rs 上的完整文档,通常你在决定使用那个 crate 组件后,应该阅读一下它的文档。

关于错误处理

正确处理时,Rust 中的错误处理是健壮的,但在现今的 Rust 中,它需要大量的模板文件。正因为如此,你会发现 Rust 实例中经常充满了 unwrap 调用,而不是正确的错误处理。

由于本指南旨在提供原样重用的实例,并鼓励最佳实践。因此当涉及到 Result 类型时,它们可以正确地设置错误处理。

我们使用的基本模式是有一个 fn main() -> Result 函数签名。

错误处理的结构,通常如下:

use error_chain::error_chain;
use std::net::IpAddr;
use std::str;

error_chain! {
    foreign_links {
        Utf8(std::str::Utf8Error);
        AddrParse(std::net::AddrParseError);
    }
}

fn main() -> Result<()> {
    let bytes = b"2001:db8::1";

    // Bytes 格式化为 string
    let s = str::from_utf8(bytes)?;

    // String 解析为 IP address
    let addr: IpAddr = s.parse()?;

    println!("{:?}", addr);
    Ok(())
}

使用 error_chain! 宏自定义 ErrorResult 类型,以及来自两种标准库的错误类型的自动转换。自动转换使得 ? 操作符正常运作。

在默认情况下——基于可读性目的——错误处理模板是隐藏的,如下代码所示。要阅读完整代码,请单击位于代码段右上角的“展开”()按钮。

use error_chain::error_chain;

use url::{Url, Position};

error_chain! {
    foreign_links {
        UrlParse(url::ParseError);
    }
}

fn main() -> Result<()> {
    let parsed = Url::parse("https://httpbin.org/cookies/set?k2=v2&k1=v1")?;
    let cleaned: &str = &parsed[..Position::AfterPath];
    println!("cleaned: {}", cleaned);
    Ok(())
}

要了解更多关于 Rust 错误处理的背景知识,请阅读 Rust 程序设计语言(2018)中的错误处理章节,以及这篇博客文章

关于 crate 的说明

本指南的最终目的是对 Rust crate 生态系统的广泛覆盖,但目前还处于引导和演示过程中,因此覆盖范围有限。我们希望从小范围开始,然后慢慢拓展,这将有助于指南更快地成为高质量的资源,并使其在增长过程中保持一致的质量水平。

目前,本指南聚焦在标准库、以及“核心”或“基础”方面的 crate ——这些 crate 构成了最常见的编程任务,而生态系统的其它部分则是以此为基础构建的。

本指南与 Rust Libz Blitz 密切相关,后者是一个用于识别并提高 crate 质量的项目,因此它在很大程度上推迟了 crate 的选择。任何已经走完评估过程的 crate,都在本指南的撰写范围内,而且等待评估的 crate 也是如此。