原文:
annas-archive.org/md5/f8130c086c32d8a769f8fc5df1fb7bb7译者:飞龙
前言
本书关于 Rust,这是一种赋予你构建各种软件系统能力的编程语言,从底层嵌入式软件到动态 Web 应用。Rust 速度快、可靠、安全。它提供的性能和安全保证达到甚至超过了 C 和 C++,同时仍然是一种具有相对较低入门门槛的现代语言。Rust 致力于渐进式改进,结合其活跃而友好的社区,为该语言带来了光明的未来。
Rust 并非设计成一种全新的语言,也不试图重新发明轮子。相反,它是一种语言,它识别了隐藏在从未被广泛采用的研发原型语言中的独特理念。它将这些理念汇集在一起,形成了一个连贯的整体,并提供了一种实用的语言,让你能够构建安全的软件系统,同时仍然保持高效。
本书面向对象
本书面向熟悉其他命令式语言但新接触 Rust 的初学者和中级程序员。它假设你至少熟悉一种命令式编程语言,如 C、C++或 Python。了解函数式编程不是必需的,但了解其基本概念是好的。我们确保解释我们从这些语言中引入的任何概念或想法。
本书涵盖内容
第一章,Rust 入门,简要介绍了 Rust 的历史及其设计背后的动机,并涵盖了基本语言语法。本章以涵盖所有语言特性的练习结束。
第二章,使用 Cargo 管理项目,展示了 Rust 如何通过其专用的包管理器组织大型项目。这为后续章节奠定了基础。它还涵盖了与 Visual Studio Code 编辑器的集成。
第三章,测试、文档和基准测试,探讨了内置的测试框架,编写单元测试、集成测试,以及如何在 Rust 中编写文档。我们还涵盖了 Rust 代码的基准测试功能。稍后,作为最后的练习,我们将构建一个包含文档和测试的完整 crate。
第四章,类型、泛型和特质,探讨了 Rust 的表达式类型系统,并通过构建复数库来解释使用类型系统的各种方法。
第五章,内存管理和安全性,从内存管理的动机和传统低级编程语言中与内存相关的各种陷阱开始,然后转向解释 Rust 独特的编译时内存管理理念。我们还解释了 Rust 中各种智能指针类型。
第六章,错误处理,从错误处理的动机开始,探讨了其他语言中不同的错误处理模型。然后,章节检查了 Rust 的错误处理策略和类型,在探索非恢复性情况下的错误处理之前。章节最后介绍了一个实现自定义错误类型的库。
第七章,高级概念,更详细地探讨了之前章节中介绍的一些概念。它提供了关于 Rust 提供的某些类型系统抽象的底层模型的详细信息。
第八章,并发,探讨了 Rust 的标准库中的并发模型和 API,并教你如何构建没有数据竞争的高度并发程序。
第九章,使用宏进行元编程,检查了如何使用 Rust 强大且高级的宏结构编写生成代码的代码,并通过构建这两种类型的宏来概述语言的表达式宏和过程宏。
第十章,不安全 Rust 和外部函数接口,探讨了 Rust 的不安全模式以及与其他语言交互时提供的 API。示例包括从 Python、Node.js 和 C 等语言调用 Rust,以及探讨如何从其他语言调用 Rust。
第十一章,日志记录,解释了为什么日志记录是软件开发中的重要实践,回答了为什么我们需要日志框架,并探讨了 Rust 生态系统提供的可以用于帮助将日志集成到应用程序中的 crate。
第十二章,Rust 中的网络编程:同步和异步 I/O,简要介绍了网络编程。在了解了基础知识之后,章节涵盖了构建一个可以与官方 Redis 客户端通信的 Redis 服务器。最后,章节解释了如何使用标准库网络原语以及 Tokio 和 futures crate。
第十三章,使用 Rust 构建 Web 应用程序,首先探讨了 HTTP 协议,并使用 hyper crate 构建了一个简单的 URL 缩短服务器,随后使用 reqwest crate 构建了一个 URL 缩短客户端。最后,我们探讨了 actix-web,这是一个高性能的异步 Web 应用程序框架,用于构建书签 API 服务器。
第十四章,在 Rust 中使用数据库交互,从对数据库后端应用程序需求的分析开始,进而探讨 Rust 生态系统中可用于与各种数据库后端(如 SQLite 和 PostgreSQL)交互的可用 crate。本章还探讨了名为 diesel 的类型安全 ORM crate。随后,它介绍了如何将上一章中构建的 bookmarks API 服务器集成到数据库支持中,使用 diesel 进行集成。
第十五章,使用 WebAssembly 在 Web 上使用 Rust,解释了 WebAssembly 是什么以及开发者如何使用它。然后,我们继续探讨 Rust 生态系统中可用的 crate,并使用 Rust 和 WebAssembly 构建一个实时 markdown 编辑器 Web 应用程序。
第十六章,使用 Rust 构建桌面应用程序,解释了如何使用 GTK 框架使用 Rust 构建桌面应用程序。我们将构建一个简单的 hacker-news 桌面客户端。
第十七章,调试,探讨了使用 GDB 调试 Rust 代码,并展示了如何将 GDB 与 Visual Studio Code 编辑器集成。
充分利用本书
要真正掌握本书的内容,建议您写下示例代码,并尝试修改代码以熟悉 Rust 的错误消息,这样它们可以指导您编写正确的程序。
本书没有特定的硬件要求,任何具有至少 1 GB RAM 和相当新版的 Linux 操作系统的系统都适用。本书中的所有代码示例和项目都是在运行 Ubuntu 16.04 的 Linux 机器上开发的。Rust 还提供了对其他操作系统平台的一流支持,包括 macOS、BSD 和 Windows 的最新版本,因此所有代码示例也应该在这些平台上编译和运行良好。
下载示例代码文件
您可以从www.packt.com的账户下载本书的示例代码文件。如果您在其他地方购买了此书,您可以访问www.packt.com/support并注册,以便将文件直接通过电子邮件发送给您。
您可以通过以下步骤下载代码文件:
-
在www.packt.com登录或注册。
-
选择支持选项卡。
-
点击代码下载与勘误。
-
在搜索框中输入书籍名称,并遵循屏幕上的说明。
下载文件后,请确保使用最新版本的软件解压缩或提取文件夹:
-
WinRAR/7-Zip for Windows
-
Zipeg/iZip/UnRarX for Mac
-
7-Zip/PeaZip for Linux
本书代码包也托管在 GitHub 上,网址为 github.com/PacktPublishing/Mastering-RUST-Second-Edition。如果代码有更新,它将在现有的 GitHub 仓库中更新。如果您在编译代码示例时遇到任何问题,请随时在 GitHub 上提出问题。
我们还有其他来自我们丰富的图书和视频目录的代码包,可在 github.com/PacktPublishing/ 上找到。查看它们吧!
使用的约定
本书使用了多种文本约定。
CodeInText:表示文本中的代码单词、数据库表名、文件夹名、文件名、文件扩展名、路径名、虚拟 URL、用户输入和 Twitter 昵称。以下是一个示例:“项目位于Chapter08/目录下的名为threads_demo的文件夹中。”
代码块设置如下:
fn main() {
println!("Hello Rust!");
}
当我们希望您注意代码块中的特定部分时,相关的行或项目将以粗体显示:
[dependencies]
serde = "1.0.8"
crossbeam = "0.6.0"
typenum = "1.10.0"
任何命令行输入或输出都按以下方式编写:
$ rustc main.rs
$ cargo build
粗体:表示新术语、重要单词或屏幕上看到的单词。例如,菜单或对话框中的单词在文本中显示如下。以下是一个示例:“从管理面板中选择系统信息。”
警告或重要注意事项显示如下。
小技巧和技巧显示如下。
联系我们
读者反馈始终欢迎。
一般反馈:如果您对本书的任何方面有疑问,请在邮件主题中提及书名,并将邮件发送至 customercare@packtpub.com.
勘误表:尽管我们已经尽最大努力确保内容的准确性,但错误仍然可能发生。如果您在这本书中发现了错误,我们将不胜感激,如果您能向我们报告这一错误。请访问 www.packt.com/submit-errata,选择您的书籍,点击勘误表提交表单链接,并输入详细信息。
盗版:如果您在互联网上以任何形式发现我们作品的非法副本,我们将不胜感激,如果您能提供位置地址或网站名称。请通过 copyright@packt.com 联系我们,并提供材料的链接。
如果您有兴趣成为作者:如果您在某个领域有专业知识,并且您有兴趣撰写或为书籍做出贡献,请访问 authors.packtpub.com.
评论
请留下评论。一旦您阅读并使用过这本书,为何不在您购买它的网站上留下评论?潜在读者可以查看并使用您的客观意见来做出购买决定,Packt 可以了解您对我们产品的看法,我们的作者也可以看到他们对书籍的反馈。谢谢!
如需了解更多关于 Packt 的信息,请访问 packt.com.
第一章:Rust 入门
学习一门新语言就像建造一座房子——基础需要牢固。使用一门能改变你思考代码方式的语言,一开始总是需要更多的努力,并且重要的是要意识到这一点。然而,最终的结果是,你可以通过这些新发现的概念和工具来转变你的思维方式。
本章将带你快速了解 Rust 的设计理念,其语法和类型系统的概述。我们假设你具备主流语言(如 C、C++或 Python)的基本知识,以及围绕面向对象编程的思想。每个部分都将包含示例代码及其解释。将有大量的代码示例和编译器的输出,帮助你熟悉这门语言。我们还将简要介绍这门语言的历史以及它如何持续发展。
熟悉一门新语言需要毅力、耐心和实践。我强烈建议所有读者手动编写代码,而不是复制粘贴这里列出的代码示例。编写和调试 Rust 代码的最好部分是来自编译器的精确且有用的错误信息,Rust 社区通常喜欢称之为错误驱动开发。在这本书的整个过程中,我们将频繁地看到这些错误,以了解编译器是如何看待我们的代码的。
在本章中,我们将涵盖以下主题:
-
Rust 是什么,为什么你应该关心?
-
安装 Rust 编译器和工具链
-
语言及其语法的简要概述
-
最后的练习,我们将把所学的内容综合运用
Rust 是什么,为什么你应该关心?
“Rust 是来自过去的科技,用来拯救未来免于自身的问题。”
* - 格雷顿·霍华德*
Rust 是一种快速、并发、安全且赋予力量的编程语言,最初由 Graydon Hoare 在 2006 年启动并开发。现在它是一个开源语言,主要由来自 Mozilla 的团队开发,同时得到了许多开源人士的合作。第一个稳定版本 1.0 在 2015 年 5 月发布。该项目始于缓解 C++ 在 gecko 中使用时出现的内存安全问题。Gecko 是 Mozilla Firefox 浏览器中使用的浏览器引擎。C++ 并非易驯的语言,其并发抽象容易被误用。由于 Gecko 使用 C++,在 2009 年和 2011 年尝试并行化其 级联样式表(CSS)解析代码以利用现代并行 CPU 时失败了。这是因为并发的 C++ 代码难以维护和推理。在众多开发者共同协作于 gecko 的庞大代码库时,用 C++ 编写并发代码并非易事。为了逐步消除 C++ 的痛苦部分,Rust 诞生了,随之而来的是 Servo,一个从头开始创建浏览器引擎的新研究项目。Servo 项目通过使用最前沿的语言特性为语言团队提供反馈,反过来,这些特性又影响了语言的发展。大约在 2017 年 11 月,Servo 项目的部分内容,尤其是 stylo 项目(一个用 Rust 编写的并行 CSS 解析器),开始随最新的 Firefox 版本(Project Quantum)发布,这在如此短的时间内是一项了不起的成就。Servo 的最终目标是逐步用其组件替换 gecko 中的组件。
Rust 吸收了许多语言的灵感,其中最值得注意的是 Cyclone(C 语言的安全方言)在基于区域的内存管理技术方面的理念;C++ 在 RAII 原则方面,以及 Haskell 在类型系统、错误处理类型和类型类方面。
RAII 代表 资源获取即初始化,这是一种范式,表明资源必须在对象的初始化期间获取,并在它们的析构函数被调用或它们被释放时必须释放。
该语言具有非常小的运行时,不需要垃圾回收,并且默认优先使用栈分配(相对于堆分配的额外开销)来分配任何在程序中声明的值。我们将在 第五章 中解释所有这些内容,内存管理和安全性。Rust 编译器 rustc 最初是用 Ocaml(一种函数式语言)编写的,并在 2011 年成为自宿主编译器,那时它已经用自己编写了。
自宿主编译器是指通过编译其自己的源代码来构建编译器。这个过程被称为编译器的引导。编译器自己的源代码作为编译器的一个非常好的测试用例。
Rust 语言在 GitHub 上公开开发,地址为 github.com/rust-lang/rust,并且以较快的速度持续进化。新特性通过社区驱动的请求评论(RFC)流程添加到语言中,任何人都可以提出新的语言特性。这些特性随后在 RFC 文档中详细描述。然后,对 RFC 进行共识寻求,如果达成一致,则开始该特性的实施阶段。实施后的特性将由社区进行审查,最终在经过用户在夜间版本中的多次测试后,合并到主分支。从社区获取反馈对于语言的进化至关重要。每六周,编译器会发布一个新的稳定版本。除了快速移动的增量更新外,Rust 还具有版本的概念,旨在为语言提供综合更新。这包括工具、文档、其生态系统,以及逐步引入任何破坏性变更。到目前为止,已经有两个版本:Rust 2015,该版本侧重于稳定性,以及Rust 2018,这是撰写本书时的当前版本,侧重于生产力。
尽管 Rust 是一种通用多范式语言,但它旨在系统编程领域,在这个领域 C 和 C++一直占据主导地位。这意味着你可以用它来编写操作系统、游戏引擎以及许多性能关键型应用。同时,它也足够表达,你可以用它构建高性能的 Web 应用、网络服务、类型安全的数据库对象关系映射器(ORM)库,并且可以通过编译成 WebAssembly 在 Web 上运行。Rust 在构建用于嵌入式平台的安全关键型、实时应用方面也获得了相当的关注,例如基于 Arm 的 Cortex-M 的微控制器,目前这个领域主要被 C 所主导。Rust 在各种领域中的应用范围——它表现得相当出色——在单一编程语言中是非常罕见的。此外,像 Cloudflare、Dropbox*、Chuckfish*、npm 等知名公司已经在他们的高风险项目中将其用于生产。
Rust 被描述为一种静态和强类型语言。静态属性意味着编译器在编译时对所有变量及其类型都有信息,并在编译时进行大部分检查,只在运行时进行非常少的类型检查。其强类型特性意味着它不允许类型之间的自动转换,例如,一个指向整数的变量不能在代码的后续部分被改变为指向字符串。例如,在弱类型语言如 JavaScript 中,你可以轻松地做类似以下操作:two = "2"; two = 2 + two;。JavaScript 在运行时会将 2 的类型弱化为字符串,从而将 22 作为字符串存储在 two 中,这与你的意图完全相反,并且毫无意义。在 Rust 中,相同的代码,即 let mut two = "2"; two = 2 + two;,将在编译时被捕获,并抛出以下错误:cannot add &strto{integer}``。这一特性使得代码重构更加安全,并在编译时而不是在运行时捕获大多数错误。
使用 Rust 编写的程序既具有很高的表达性,又具有高性能,这意味着你可以拥有类似于高阶函数和惰性迭代器等高级函数式语言的大多数特性,同时它编译后的代码效率又像 C/C++ 程序一样高效。支撑其许多设计决策的核心理念是编译时内存安全、无畏并发和零成本抽象。让我们详细阐述这些观点。
编译时内存安全:Rust 编译器可以在编译时跟踪程序中拥有资源的变量,并且这一切都不需要垃圾回收器来完成。
资源可以是内存地址、一个持有值的变量、共享内存引用、文件句柄、网络套接字或数据库连接句柄。
这意味着你不会在运行时遇到指针使用后释放、重复释放或悬垂指针等臭名昭著的问题。Rust 中的引用类型(在它们前面有 & 的类型)隐式地关联着一个生命周期标签(例如 `‘foo’),有时程序员还会显式地对其进行注释。通过生命周期,编译器可以跟踪代码中可以安全使用引用的地方,如果发现非法使用,则在编译时报告错误。为了实现这一点,Rust 通过在引用上使用这些生命周期标签来运行借用/引用检查算法,确保你永远不能访问已经被释放的内存地址。它还确保在某个变量使用指针时,你不能释放该指针。我们将在第五章“内存管理和安全性”中详细介绍这一点。
零成本抽象:编程全部关于管理复杂性,而良好的抽象有助于简化这一点。让我们通过 Rust 和 Kotlin(一个针对 Java 虚拟机(JVM)的语言,它允许我们编写高级代码,易于阅读和推理)中抽象的一个优秀例子来探讨抽象。我们将比较 Kotlin 的流和 Rust 的迭代器在操作数字列表时的表现,并对比 Rust 提供的零成本抽象原则。这里的抽象是能够使用接受其他方法作为参数的方法来根据条件过滤数字,而不使用手动循环。在这里使用 Kotlin 是因为它与 Rust 的视觉相似性。代码相当简单易懂,我们的目标是给出一个高级解释。我们将略过代码的细节,因为整个例子的主要目的是理解零成本属性。
首先,让我们看看 Kotlin 中的代码(以下代码可以在线运行:try.kotlinlang.org):
1\. import java.util.stream.Collectors
2\.
3\. fun main(args: Array<String>) {
5\. // Create a stream of numbers
6\. val numbers = listOf(1, 2, 3, 4, 5, 6, 7, 8, 9, 10).stream()
7\. val evens = numbers.filter { it -> it % 2 == 0 }
8\. val evenSquares = evens.map { it -> it * it }
9\. val result = evenSquares.collect(Collectors.toList())
10\. println(result) // prints [4,16,36,64,100]
11\.
12\. println(evens)
13\. println(evenSquares)
14\. }
我们创建一个数字流(第 6 行)并调用一系列方法(filter 和 map)来转换元素,只收集偶数的平方。这些方法可以接受一个闭包或函数(即第 8 行的 it -> it * it)来转换集合中的每个元素。在函数式风格的语言中,当我们对流/迭代器调用这些方法时,对于每个这样的调用,语言都会创建一个中间对象来保持与正在执行的操作相关的任何状态或元数据。因此,evens 和 evenSquares 将是两个不同的中间对象,它们在 JVM 堆上分配。在堆上分配东西会产生内存开销。这就是我们在 Kotlin 中必须支付的抽象额外成本!
当我们打印 evens 和 evenSquares 的值时,我们确实得到不同的对象,如下所示:
java.util.stream.ReferencePipeline$Head@51521cc1
java.util.stream.ReferencePipeline$3@1b4fb997
@ 符号后面的十六进制值是在 JVM 上对象的哈希码。由于哈希码不同,它们是不同的对象。
在 Rust 中,我们做同样的事情(以下代码可以在线运行:gist.github.com/rust-play/e0572da05d999cfb6eb802d003b33ffa):
1\. fn main() {
2\. let numbers = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10].into_iter();
3\. let evens = numbers.filter(|x| *x % 2 == 0);
4\. let even_squares = evens.clone().map(|x| x * x);
5\. let result = even_squares.clone().collect::<Vec<_>>();
6\. println!("{:?}", result); // prints [4,16,36,64,100]
7\. println!("{:?}\n{:?}", evens, even_squares);
8\. }
略过细节,在第 2 行我们调用 vec![] 来在堆上创建一个数字列表,然后调用 into_iter() 来使其成为数字的迭代器/流。into_iter() 方法从一个集合(在这里,Vec <i32> 是一个有符号 32 位整数的列表)创建一个包装迭代器类型,IntoIter([1,2,3,4,5,6,7,8,9,10])。这个迭代器类型引用原始数字列表。然后我们执行过滤和映射转换(第 3 和 4 行),就像我们在 Kotlin 中做的那样。第 7 和 8 行打印 evens 和 even_squares 的类型,如下(为了简洁起见,省略了一些细节):
evens: | Filter { iter: IntoIter( <numbers> ) } |
|---|---|
even_squares: | Map { iter: Filter { iter: IntoIter( <numbers> ) }} |
中间对象Filter和Map是包装类型(不在堆上分配),它们本身是包装器,持有对第 2 行原始数字列表的引用。在第 4 行和第 5 行调用filter和map时创建的包装器结构之间没有任何指针间接引用,并且不产生堆分配开销,这与 Kotlin 的情况不同。所有这些都归结为高效的汇编代码,这与手动使用循环编写的版本相当。
无畏并发:当我们说 Rust 是并发安全的,我们的意思是该语言具有应用程序编程接口(API)和抽象,使得编写正确且安全的并发代码变得非常容易。与 C++相比,编写并发代码时出错的可能性相当高。在 C++中对多个线程的数据访问进行同步时,你需要负责每次进入临界区时调用mutex.lock(),并在退出该区域时调用mutex.unlock():
// C++
mutex.lock(); // Mutex locked, good to go
// Do super critical stuff
mutex.unlock(); // We're done
临界区:这是一组需要原子执行的指令/语句。在这里,“原子”意味着没有其他线程可以中断临界区中当前正在执行的线程,并且在临界区代码执行期间,任何线程都不会感知到中间值。
在一个大型代码库中,许多开发者协作编写代码,你可能会忘记在从多个线程访问共享对象之前调用mutex.lock(),这可能导致数据竞争。在其他情况下,你可能会忘记解锁mutex,导致其他想要访问数据的线程饥饿。
Rust 对此有不同的看法。在这里,你将数据包裹在Mutex类型中,以确保从多个线程对数据进行同步可变访问:
// Rust
use std::sync::Mutex;
fn main() {
let value = Mutex::new(23);
*value.lock().unwrap() += 1; // modify
} // unlocks here automatically
在前面的代码中,我们在对 value 调用 lock() 之后能够修改数据。Rust 使用保护共享数据本身而不是代码的概念。与 C++ 不同,与 Mutex 和受保护数据的交互不是独立的。你不能在不调用 Mutex 类型的 lock 的情况下访问内部数据。那么释放锁呢?好吧,调用 lock() 会返回一个名为 MutexGuard 的东西,当变量超出作用域时会自动释放锁。这是 Rust 提供的许多安全并发抽象之一。我们将在 第八章 中详细介绍它们,即 并发。另一个新颖的想法是标记特性概念,它在编译时验证并确保并发代码中对数据的同步和安全的访问。特性在 第四章 中详细描述,类型、泛型和特性。类型使用标记特性 Send 和 Sync 进行注释,以指示它们是否可以安全地发送到线程或线程之间共享。当程序向线程发送值时,编译器会检查该值是否实现了所需的标记特性,如果未实现,则禁止使用该值。这样,Rust 允许你编写无需担心的并发代码,在编译时编译器会捕获多线程代码中的错误。编写并发代码已经很困难了。使用 C/C++,它变得更加困难且晦涩。CPU 的时钟频率并没有增加;相反,我们增加了更多的核心。因此,并发编程是未来的方向。Rust 使编写并发代码变得轻而易举,并降低了许多人编写安全并发代码的门槛。
Rust 还采用了 C++ 的 RAII 习惯用法进行资源初始化。这种技术基本上将资源的生命周期与对象的生存周期绑定在一起,而堆分配类型的释放则是通过 drop 方法来完成的,该方法由 drop 特性提供。当变量超出作用域时,它会自动调用。它还用 Result 和 Option 类型替换了空指针的概念,我们将在 第六章 中详细介绍,即 错误处理。这意味着 Rust 不允许代码中出现空/未定义的值,除非通过外部函数接口与其他语言交互,或者在使用不安全代码时。该语言还强调组合优于继承,并具有一个特性系统,该系统由数据类型实现,类似于 Haskell 类型类,也称为增强版的 Java 接口。Rust 中的特性是其许多功能的支柱,正如我们将在接下来的章节中看到的。
最后但同样重要的是,Rust 的社区非常活跃和友好,该语言有全面的文档,可以在 doc.rust-lang.org 找到。连续三年(2016、2017 和 2018 年),Stack Overflow 的开发者调查将 Rust 评为最受欢迎的编程语言,因此可以说整个编程社区都非常关注它。总的来说,如果你旨在编写高性能软件,同时享受许多现代语言特性和一个出色的社区,那么你应该关注 Rust!
安装 Rust 编译器和工具链
Rust 工具链有两个主要组件:编译器 rustc 和包管理器 cargo,它有助于管理 Rust 项目。工具链有三个发布渠道:
-
Nightly:来自主开发分支的每日成功构建。这包含了所有最新的功能,其中许多是不稳定的。
-
Beta:每六周发布一次。从一个新的 beta 分支中提取。它只包含标记为稳定的特性。
-
Stable:每六周发布一次。之前的 beta 分支成为新的稳定发布。
鼓励开发者使用稳定发布渠道。然而,nightly 版本提供了前沿特性,某些库和程序需要它。你可以使用 rustup 轻松切换到 nightly 工具链。我们稍后将看到如何做到这一点。
使用 rustup.rs
Rustup 是一个工具,用于在所有支持的平台上安装 Rust 编译器。为了使不同平台上的开发者更容易下载和使用该语言,Rust 团队开发了 rustup。它是一个用 Rust 编写的命令行工具,提供了一种简单的方式来安装编译器的预构建二进制文件和用于交叉编译的标准库的二进制构建。它还可以安装其他组件,例如 Rust 源代码、文档、Rust 格式化工具(rustfmt)、Rust 语言服务器(RLS 用于 IDEs),以及其他开发者工具,并且它在所有平台上运行,包括 Windows。
从他们的官方页面 rustup.rs 可以看到,安装工具链的推荐方法是运行以下命令:
curl https://sh.rustup.rs -sSf | sh
默认情况下,安装程序会安装 Rust 编译器的稳定版本、其包管理器 Cargo 以及语言的标准化库文档,以便可以离线查看。这些默认安装在 ~/.cargo 目录下。Rustup 还会更新你的 PATH 环境变量,使其指向此目录。
以下是在 Ubuntu 16.04 上运行先前命令的截图:
如果你需要对你的安装进行任何更改,请选择 2。然而,默认设置对我们来说已经足够好了,所以我们将继续选择 1。以下是安装后的输出:
Rustup 还具有其他功能,例如通过运行 rustup update 更新工具链到最新版本。它也可以通过 rustup self update 更新自身。它还提供了特定目录的工具链配置。默认工具链被全局设置为安装的工具链,在大多数情况下是稳定版工具链。你可以通过调用 rustup show 来查看默认的工具链。如果你想为你的某个项目使用最新的夜间版工具链,你可以通过运行 rustup override set nightly 告诉 rustup 为特定目录切换到夜间版。如果出于某种原因,有人想使用工具链的旧版本或降级(比如,2016-06-03 的夜间构建),如果运行 rustup install nightly-2016-06-03,rustup 也可以下载它,然后通过 override 子命令设置相同的版本。有关 rustup 的更多信息,请参阅 github.com/rust-lang-nursery/rustup.rs。
注意:本书中的所有代码示例和项目都是基于编译器版本 rustc 1.32.0 (9fda7c223 2019-01-16)。
现在,你应该已经拥有了编译和运行 Rust 编写的程序所需的一切。让我们开始 Rust 之旅吧!
语言之旅
对于基本语言特性,Rust 并没有偏离你在其他语言中习惯的内容太远。在高级层面,一个 Rust 程序被组织成模块,其中根模块包含一个 main() 函数。对于可执行文件,根模块通常是 main.rs 文件,而对于库,则是 lib.rs 文件。在一个模块内部,你可以定义函数、导入库、定义类型、创建常量、编写测试和宏,甚至创建嵌套模块。我们将逐一了解它们,但让我们从基础开始。这是一个简单的 Rust 程序,用于问候你:
// greet.rs
1\. use std::env;
2\.
3\. fn main() {
4\. let name = env::args().skip(1).next();
5\. match name {
6\. Some(n) => println!("Hi there ! {}", n),
7\. None => panic!("Didn't receive any name ?")
8\. }
9\. }
让我们编译并运行这个程序。将其写入名为 greet.rs 的文件中,并使用文件名运行 rustc,然后将你的名字作为参数传递。我传递了名字 Ferris,这是 Rust 的非官方吉祥物,在我的机器上得到了以下输出:
太棒了!它问候了 Ferris。让我们逐行浏览这个程序。
在第 1 行,我们从 std crate(库被称为 crate)中导入了一个名为 env 的模块。std 是 Rust 的标准库。在第 3 行,我们有我们常用的 main 函数。然后,在第 4 行,我们调用 env 模块中的 args() 函数,该函数返回一个迭代器(序列),其中包含传递给我们的程序的参数。由于第一个参数包含我们的程序名称,我们想要跳过它,所以我们调用 skip 并传入一个数字,这表示我们要跳过多少个元素(1)。由于迭代器在 Rust 中是惰性的,不会预先计算任何东西,因此我们必须明确要求它提供下一个元素,所以我们调用 next(),它返回一个名为 Option 的枚举类型。这可以是 Some(value) 值或 None 值,因为用户可能会忘记提供参数。
在第 5 行,我们使用 Rust 的强大 match 表达式对变量 name 进行操作,并检查它是否是 Some(n) 或 None 值。match 与 if else 构造类似,但更强大。在第 6 行,当它是 Some(n) 时,我们调用 println!(),传入我们的内部字符串变量 n(当使用 match 表达式时,它会自动声明),然后问候我们的用户。println! 调用不是一个函数,而是一个 宏(它们都以 ! 结尾)。最后,在第 7 行,如果它是枚举的 None 变体,我们只是 panic!()(另一个宏),这会导致程序终止,并留下一个错误消息。
println! 宏,正如我们所见,接受一个字符串,该字符串可以使用 "{}" 语法包含用于项的占位符。这些字符串被称为 格式字符串,而字符串中的 "{}" 被称为 格式说明符。对于打印简单类型,如原始类型,我们可以使用 "{}" 格式说明符,而对于其他类型,我们使用 "{:?}" 格式说明符。不过,这里还有一些细节。当 println! 遇到格式说明符,即 "{}",以及相应的替换值时,它会调用该值上的一个方法,该方法返回其字符串表示形式。这个方法是 trait 的一部分。对于 "{}" 说明符,它调用 Display trait 中的方法,而对于 "{:?}",它调用 Debug trait 中的方法。后者主要用于调试,而前者用于显示数据类型的人类可读输出。这与 Java 中的 toString() 方法有些相似。在开发过程中,你通常需要打印数据类型以进行调试。当使用 "{:?}" 说明符时,如果这些方法在类型上不可用,我们则需要在该类型上添加一个 #[derive(Debug)] 属性来获取这些方法。我们将在后续章节中详细解释属性,但预计你将在未来的代码示例中看到这一点。我们还将回顾第九章中的 println! 宏,使用宏进行元编程。
手动运行 rustc 并非真实程序的正确做法,但对于本章中的这些小程序来说,这样做是可以的。在后续章节中,我们将使用 Rust 的包管理器来构建和运行我们的程序。除了在本地运行编译器之外,还可以使用官方在线编译器 Rust playground 来运行代码示例,该编译器可以在 play.rust-lang.org 找到。以下是我机器上的截图:
Rust playground 还支持导入和使用外部库,以便在尝试示例程序时使用。
在前面的示例中,我们得到了一个基本的 Rust 程序的高级概述,但没有深入所有细节和语法。在下一节中,我们将分别解释语言特性和它们的语法。以下解释旨在为您提供足够的背景知识,以便您能够快速开始编写 Rust 程序,而无需详尽地了解所有用例。为了简洁起见,每个部分还包含对解释这些概念的章节的引用。此外,Rust 文档页面 doc.rust-lang.org/std/index.html 将帮助您深入了解,并且具有内置的搜索功能,非常易于阅读。鼓励您积极搜索以下章节中解释的任何结构。这将帮助您更好地理解您正在学习的概念。
本章中的所有代码示例都可以在本书的 GitHub 仓库中找到 (PacktPublishing/Mastering-RUST-Second-Edition)。对于本章,它们位于 第一章,Rust 入门 目录 – 本书其余章节也遵循相同的约定。
一些代码文件被故意设计为无法编译,这样您就可以在编译器的帮助下自己修复它们。
话虽如此,让我们从 Rust 中的基本原始类型开始。
原始类型
Rust 有以下内置原始类型:
-
bool: 这些是常规布尔值,可以是true或false。 -
char: 字符,例如e。 -
整数类型:这些类型以位宽为特征。Rust 支持宽度高达 128 位的整数:
有符号 无符号 i8u8i16u16i32u32i64u64i128u128 -
isize: 指针大小的有符号整数类型。在 32 位 CPU 上相当于i32,在 64 位 CPU 上相当于i64。 -
usize: 指针大小的无符号整数类型。在 32 位 CPU 上相当于i32,在 64 位 CPU 上相当于i64。 -
f32: 32 位浮点类型。实现了 IEEE 754 浮点表示标准。 -
f64: 64 位浮点类型。 -
[T; N]:一个固定大小的数组,对于元素类型T和非负编译时常量大小 N。 -
[T]:任何类型T的连续序列的动态大小视图。 -
str:字符串切片,主要用于引用,即&str。 -
(T, U, ..):一个有限序列,其中 T 和 U 可以是不同类型。 -
fn(i32) -> i32:一个接受i32并返回i32的函数。函数也有类型。
声明变量和不可变性
变量允许我们存储一个值,并在代码中稍后轻松地引用它。在 Rust 中,我们使用 let 关键字来声明变量。我们已经在上一节的 greet.rs 示例中看到了它的身影。在主流的命令式语言,如 C 或 Python 中,初始化变量并不会阻止你将其重新赋值给其他值。Rust 在这里与主流做法不同,它默认使变量不可变,也就是说,你初始化变量后不能将其赋值给其他值。如果你需要变量稍后指向其他东西(同一类型),你需要在它前面加上 mut 关键字。Rust 要求你尽可能明确地表达你的意图。考虑以下代码:
// variables.rs
fn main() {
let target = "world";
let mut greeting = "Hello";
println!("{}, {}", greeting, target);
greeting = "How are you doing";
target = "mate";
println!("{}, {}", greeting, target);
}
我们声明了两个变量,target 和 greeting。target 是一个不可变绑定,而 greeting 前面有一个 mut,使其成为一个可变绑定。如果我们运行这个程序,则会得到以下错误:
如前述错误信息所示,Rust 不允许你再次对 target 进行赋值。为了使这个程序编译,我们需要在 let 语句中的 target 前面添加 mut,然后再次编译和运行它。以下是你运行程序时的输出:
$ rustc variables.rs
$ ./variables
Hello, world
How are you doing, mate
let 在 Rust 中做的不只是赋值变量。它是一个模式匹配语句。在 第七章 的 高级概念 中,我们将更详细地探讨 let。接下来,我们将看看函数。
函数
函数将一系列指令抽象成命名实体,可以在稍后通过其他代码调用,有助于管理复杂性。我们已经在我们的 greet.rs 程序中使用了一个函数,即 main 函数。让我们看看我们如何定义另一个函数:
// functions.rs
fn add(a: u64, b: u64) -> u64 {
a + b
}
fn main() {
let a: u64 = 17;
let b = 3;
let result = add(a, b);
println!("Result {}", result);
}
在前面的代码中,我们创建了一个名为 add 的新函数。使用 fn 关键字来创建函数,后面跟着其名称 add,括号内的参数 a 和 b,以及花括号 {} 内的函数体。参数的类型位于冒号 : 的右侧。函数的返回类型使用 -> 符号指定,后面跟着类型 u64,如果函数没有返回值,则可以省略。函数也有类型。我们的 add 函数类型表示为 fn(u64, u64) -> u64。它们也可以存储在变量中,并传递给其他函数。
如果你查看add函数的主体,我们不需要return关键字来返回a + b,就像在其他语言中那样。最后一个表达式会自动返回。然而,我们确实有return关键字可用于提前返回。函数基本上是返回值的表达式,默认情况下返回值类型为()(单元)类型,类似于 C/C++中的void返回类型。它们也可以在其他函数内声明。这种用例是当你有一个在函数内部的功能(比如foo)难以作为语句序列进行推理时。在这种情况下,可以在局部函数bar中提取这些行,然后bar在父函数foo内部定义。
在main函数中,我们使用let关键字声明了两个变量a和b。与b一样,我们甚至可以省略指定类型,因为 Rust 在大多数情况下能够通过检查你的代码来推断变量的类型。这也适用于result,它是一个u64值。这个特性有助于防止类型签名杂乱,并提高代码的可读性,尤其是在你的类型嵌套在具有长名称的其他类型内部时。
Rust 的类型推断基于 Hindley Milner 类型系统。它是一组规则和算法,使编程语言能够进行类型推断。这是一种高效的类型推断方法,以线性时间执行,使得对大型程序进行类型检查变得实用。
我们也可以有修改其参数的函数。考虑以下代码:
// function_mut.rs
fn increase_by(mut val: u32, how_much: u32) {
val += how_much;
println!("You made {} points", val);
}
fn main() {
let score = 2048;
increase_by(score, 30);
}
我们声明了一个score变量,其值为2048,并调用了increase_by函数,将score和值30作为第二个参数传递。在increase_by函数中,我们指定第一个参数为mut val,表示该参数应被视为可变的,这允许从函数内部修改变量。我们的increase_by函数修改了val绑定并打印了值。以下是运行程序时的输出:
$ rustc function_mut.rs
$ ./function_mut
You made 2078 points
接下来,让我们看看闭包。
闭包
Rust 也支持闭包。闭包类似于函数,但它们具有更多关于它们声明时的环境或作用域的信息。虽然函数与它们的名字相关联,但闭包是无名的定义,但可以赋值给变量。Rust 类型推断的另一个优点是,在大多数情况下,你可以指定闭包的参数而不需要它们的类型。这里是最简单的闭包示例:let my_closure = || ();。我们定义了一个无参数的闭包,它什么也不做。我们可以通过调用my_closure()来调用它,就像函数一样。两个垂直条||包含闭包的参数(如果有),例如|a, b|。当 Rust 无法确定正确的类型时,有时需要指定参数的类型(|a: u32|)。像函数一样,闭包也可以存储在变量中,稍后调用或传递给其他函数。然而,闭包的主体可以是一行表达式,也可以是一对花括号,用于多行表达式。一个更复杂的闭包可能如下所示:
// closures.rs
fn main() {
let doubler = |x| x * 2;
let value = 5;
let twice = doubler(value);
println!("{} doubled is {}", value, twice);
let big_closure = |b, c| {
let z = b + c;
z * twice
};
let some_number = big_closure(1, 2);
println!("Result from closure: {}", some_number);
}
在前面的代码中,我们定义了两个闭包:doubler和big_closure。doubler将给定的值加倍;在这种情况下,它从父作用域或环境(即main函数)传递value。同样,在big_closure中,我们使用其环境中的变量twice。这个闭包在花括号内有多行表达式,并且需要以分号结束,以便我们可以将其赋值给big_closure变量。稍后,我们调用big_closure,传递1, 2,并打印some_number。
闭包的主要用途是作为高阶函数的参数。高阶函数是一种接受另一个函数或闭包作为其参数的函数。例如,标准库中的thread::spawn函数接受一个闭包,在其中你可以编写你想要在另一个线程中运行的代码。另一个闭包提供便利抽象的例子是当你有一个操作集合(如Vec)的函数,而你想要根据某些条件过滤项目时。Rust 的Iterator特质有一个名为filter的方法,它接受一个闭包作为参数。这个闭包由用户定义,它返回true或false,具体取决于用户想要如何过滤集合中的项目。我们将在第七章高级概念中更深入地了解闭包。
字符串
字符串是任何编程语言中最常用的数据类型之一。在 Rust 中,它们通常以两种形式存在:&str类型(发音为stir)和String类型。Rust 字符串保证是有效的 UTF-8 编码字节序列。它们不像 C 字符串那样以空字符终止,并且可以在它们之间包含空字节。以下程序展示了这两种类型的作用:
// strings.rs
fn main() {
let question = "How are you ?"; // a &str type
let person: String = "Bob".to_string();
let namaste = String::from("नमस्ते"); // unicodes yay!
println!("{}! {} {}", namaste, question, person);
}
在前面的代码中,person和namaste是String类型,而question是&str类型。你可以用多种方式创建String类型。字符串是在堆上分配的,而&str类型通常是现有字符串的指针,这些字符串可能位于栈上、堆上或在编译对象的代码段的数据段中。&是一个用于创建任何类型的指针的运算符。在初始化前面的代码中的字符串后,我们使用println!宏通过格式字符串将它们一起打印出来。这就是字符串的非常基础的知识。字符串将在第七章,“高级概念”中详细讲解。
条件语句和决策
条件语句在其他语言中也有类似的结构。它们遵循类似于 C 语言的if {} else {}结构:
// if_else.rs
fn main() {
let rust_is_awesome = true;
if rust_is_awesome {
println!("Indeed");
} else {
println!("Well, you should try Rust !");
}
}
在 Rust 中,if结构不是一个语句,而是一个表达式。在一般的编程术语中,语句不会返回任何值,但表达式会。这种区别意味着 Rust 中的if else条件语句总是返回一个值。这个值可能是一个空的()单元类型,也可能是一个实际值。括号内最后一行剩余的内容将成为if else表达式的返回值。重要的是要注意,if和else分支应该有相同的返回类型。此外,我们不需要在if条件表达式周围使用括号,正如你可以在前面的代码中看到的那样。我们甚至可以将if else块的值赋给一个变量:
// if_assign.rs
fn main() {
let result = if 1 == 2 {
"Wait, what ?"
} else {
"Rust makes sense"
};
println!("You know what ? {}.", result);
}
当将if else表达式返回的值赋值时,我们需要在它们后面加上分号。例如,if { ...是一个表达式,而let是一个期望我们在末尾加上分号的语句。在赋值的情况下,如果我们从前面的代码中移除else {}块,编译器会抛出一个错误,如下所示:
如果没有else块,当if条件评估为false时,结果将是(),result变量将有两个可能的值,即()和&str。Rust 不允许在一个变量中存储多个类型。因此,在这种情况下,我们需要if {}和else {}块返回相同类型的值。此外,在条件分支中添加分号会改变代码的含义。在以下代码中,在if块中的字符串后添加分号,编译器会将其解释为你想要丢弃该值:
// if_else_no_value.rs
fn main() {
let result = if 1 == 2 {
"Nothing makes sense";
} else {
"Sanity reigns";
};
println!("Result of computation: {:?}", result);
}
在这种情况下,结果将是一个空的(),这就是为什么我们不得不稍微改变println!表达式(即{:?});这种类型不能以常规方式打印出来。现在,对于更复杂的多值决策;Rust 还有一个称为match表达式的强大结构,我们将在下一节中探讨。
匹配表达式
Rust 的 match 表达式非常易于使用。它基本上是 C 语言的 switch 语句的强化版,允许你根据变量的值做出决策,并且它具有先进的过滤能力。以下是一个使用匹配表达式的程序:
// match_expression.rs
fn req_status() -> u32 {
200
}
fn main() {
let status = req_status();
match status {
200 => println!("Success"),
404 => println!("Not Found"),
other => {
println!("Request failed with code: {}", other);
// get response from cache
}
}
}
在前面的代码中,我们有一个返回模拟 HTTP 请求状态码 200 的 req_status 函数,我们在 main 中调用它并将结果赋值给 status。然后我们使用 match 关键字匹配这个值,后面跟着我们想要检查的变量(status),然后是一对大括号。在大括号内,我们写表达式——这些被称为 匹配分支。这些分支代表了被匹配变量可能取的值。每个匹配分支是通过写出变量的可能值,然后跟一个 =>,再然后是右侧的表达式来编写的。在右侧,你可以有一个单行表达式或一个在大括号 {} 内的多行表达式。当写成单行表达式时,它们需要用逗号分隔。此外,每个匹配分支必须返回相同的类型。在这种情况下,每个匹配分支返回 Unit 类型 ()。
match 表达式的一个很好的特性或你可以称之为保证是,我们必须对所有可能的值进行穷举匹配。在我们的例子中,这将是列出所有直到 i32 最大值的数字。然而,实际上这是不可能的,所以 Rust 允许我们通过使用一个 catch all 变量(这里,它是 other)或一个 _(下划线)来忽略其余的可能性,如果我们想忽略这个值。当有多个可能的值时,匹配表达式是做出关于值的决策的主要方式,而且它们写起来非常简洁。像 if else 表达式一样,当用分号分隔时,匹配表达式的返回值也可以在 let 语句中分配给一个变量,并且所有匹配分支返回相同的类型。
循环
在 Rust 中,重复操作可以通过三种结构实现,即 loop、while 和 for。在所有这些结构中,我们都有常用的 continue 和 break 关键字,分别允许你跳过循环或从循环中退出。以下是一个使用 loop 的例子,它与 C 语言的 while(true) 等效:
// loops.rs
fn main() {
let mut x = 1024;
loop {
if x < 0 {
break;
}
println!("{} more runs to go", x);
x -= 1;
}
}
loop 表示一个无限循环。在前面的代码中,我们简单地递减 x 的值,直到它达到条件 x < 0,在那里我们退出循环。在 Rust 中使用 loop 的一个额外特性是能够给 loop 块加上一个标签。这可以在你有两个或更多嵌套循环,并且想要从任何一个循环中退出,而不仅仅是紧邻 break 语句的循环时使用。以下是一个使用循环标签退出 loop 的例子:
// loop_labels.rs
fn silly_sub(a: i32, b: i32) -> i32 {
let mut result = 0;
'increment: loop {
if result == a {
let mut dec = b;
'decrement: loop {
if dec == 0 {
// breaks directly out of 'increment loop
break 'increment;
} else {
result -= 1;
dec -= 1;
}
}
} else {
result += 1;
}
}
result
}
fn main() {
let a = 10;
let b = 4;
let result = silly_sub(a, b);
println!("{} minus {} is {}", a, b, result);
}
在前面的代码中,我们正在进行一个非常低效的减法操作,只是为了演示在嵌套循环中使用标签的用法。在内层'decrement标签中,当dec等于0时,我们可以传递一个标签给break(这里,这是'increment'),然后跳出外层的'increment'循环。
现在,让我们看看while循环。这里没有太多花哨的东西:
// while.rs
fn main() {
let mut x = 1000;
while x > 0 {
println!("{} more runs to go", x);
x -= 1;
}
}
Rust 也有一个for关键字,与其他语言的 for 循环类似,但在实现上却大不相同。Rust 的for实际上是一个更强大的重复构造的语法糖,称为迭代器。我们将在第七章,高级概念中更详细地讨论它们。简单来说,Rust 中的 for 循环只适用于可以转换为迭代器的类型。其中一种类型是Range类型。Range类型可以指代一个数字范围,例如(0..10)。它们可以用在 for 循环中,如下所示:
// for_loops.rs
fn main() {
// does not include 10
print!("Normal ranges: ");
for i in 0..10 {
print!("{},", i);
}
println!(); // just a newline
print!("Inclusive ranges: ");
// counts till 10
for i in 0..=10 {
print!("{},", i);
}
}
除了正常的范围语法,即0..10,它不包括10之外,Rust 还有一个包含范围语法0..=10,它迭代直到10,如第二个for循环所示。现在,让我们继续讨论用户定义的数据类型。
用户定义类型
正如其名所示,用户定义类型是由您定义的类型。这些可以由几个类型组成。它们可能是一个原始类型的包装,或者是由几个用户定义类型组成的组合。它们有三种形式:结构体、枚举和联合体,或者更常见地称为结构体、枚举和联合体。它们允许您轻松地表达您的数据。用户定义类型的命名约定遵循驼峰式风格。结构体和枚举比 C 语言的结构体和枚举更强大,而 Rust 中的联合体与 C 语言非常接近,主要是为了与 C 代码库交互。我们将在本节中介绍结构体和枚举,而联合体将在第七章,高级概念中介绍。
结构体
在 Rust 中,我们可以声明三种结构体形式。其中最简单的是单元结构体,它使用struct关键字编写,后面跟着其名称和结尾的分号。以下代码示例定义了一个单元结构体:
// unit_struct.rs
struct Dummy;
fn main() {
let value = Dummy;
}
在前面的代码中,我们定义了一个名为Dummy的单元结构体。在main函数中,我们可以仅使用其名称来初始化此类型。value现在包含了一个Dummy类型的实例,并且是一个零大小值。单元结构体在运行时不会占用任何大小,因为它们没有与之关联的数据。单元结构体的用途非常有限。它们可以用来模拟没有数据或状态关联的实体。另一个用途是使用它们来表示错误类型,其中结构体本身足以理解错误,而不需要对其描述。另一个用途是在状态机实现中表示状态。接下来,让我们看看结构体的第二种形式。
结构体的第二种形式是元组结构体,它关联着数据。在这里,各个字段没有命名,而是通过在定义中的位置来引用。假设你正在编写一个用于图形应用程序的颜色转换/计算库,并想在代码中表示RGB颜色值。我们可以这样表示我们的Color类型和相关项:
// tuple_struct.rs
struct Color(u8, u8, u8);
fn main() {
let white = Color(255, 255, 255);
// You can pull them out by index
let red = white.0;
let green = white.1;
let blue = white.2;
println!("Red value: {}", red);
println!("Green value: {}", green);
println!("Blue value: {}\n", blue);
let orange = Color(255, 165, 0);
// You can also destructure the fields directly
let Color(r, g, b) = orange;
println!("R: {}, G: {}, B: {} (orange)", r, g, b);
// Can also ignore fields while destructuring
let Color(r, _, b) = orange;
}
在前面的代码中,Color(u8, u8, u8)是一个元组结构体,它被创建并存储在white中。然后我们使用white.0语法访问white中的单个颜色组件。可以通过variable.<index>语法访问元组结构体内的字段,其中index指的是字段在结构体中的位置,从0开始。另一种访问结构体单个字段的方法是使用let语句解构结构体。在第二部分,我们创建了一个颜色orange。随后,我们编写了let语句,左侧是Color(r, g, b),右侧是我们的orange。这导致orange中的三个字段被存储在r、g和b变量中。r、g和b的类型也会自动为我们推断。
当需要建模具有不到四个或五个属性的数据时,元组结构体是一个理想的选择。超过这个数量会阻碍可读性和推理。对于具有超过三个字段的情况,建议使用类似 C 的结构体,这是第三种形式,也是最常用的形式。考虑以下代码:
// structs.rs
struct Player {
name: String,
iq: u8,
friends: u8,
score: u16
}
fn bump_player_score(mut player: Player, score: u16) {
player.score += 120;
println!("Updated player stats:");
println!("Name: {}", player.name);
println!("IQ: {}", player.iq);
println!("Friends: {}", player.friends);
println!("Score: {}", player.score);
}
fn main() {
let name = "Alice".to_string();
let player = Player { name,
iq: 171,
friends: 134,
score: 1129 };
bump_player_score(player, 120);
}
在前面的代码中,结构体是以与元组结构体相同的方式创建的,即通过写出struct关键字后跟结构体的名称。然而,它们以大括号开始,并且它们的字段声明是有名的。在大括号内,我们可以将字段写成field: type逗号分隔的对。创建结构体实例也很简单;我们写出Player,然后跟上一对大括号,其中包含逗号分隔的字段初始化。当我们从与字段名称相同的变量初始化字段时,我们可以使用字段初始化简写功能,正如前面代码中的name字段那样。然后我们可以通过使用struct.field_name语法轻松访问创建的实例的字段。在前面的代码中,我们还有一个名为bump_player_score的函数,它接受结构体Player作为参数。默认情况下,函数参数是不可变的,所以当我们想要修改玩家的分数时,我们需要在我们的函数中将参数更改为mut player,这允许我们修改其任何字段。在结构体上有mut意味着所有字段都具有可变性。
使用结构体而不是元组结构体的优点在于我们可以以任何顺序初始化字段。它还允许我们为字段提供有意义的名称。作为旁注,结构体的大小仅仅是其各个字段成员的总和,以及如果需要的话,任何数据对齐填充。它们与它们没有任何额外的元数据大小开销相关联。接下来,让我们看看枚举,也称为枚举。
枚举
当你需要对一个可以有多种类型的对象进行建模时,枚举是最佳选择。它们通过使用enum关键字,后跟枚举名称,然后是一对花括号来创建。在花括号内,我们可以写出该类型的所有可能性,这些被称为变体。这些变体可以带或不带包含在其中的数据定义,包含的数据可以是任何原始类型、结构体、元组结构体,甚至是枚举。然而,在递归情况下,当你有一个枚举Foo和一个包含Foo的变体时,这个变体需要位于一个指针类型(如Box、Rc等)之后,以避免有递归无限类型定义。因为枚举也可以在栈上创建,所以它们需要有一个预定的尺寸,无限类型定义使得在编译时无法确定大小。现在,让我们看看如何创建一个枚举:
// enums.rs
enum Direction {
N,
E,
S,
W
}
enum PlayerAction {
Move {
direction: Direction,
speed: u8
},
Wait,
Attack(Direction)
}
fn main() {
let simulated_player_action = PlayerAction::Move {
direction: Direction::N,
speed: 2,
};
match simulated_player_action {
PlayerAction::Wait => println!("Player wants to wait"),
PlayerAction::Move { direction, speed } => {
println!("Player wants to move in direction {:?} with speed {}",
direction, speed)
}
PlayerAction::Attack(direction) => {
println!("Player wants to attack direction {:?}", direction)
}
};
}
上述代码定义了两种枚举类型:Direction和PlayerAction。然后我们通过选择任何变体,例如Direction::N或PlayerAction::Wait,使用双冒号::在它们之间创建它们的实例。请注意,我们不能有一个未初始化的枚举,它必须是其中一个变体。给定一个枚举值,要查看枚举实例具有哪个变体,我们使用模式匹配通过使用match表达式。当我们对枚举进行匹配时,我们可以通过将变量放在字段如PlayerAction::Attack(direction)中的direction等字段的位置来直接解构变体的内容,这反过来意味着我们可以在我们的匹配分支中使用它们。
正如你在我们之前的Direction枚举中看到的那样,我们有一个#[derive(Debug)]注解。这是一个属性,它允许Direction实例使用println!()中的{:?}格式字符串进行打印。这是通过从名为Debug的特质生成方法来完成的。编译器会告诉我们是否缺少Debug特质,并给出有关如何修复的建议,因此我们需要在那里使用这个属性:
从函数式程序员的视角来看,结构和枚举也被称为代数数据类型(ADTs),因为它们可以表示的可能值的范围可以用代数规则来表示。例如,枚举被称为求和类型,因为它可以持有的值范围基本上是其变体值范围的求和,而结构被称为积类型,因为其可能的值范围是其各个字段值范围的笛卡尔积。在一般讨论它们时,我们有时会称它们为 ADTs。
类型上的函数和方法
没有行为的类型可能有限制,通常我们希望在类型上有函数或方法,这样我们就可以返回它们的新实例而不是手动构建它们,或者这样我们就有能力操作用户定义类型的字段。我们可以通过impl 块来实现这一点,这可以理解为为类型提供实现。我们可以为所有用户定义类型或任何包装类型提供实现。首先,让我们看看如何为结构编写实现。
结构上的 Impl 块
我们可以通过两种功能向先前定义的Player结构添加行为:一个类似于构造函数的函数,它接受一个名称并设置Person中剩余字段的默认值,以及Person的 getter 和 setter 方法来设置朋友数量:
// struct_methods.rs
struct Player {
name: String,
iq: u8,
friends: u8
}
impl Player {
fn with_name(name: &str) -> Player {
Player {
name: name.to_string(),
iq: 100,
friends: 100
}
}
fn get_friends(&self) -> u8 {
self.friends
}
fn set_friends(&mut self, count: u8) {
self.friends = count;
}
}
fn main() {
let mut player = Player::with_name("Dave");
player.set_friends(23);
println!("{}'s friends count: {}", player.name, player.get_friends());
// another way to call instance methods.
let _ = Player::get_friends(&player);
}
我们使用impl关键字,后跟我们要实现方法的类型,然后是花括号。在花括号内,我们可以编写两种方法:
- 关联方法:没有
self类型作为其第一个参数的方法。with_name方法被称为关联方法,因为它没有self作为第一个参数。它类似于面向对象语言中的静态方法。这些方法在类型本身上可用,并且不需要类型的实例来调用它们。关联方法通过在方法名前加上结构名和双冒号来调用,如下所示:
Player::with_name("Dave");
- 实例方法:以
self值作为其第一个参数的函数。这里的self符号与 Python 中的self类似,指向实现该方法的实例(在这里,这是Player)。因此,get_friends()方法只能在已经创建的结构实例上调用:
let player = Player::with_name("Dave");
player.get_friends();
如果我们使用关联方法语法调用get_friends,即Player::get_friends(),编译器会给出以下错误:
这里的错误具有误导性,但它表明实例方法基本上是与self作为第一个参数关联的方法,并且instance.foo()是一种语法糖。这意味着我们也可以这样调用它:Player::get_friends(&player);。在这个调用中,我们向方法传递了一个Player实例,即&self是&player。
在类型上,我们可以实现三种实例方法的变体:
-
self作为第一个参数。在这种情况下,调用此方法不会允许你在之后使用该类型。 -
&self作为第一个参数。此方法仅提供对类型实例的读取访问。 -
&mut self作为第一个参数。此方法提供了对类型实例的可变访问。
我们的 set_friends 方法是一个 &mut self 方法,它允许我们修改 player 的字段。我们需要在 self 前面使用 & 操作符,这意味着 self 在方法执行期间被借用,这正是我们想要的。如果没有使用连字符,调用者会将所有权移动到方法中,这意味着值在 get_friends 返回后会进行去分配,我们就无法再使用 Player 实例了。如果你对术语移动和借用还不理解,不要担心,我们将在第五章,内存管理和安全性中解释所有这些内容。
现在,让我们来看一下枚举的实现。
枚举的 Impl 块
我们也可以为枚举提供实现。例如,考虑一个用 Rust 编写的支付库,它公开了一个名为 pay 的单一 API:
// enum_methods.rs
enum PaymentMode {
Debit,
Credit,
Paypal
}
// Bunch of dummy payment handlers
fn pay_by_credit(amt: u64) {
println!("Processing credit payment of {}", amt);
}
fn pay_by_debit(amt: u64) {
println!("Processing debit payment of {}", amt);
}
fn paypal_redirect(amt: u64) {
println!("Redirecting to paypal for amount: {}", amt);
}
impl PaymentMode {
fn pay(&self, amount: u64) {
match self {
PaymentMode::Debit => pay_by_debit(amount),
PaymentMode::Credit => pay_by_credit(amount),
PaymentMode::Paypal => paypal_redirect(amount)
}
}
}
fn get_saved_payment_mode() -> PaymentMode {
PaymentMode::Debit
}
fn main() {
let payment_mode = get_saved_payment_mode();
payment_mode.pay(512);
}
前面的代码中有一个名为 get_saved_payment_mode() 的方法,它返回一个用户的保存支付方式。这可以是信用卡、借记卡或Paypal。这最好用枚举(enum)来建模,其中不同的支付方式可以作为其变体添加。然后库为我们提供了一个单一的 pay() 方法,我们可以方便地提供要支付的金额。此方法确定枚举的哪个变体,并相应地调度到正确的支付服务提供商,而无需库消费者担心检查使用哪种支付方式。
枚举也广泛用于建模状态机,当与匹配语句结合使用时,它们使得状态转换代码非常简洁易写。它们还用于建模自定义错误类型。当枚举变体没有与之关联的数据时,它们可以像 C 枚举一样使用,其中变体隐式地具有从 0 开始的整数值,但也可以手动标记为整型(isize)值。这在与外部 C 库交互时很有用。
模块、导入和使用语句
语言通常提供一种方法将大型代码库拆分成多个文件以管理复杂性。Java 遵循每个.java文件一个公共类的约定,而 C++则提供了头文件和包含语句。Rust 也不例外,它为我们提供了模块。模块是命名空间或组织 Rust 程序代码的一种方式。为了在组织代码时提供灵活性,有多种创建模块的方法。模块是一个复杂的概念,为了本节的简洁性,我们将只突出使用它们的重要方面。模块的详细内容在第二章,使用 Cargo 管理项目中有所介绍。以下是关于 Rust 中模块的关键要点:
-
每个 Rust 程序都需要有一个根模块。在可执行文件中,通常是
main.rs文件,而对于库来说,则是lib.rs。 -
模块可以在其他模块内部声明,也可以组织成文件和目录。
-
为了让编译器了解我们的模块,我们需要使用
mod关键字来声明它,就像在根模块中使用mod my_module;一样。 -
要使用模块内的任何项目,我们需要使用
use关键字,以及模块的名称。这被称为将项目引入作用域。 -
在模块内部定义的项目默认是私有的,你需要使用
pub关键字来将它们暴露给消费者。
这就是模块的简要介绍。模块的一些高级特性也在第七章,高级概念中有所涉及。接下来,让我们看看标准库中可用的常用集合类型。
集合
通常情况下,你的程序需要处理多个数据实例。为此,我们有了集合类型。根据你的需求和数据在内存中的位置,Rust 提供了许多内置类型来存储数据集合。首先,我们有数组和元组。然后,在标准库中,我们有动态集合类型,我们将介绍最常用的几种,即向量(项目列表)和映射(键/值项)。然后,我们还有集合类型的引用,称为切片,它基本上是某个其他变量拥有的连续数据片段的视图。让我们先从数组开始。
数组
数组有一个固定长度,可以存储相同类型的项目。它们用[T, N]表示,其中T是任何类型,N是数组中的元素数量。数组的大小不能是变量,而必须是字面量usize值:
// arrays.rs
fn main() {
let numbers: [u8; 10] = [1, 2, 3, 4, 5, 7, 8, 9, 10, 11];
let floats = [0.1f64, 0.2, 0.3];
println!("Number: {}", numbers[5]);
println!("Float: {}", floats[2]);
}
在前面的代码中,我们声明了一个数组numbers,它包含10个元素,我们在左侧指定了类型。在第二个数组floats中,我们将类型指定为第一个数组项的后缀,即0.1f64。这是指定类型的另一种方式。接下来,让我们看看元组。
元组
元组与数组的不同之处在于,数组中的元素必须具有相同的类型,而元组中的项可以是不同类型的混合。它们是异构集合,用于存储不同类型的数据很有用。当从函数返回多个值时也可以使用。考虑以下使用元组的代码:
// tuples.rs
fn main() {
let num_and_str: (u8, &str) = (40, "Have a good day!");
println!("{:?}", num_and_str);
let (num, string) = num_and_str;
println!("From tuple: Number: {}, String: {}", num, string);
}
在前面的代码中,num_and_str 是一个包含两个元素的元组,(u8, &str)。我们还可以从已声明的元组中提取值到单独的变量中。在打印元组后,我们在下一行将其解构为 num 和 string 变量,它们的类型会自动推断。这相当方便。
向量
向量类似于数组,但它们的长度或内容不需要预先知道,并且可以根据需要增长。它们在堆上分配。可以通过调用 Vec::new 构造函数或使用 vec![] 宏来创建:
// vec.rs
fn main() {
let mut numbers_vec: Vec<u8> = Vec::new();
numbers_vec.push(1);
numbers_vec.push(2);
let mut vec_with_macro = vec![1];
vec_with_macro.push(2);
let _ = vec_with_macro.pop(); // value ignored with `_`
let message = if numbers_vec == vec_with_macro {
"They are equal"
} else {
"Nah! They look different to me"
};
println!("{} {:?} {:?}", message, numbers_vec, vec_with_macro);
}
在前面的代码中,我们以不同的方式创建了两个向量,numbers_vec 和 vec_with_macro。我们可以使用 push() 方法向向量中添加元素,并使用 pop() 方法移除元素。如果你访问它们的文档页面,还可以探索更多方法:doc.rust-lang.org/std/vec/struct.Vec.html。向量也可以使用 for 循环语法进行迭代,因为它们也实现了 Iterator 特性。
哈希映射
Rust 还为我们提供了映射,可以用来存储键值数据。它们来自 std::collections 模块,并命名为 HashMap。它们通过 HashMap::new 构造函数创建:
// hashmaps.rs
use std::collections::HashMap;
fn main() {
let mut fruits = HashMap::new();
fruits.insert("apple", 3);
fruits.insert("mango", 6);
fruits.insert("orange", 2);
fruits.insert("avocado", 7);
for (k, v) in &fruits {
println!("I got {} {}", v, k);
}
fruits.remove("orange");
let old_avocado = fruits["avocado"];
fruits.insert("avocado", old_avocado + 5);
println!("\nI now have {} avocados", fruits["avocado"]);
}
在前面的代码中,我们创建了一个名为 fruits 的新 HashMap。然后我们使用 insert 方法将一些水果及其数量插入到我们的 fruits 映射中。随后,我们使用 for 循环遍历键值对,其中我们通过 &fruits 获取水果映射的引用,因为我们只想读取键和值。默认情况下,值将被 for 循环消耗。在这种情况下,for 循环返回一个包含两个字段的元组((k,v))。还有单独的 keys() 和 values() 方法可用于分别遍历键和值。HashMap 类型中用于哈希键的哈希算法基于 Robin hood 开放寻址方案,但可以根据用例和性能替换为自定义哈希器。这就说完了。
接下来,让我们看看切片。
切片
切片是一种通用的方式来获取集合类型的一个视图。大多数用例是为了获取对集合类型中某个范围的只读访问。切片基本上是一个指针或引用,它指向由某个其他变量拥有的现有集合类型中的连续范围。在底层,切片是现有数据中的胖指针,这些数据位于栈或堆的某个位置。通过胖指针,意味着它们还包含它们指向的元素数量信息,以及数据指针。
切片用 &[T] 表示,其中 T 是任何类型。在用法上,它们与数组非常相似:
// slices.rs
fn main() {
let mut numbers: [u8; 4] = [1, 2, 3, 4];
{
let all: &[u8] = &numbers[..];
println!("All of them: {:?}", all);
}
{
let first_two: &mut [u8] = &mut numbers[0..2];
first_two[0] = 100;
first_two[1] = 99;
}
println!("Look ma! I can modify through slices: {:?}", numbers);
}
在前面的代码中,我们有一个 numbers 数组,它是一个栈分配的值。然后我们使用 &numbers[..] 语法从数组 numbers 中取一个切片,并将其存储在 all 中,其类型为 &[u8]。末尾的 [..] 表示我们想要获取整个集合的切片。这里我们需要 &,因为我们不能有裸值的切片——只能位于指针之后。这是因为切片是无大小类型。我们将在第七章,高级概念中详细讲解它们。我们也可以提供范围([0..2])来从任何中间位置或全部获取切片。切片也可以被可变地获取。first_two 是一个可变切片,通过它可以修改原始的 numbers 数组。
对于敏锐的观察者来说,你可以看到在取切片时,我们使用了额外的成对花括号。它们的存在是为了隔离代码,这些代码获取切片的可变引用而不是不可变引用。没有它们,代码将无法编译。这些概念将在第五章,内存管理和安全性中更加清晰。
注意:&str 类型也属于切片类型(一个 [u8])。与其他字节切片的区别在于,它们保证是 UTF-8 编码。切片也可以从 Vec 或 String 中获取。
接下来,让我们看看迭代器。
迭代器
迭代器是一种提供对集合类型元素进行高效操作的构造。尽管它不是一个新概念,但在许多命令式语言中,迭代器被实现为从列表或映射等集合类型构造的对象。例如,Python 的 iter(some_list) 或 C++ 的 vector.begin() 是从现有集合构造迭代器的方法。迭代器最初存在的主要动机是它们提供了一种比使用手动 for 循环更高层次的抽象,手动 for 循环很容易出现“少一个”的错误。另一个优点是迭代器不会在内存中读取整个集合,并且是惰性的。惰性意味着迭代器仅在需要时才会评估或访问集合中的元素。迭代器还可以与多个转换操作链式使用,例如根据条件过滤元素,并且只有在需要时才会评估这些转换。当需要访问这些元素时,迭代器提供了一个 next() 方法,该方法尝试从集合中读取下一个元素。这发生在迭代器评估计算链时。
在 Rust 中,任何实现了 Iterator 特性的类型都是迭代器。这种类型可以用于 for 循环中遍历其元素。它们为大多数标准库集合类型(如 Vector、HashMap、BTreeMap 等)实现了迭代器,也可以为它们自己的类型实现迭代器。
注意:只有当类型具有集合,如语义时,才需要实现 Iterator 特性。例如,为 () 单位类型实现迭代器特性是没有意义的。
在 Rust 中,迭代器是任何实现了 Iterator 特性的类型。这种类型可以用于 for 循环中遍历其元素。它们为大多数标准库集合类型(如 Vector、HashMap、BTreeMap 等)实现了迭代器,也可以为它们自己的类型实现迭代器。在 Rust 中,for 循环被转换为对正在迭代的对象的 next 调用的正常 match 表达式。此外,我们可以通过在它们上调用 iter() 或 into_iter() 来将大多数集合类型转换为迭代器。关于迭代器的信息就这么多——现在,我们可以着手解决以下练习。我们将深入研究迭代器,并在第七章 高级概念 中实现一个迭代器。
练习 – 修复单词计数器
带着基础知识,现在是时候将我们的知识付诸实践了!在这里,我们有一个程序,它计算文本文件中单词的实例,该文件作为参数传递给它。它几乎完成了,但有几个编译器捕获的错误和一些微妙的错误。以下是我们的不完整程序:
// word_counter.rs
use std::env;
use std::fs::File;
use std::io::prelude::BufRead;
use std::io::BufReader;
#[derive(Debug)]
struct WordCounter(HashMap<String, u64>);
impl WordCounter {
fn new() -> WordCounter {
WordCounter(HashMap::new());
}
fn increment(word: &str) {
let key = word.to_string();
let count = self.0.entry(key).or_insert(0);
*count += 1;
}
fn display(self) {
for (key, value) in self.0.iter() {
println!("{}: {}", key, value);
}
}
}
fn main() {
let arguments: Vec<String> = env::args().collect();
let filename = arguments[1];
println!("Processing file: {}", filename);
let file = File::open(filenam).expect("Could not open file");
let reader = BufReader::new(file);
let mut word_counter = WordCounter::new();
for line in reader.lines() {
let line = line.expect("Could not read line");
let words = line.split(" ");
for word in words {
if word == "" {
continue
} else {
word_counter.increment(word);
}
}
}
word_counter.display();
}
尝试将程序输入到一个文件中;尝试在编译器的帮助下编译并修复所有错误。一次修复一个错误,并通过重新编译代码从编译器那里获取反馈。这个练习的目的,除了涵盖本章的主题外,还在于让你更加熟悉编译器给出的错误信息,这是了解编译器及其如何分析你的代码的重要心理锻炼。你可能会惊讶地看到编译器在帮助你从代码中移除错误方面是多么的聪明。
一旦你完成代码的修复,这里有一些练习供你尝试,以便你能够进一步锻炼你的能力:
-
向
WordCounter的display方法添加一个filter参数,以便根据计数过滤输出。换句话说,只有当值大于过滤值时才显示键/值对。 -
由于 HashMap 存储其值是随机的,所以每次运行程序时输出也是随机的。尝试对输出进行排序。HashMap 的
values方法可能很有用。 -
看一下
display方法的self参数。如果你在self之前移除&运算符会发生什么?
概述
本章我们涵盖了如此多的主题。我们了解了一些关于 Rust 的历史和语言背后的动机。我们对它的设计原则和语言的基本特性进行了简要的介绍。我们还瞥见了 Rust 如何通过其类型系统提供丰富的抽象。我们学习了如何安装语言工具链,以及如何使用rustc构建和运行简单的示例程序。
在下一章中,我们将探讨使用 Rust 的专用包管理器构建 Rust 应用程序和库的标准方法,并设置我们的 Rust 开发环境,包括代码编辑器,这将为本书中所有后续练习和项目提供基础。
第二章:使用 Cargo 管理项目
现在我们已经熟悉了语言以及如何编写基本程序,我们将提升到在 Rust 中编写实用项目的水平。对于可以包含在单个文件中的简单程序,手动编译和构建它们并不是什么大问题。然而,在现实世界中,程序被分割成多个文件以管理复杂性,并且依赖于其他库。手动编译所有源文件并将它们链接在一起变得非常复杂。对于大型项目,手动方式不是可扩展的解决方案,因为可能有数百个文件及其依赖项。幸运的是,有工具可以自动化构建大型软件项目——包管理器。本章将探讨 Rust 如何使用其专门的包管理器管理大型项目,以及它为开发者提供了哪些功能来增强他们的开发体验。我们将涵盖以下主题:
-
包管理器
-
模块
-
Cargo 包管理器和 crates(库)作为编译单元
-
创建和构建项目
-
运行测试
-
货物子命令和第三方二进制文件的安装
-
Visual Studio 代码中的编辑器集成和设置
作为最后的练习,我们将创建 imgtool,这是一个简单的命令行工具,可以使用库从命令行旋转图像,并使用 Cargo 构建和运行我们的程序。我们有很多内容要介绍,所以让我们深入探讨吧!
包管理器
“高效开发的关键是犯有趣的错误。”
——汤姆·洛夫
真实世界的软件代码库通常组织成多个文件,并且会有许多依赖项,这就需要一个专门的工具来管理它们。包管理器是一类命令行工具,有助于管理具有多个依赖项的大型项目。如果你来自 Node.js 背景,你一定熟悉 npm/yarn,如果你来自 Go 语言,那么熟悉 go 工具。它们执行了分析项目、下载依赖项的正确版本、检查版本冲突、编译和链接源文件等所有繁重的工作。
低级语言(如 C/C++)的问题在于它们默认不提供专门的包管理器。C/C++社区长期以来一直在使用 GNU make 工具,这是一个语言无关的构建系统,具有晦涩的语法,这让许多开发者望而却步。make 的问题在于它不知道你的 C/C++源文件中包含了哪些头文件,因此必须手动提供这些信息。它没有内置的下载外部依赖项的支持,也不知道你正在运行的平台。幸运的是,这种情况并不适用于 Rust,因为它提供了一个专门的包管理器,它对正在管理的项目有更多的上下文信息。以下是对 Cargo 的介绍,Rust 的包管理器,它使得构建和维护 Rust 项目变得容易。但首先,我们需要更深入地了解 Rust 的模块系统。
模块
在我们探索更多关于 Cargo 之前,我们需要熟悉 Rust 如何组织我们的代码。我们在上一章中简要地看到了模块。在这里,我们将详细讲解它们。每个 Rust 程序都以根模块开始。如果你正在创建一个库,你的根模块是 lib.rs 文件。如果你正在创建一个可执行文件,根模块是任何包含 main 函数的文件,通常是 main.rs。当你的代码变得很大时,Rust 允许你将其拆分为模块。为了在组织项目时提供灵活性,有多种创建模块的方法。
嵌套模块
创建模块的最简单方法是使用现有模块中的 mod {} 块。考虑以下代码:
// mod_within.rs
mod food {
struct Cake;
struct Smoothie;
struct Pizza;
}
fn main() {
let eatable = Cake;
}
我们创建了一个名为 food 的内部模块。要在现有模块中创建模块,我们使用 mod 关键字,后跟模块名称 food,然后是一对大括号。在大括号内,我们可以声明任何类型的项,甚至嵌套模块。在我们的 food 模块中,我们声明了三个结构体:Cake、Smoothie 和 Pizza。然后在 main 中,我们使用路径语法 food::Cake 从 food 模块创建一个 Cake 实例。让我们编译这个程序:
奇怪!编译器看不到任何 Cake 类型被定义。让我们按照编译器说的去做,添加 use food::Cake:
// mod_within.rs
mod food {
struct Cake;
struct Smoothie;
struct Pizza;
}
use food::Cake;
fn main() {
let eatable = Cake;
}
我们添加了 use food::Cake;。要使用模块中的任何项目,我们必须添加一个 use 声明。让我们再试一次:
我们又得到了一个错误,说 Cake 是私有的。这让我们想到了模块的一个重要方面,即提供隐私。模块内的项目默认是私有的。要使用模块中的任何项目,我们需要将项目引入作用域。这是一个两步的过程。首先,我们需要通过在项目声明前加上 pub 关键字来使项目本身公开。其次,要使用该项目,我们需要添加一个 use 语句,就像我们之前使用 use food::Cake 一样。
use 关键字之后是模块中的项目路径。模块中任何项目的路径都使用路径语法指定,它使用两个双冒号(::)分隔项目名称。路径语法通常以模块名称开始,用于导入项目,尽管它也用于导入某些类型的单个字段,例如枚举。
让我们的 Cake 公开:
// mod_within.rs
mod food {
pub struct Cake;
struct Smoothie;
struct Pizza;
}
use food::Cake;
fn main() {
let eatable = Cake;
}
我们在 Cake 结构体前添加了 pub 并通过 use food::Cake 在根模块中使用它。有了这些更改,我们的代码可以编译。现在可能还不清楚为什么需要创建如此嵌套的模块,但当我们编写第三章测试、文档和基准测试中的测试时,我们会看到它们是如何被使用的。
文件作为模块
模块也可以作为文件创建。例如,对于名为 foo 的目录中的 main.rs 文件,我们可以在与 foo 同一目录中创建一个名为 bar 的模块作为文件 foo/bar.rs。然后在 main.rs 中,我们需要告诉编译器这个模块,即通过 mod foo; 声明模块。当使用基于文件的模块时,这是一个额外的步骤。为了演示如何使用文件作为模块,我们创建了一个名为 modules_demo 的目录,其结构如下:
+ modules_demo
└── foo.rs
└── main.rs
我们的 foo.rs 包含一个结构体 Bar,以及它的 impl 块:
// modules_demo/foo.rs
pub struct Bar;
impl Bar {
pub fn init() {
println!("Bar type initialized");
}
}
我们想在 main.rs 中使用这个模块。我们的 main.rs 包含以下代码:
// modules_demo/main.rs
mod foo;
use crate::foo::Bar;
fn main() {
let _bar = Bar::init();
}
我们使用 mod foo; 声明我们的模块,foo。然后,我们通过编写 use crate::foo::Bar. 来使用模块中的 Bar 结构体。注意在 use crate::foo::Bar; 中的 crate 前缀。根据你使用的不同前缀,有三种方式来使用模块中的项目:
绝对导入:
- crate: 一个绝对导入前缀,指向当前 crate 的根。在前面代码中,这将是指根模块,即 main.rs 文件。crate 关键字之后的所有内容都是从根模块解析的。
相对导入:
-
self: 一个相对导入前缀,指向当前模块中的项目。当任何代码想要引用其包含的模块时,会使用它,例如,使用 self::foo::Bar;。这通常用于从子模块重新导出项目以便在父模块中使用。
-
super: 一个相对导入前缀,可以用来使用和导入父模块中的项目。例如,测试模块这样的子模块会使用它来从父模块导入项目。例如,如果模块 bar 想要访问其父模块 foo 中的项目 Foo,它会在模块 bar 中将其导入为 use super::foo::Foo;。
创建模块的第三种方式是将它们组织成目录。
目录作为模块
我们也可以创建一个表示模块的目录。这种方法允许我们在文件和目录层次结构中拥有模块内的子模块。假设我们有一个名为 my_program 的目录,它有一个名为 foo 的模块作为文件 foo.rs。它包含一个名为 Bar 的类型以及 foo 的功能。随着时间的推移,Bar API 的数量不断增加,我们希望将它们作为子模块分离。我们可以使用基于目录的模块来模拟这个用例。
为了演示如何将模块作为目录创建,我们在名为 my_program 的目录中创建了一个程序。它有一个在 main.rs 中的入口点和一个名为 foo 的目录。这个目录现在包含一个名为 bar.rs 的子模块。
以下是我 _program 目录的结构:
+ my_program
└── foo/
└── bar.rs
└── foo.rs
└── main.rs
为了让 Rust 了解 bar,我们还需要在目录 foo/ 旁边创建一个名为 foo.rs 的同级文件。foo.rs 文件将包含在目录 foo/ 中创建的任何子模块的 mod 声明(这里为 bar.rs)。
我们的 bar.rs 包含以下内容:
// my_program/foo/bar.rs
pub struct Bar;
impl Bar {
pub fn hello() {
println!("Hello from Bar !");
}
}
我们有一个单元结构体 Bar,它有一个关联的方法 hello。我们想在 main.rs 中使用这个 API。
注意:在较旧的 Rust 2015 版本中,子模块不需要在 foo 目录旁边有一个 foo.rs 的同级文件,而是可以在 foo 中使用 mod.rs 文件来告知编译器该目录是一个模块。这两种方法在 Rust 2018 版本中都得到了支持。
接下来,我们的 foo.rs 包含以下代码:
// my_program/foo.rs
mod bar;
pub use self::bar::Bar;
pub fn do_foo() {
println!("Hi from foo!");
}
我们添加了对模块 bar 的声明。随后,我们从模块 bar 中重新导出了项目 Bar。这要求 Bar 被定义为 pub。pub use 部分是我们从子模块重新导出项目以便在父模块中可用的方式。在这里,我们使用了 self 关键字来引用模块本身。重新导出主要是编写 use 语句时的便利步骤,有助于在导入隐藏在嵌套子模块中的项目时减少混乱。
self 是相对导入的关键字。虽然鼓励使用 crate 进行绝对导入,但在父模块中从子模块重新导出项目时,使用 self 会更加简洁。
最后 main.rs 使用了这两个模块:
// my_program/main.rs
mod foo;
use foo::Bar;
fn main() {
foo::do_foo();
Bar::hello();
}
我们的 main.rs 声明了 foo 然后导入了结构体 Bar。然后我们调用了 foo 的方法 do_foo,也调用了 Bar 上的 hello。
模块远不止表面看起来那么简单,因此我们在 第七章 中介绍了关于它们的详细信息,高级概念。在探索了模块之后,让我们继续了解 Cargo。
Cargo 和 crates
当项目变得庞大时,通常的做法是将代码重构为更小、更易于管理的单元,如模块或库。你还需要工具来渲染项目的文档,包括如何构建以及它依赖哪些库。此外,为了支持开发者可以与社区分享库的语言生态系统,如今通常需要一个在线注册表。
Cargo 是一个工具,它赋予你做所有这些事情的能力,crates.io 是托管库的集中地点。用 Rust 编写的库称为 crate,crates.io 为开发者提供托管服务。通常,crate 可以来自三个来源:本地目录、在线 Git 仓库如 GitHub,或托管 crate 注册表如 crates.io。Cargo 支持来自所有这些来源的 crate。
让我们看看 Cargo 的实际应用。如果你已经按照前一章所述运行了 rustup,那么你将已经安装了 cargo 和 rustc。要查看我们可用的命令,我们可以不带任何参数运行 cargo:
它显示了一个我们可以使用的常见命令列表,以及一些标志。让我们使用 new 子命令来创建一个新的 Cargo 项目。
创建新的 Cargo 项目
cargo new 命令创建一个以目录形式存在的新项目名称。我们可以通过在 cargo 和子命令之间添加 help 标志来获取任何子命令的更多上下文。我们可以通过运行 cargo help new 来查看 new 子命令的文档,如下面的截图所示:
默认情况下,cargo new 创建一个二进制项目;创建库项目时必须使用 --lib 参数。让我们通过输入 cargo new imgtool 并查看它创建的目录结构来试一试:
Cargo 创建了一些启动文件,Cargo.toml 和 src/main.rs,其中 main 函数打印出 Hello World!对于二进制 crate(可执行文件),Cargo 创建一个 src/main.rs 文件,而对于库 crate,它则在 src/ 目录下创建 src/lib.rs。
Cargo 还为新项目初始化了 Git 仓库,并使用了一些常规默认设置,例如通过 .gitignore 文件防止目标目录被提交,以及对于二进制 crate 提交 Cargo.lock 文件,而对于库 crate 则忽略它。默认的版本控制系统(VCS)是 Git,可以通过传递 --vcs 标志给 Cargo 来更改(对于 mercurial 使用 --vcs hg)。截至目前,Cargo 支持 Git、hg(mercurial)、pijul(用 Rust 编写的版本控制系统)和 fossil。如果我们想修改这种默认行为,可以通过传递 --vcs none 来指示 Cargo 在创建我们的项目时不要配置任何 vcs。
让我们来看看我们创建的 imgtool 项目的 Cargo.toml 文件。此文件定义了项目的元数据和依赖项。它也被称为项目的清单文件:
[package]
name = "imgtool"
version = "0.1.0"
authors = ["creativcoders@gmail.com"]
edition = "2018"
[dependencies]
这是新项目所需的最低限度的 Cargo.toml 清单文件。它使用 TOML 配置语言,代表 Tom’s Obvious Minimal Language。它是一种由 Tom Preston-Werner 创建的文件格式。它让人联想到标准的 .INI 文件,但向其中添加了几个数据类型,这使得它成为配置文件的理想现代格式,并且比 YAML 或 JSON 更简单。我们现在将保持此文件最小化,并在以后添加内容。
货物和依赖项
对于依赖于其他库的项目,包管理器必须找到项目中的所有直接依赖项以及任何间接依赖项,然后编译并将它们链接到项目中。包管理器不仅仅是促进依赖项解析的工具;它们还应确保项目的可预测和可重复构建。在我们介绍如何构建和运行我们的项目之前,让我们讨论 Cargo 如何管理依赖项并确保可重复构建。
使用 Cargo 管理的 Rust 项目通过两个文件来完成所有魔法:Cargo.toml(之前已介绍)是开发者写入依赖项及其所需版本(如 1.3.*)的 SemVer 语法文件的文件,以及一个名为 Cargo.lock 的锁文件,该文件在构建项目时由 Cargo 生成,其中包含所有直接依赖项和任何间接依赖项的绝对版本(如 1.3.15)。此锁文件确保二进制包的重复构建。Cargo 通过引用此锁文件来最小化对项目进行任何进一步更改时所需的工作。因此,建议二进制包将其 .lock 文件包含在他们的存储库中,而库包可以是无状态的,不需要包含它。
可以使用 cargo update 命令更新依赖项。这将更新所有依赖项。如果要更新单个依赖项,我们可以使用 cargo update -p 。如果您更新单个包的版本,Cargo 会确保只更新与该包在 Cargo.lock 文件中相关的部分,并保留其他版本不变。
Cargo 遵循语义版本控制系统(SemVer),其中您的库版本以 major.minor.patch 格式指定。这些可以描述如下:
-
主版本:只有当项目进行新的破坏性更改(包括错误修复)时才会增加。
-
小版本:只有在新功能以向后兼容的方式添加时才会增加。
-
补丁版本:只有以向后兼容的方式修复错误且没有添加新功能时才会增加。
例如,您可能想在项目中包含序列化库 serde。在撰写本书时,serde 的最新版本是 1.0.85,您可能只关心主版本号。因此,您将 serde = “1” 作为依赖项(在 SemVer 格式中表示为 1.x.x)写入 Cargo.toml,Cargo 将为您解决它,并在锁文件中将它固定为 1.0.85。下次您使用 cargo update 命令更新 Cargo.lock 时,此版本可能会升级到 1.x.x 匹配中的最新版本。如果您不太关心,只想获取包的最新发布版本,您可以使用 * 作为版本,但这不是推荐的做法,因为它会影响构建的可重复性,您可能会拉入具有破坏性更改的主版本。以 * 作为依赖项版本发布包也是禁止的。
在此基础上,让我们看看 cargo build 命令,该命令用于编译、链接和构建我们的项目。此命令对您的项目执行以下操作:
-
如果您还没有 Cargo.lock 文件,则为您运行 cargo update,并将 Cargo.toml 中的确切版本放入锁文件中
-
下载所有在 Cargo.lock 中已解析的依赖项
-
构建所有这些依赖项
-
构建你的项目并将其与依赖项链接
默认情况下,cargo build 在 target/debug/ 目录下创建项目的调试版本。可以通过传递 --release 标志来创建在 target/release/ 目录下的优化版本,用于生产代码。调试版本提供更快的构建时间,缩短了反馈循环,而生产构建则稍微慢一些,因为编译器会对源代码执行更多的优化遍历。在开发过程中,你需要有更短的修复-编译-检查的反馈时间。为此,可以使用 cargo check 命令,这将导致更短的编译时间。它基本上跳过了编译器的代码生成部分,并且只运行源代码的前端阶段,即在编译器中的解析和语义分析。另一个命令是 cargo run,它具有双重功能。它首先运行 cargo build,然后在 target/debug/ 目录下运行你的程序。对于构建/运行发布版本,可以使用 cargo run --release .。在 imgtool/ 目录下运行 Cargo run 后,我们得到以下输出:
使用 Cargo 运行测试
Cargo 还支持运行测试和基准测试。深入测试和基准测试在第三章,测试、文档和基准测试中有详细说明。在本节中,我们将简要介绍如何使用 Cargo 运行测试。我们将为库 crate 编写测试。为了完成本节,让我们通过运行以下命令创建一个 crate:cargo new myexponent --lib:
库 crate 与二进制 crate 类似。区别在于,我们不是使用 src/main.rs 和作为入口点的 main 函数,而是使用 src/lib.rs 和一个简单的测试函数 it_works,该函数带有 #[test] 注解。我们可以立即使用 cargo test 运行 it_works 测试函数并查看它是否通过:
现在,让我们尝试使用 Cargo 进行一些测试驱动开发(TDD)。我们将通过添加一个 pow 函数来扩展这个库,用户可以使用这个函数来计算给定数字的指数。我们将为这个函数编写一个测试,该测试最初失败,然后填充实现直到它通过。以下是新的 src/lib.rs,其中包含没有实现的 pow 函数:
// myexponent/src/lib.rs
fn pow(base: i64, exponent: usize) > i64 {
unimplemented!();
}
#[cfg(test)]
mod tests {
use super::pow;
#[test]
fn minus_two_raised_three_is_minus_eight() {
assert_eq!(pow(-2, 3), -8);
}
}
目前不必担心细节。我们已经创建了一个单独的 pow 函数,它接受一个 i64 类型的基数和一个正指数 usize,并返回一个被提升到指数的数字。在 mod tests {中,我们有一个名为 minus_two_raised_three_is_minus_eight 的测试函数,它执行单个断言。assert_eq!宏检查传递给它的两个值的相等性。如果左边的参数等于右边的参数,则断言通过;否则,它会抛出一个错误,编译器会报告失败的测试。如果我们运行 cargo test,由于那里有一个 unimplemented!()宏调用,单元测试显然会因 pow 调用而失败:
简而言之,unimplemented!()只是一个方便的宏,用于标记未完成的代码或你打算稍后实现的代码,但希望编译器仍然编译它而不报类型错误。内部,它会调用 panic!并传递消息“尚未实现”。它可以用于实现特质多个方法的情况。例如,你开始实现一个方法,但还没有计划其他方法的实现。在编译时,如果你只是放置了一个带有空体的函数,你会得到其他未实现方法的编译错误。对于这些方法,我们可以在它们内部放置一个 unimplemented!()宏调用,只是为了让类型检查器满意并为我们编译,并在运行时转移错误。我们将在第九章“使用宏进行元编程”中查看更多这样的方便宏。
现在,让我们通过实现一个快速且简单的 pow 函数版本来解决这个问题,并再次尝试:
// myexponent/src/lib.rs
pub fn pow(base: i64, exponent: usize) -> i64 {
let mut res = 1;
if exponent == 0 {
return 1;
}
for _ in 0..exponent {
res *= base as i64;
}
res
}
运行 Cargo test 会得到以下输出:
这次,测试通过了。嗯,这就是基础。我们将在第三章“测试、文档和基准测试”中进行更多测试。
使用 Cargo 运行示例
为了使用户能够快速开始使用你的 crate,将如何使用你的 crate 的代码示例传达给用户是一个好习惯。Cargo 标准化了这个做法,这意味着你可以在项目根目录下添加一个 examples/目录,其中可以包含一个或多个.rs 文件,包含一个 main 函数,展示你的 crate 的示例用法。
你可以使用 cargo run --examples <file_name>来运行 examples/目录下的代码,其中文件名没有.rs 扩展名。为了演示这一点,我们为 myexponent crate 添加了一个 example/目录,包含一个名为 basic.rs 的文件:
// myexponent/examples/basic.rs
use myexponent::pow;
fn main() {
println!("8 raised to 2 is {}", pow(8, 2));
}
在 examples/目录下,我们从 myexponent crate 中导入了 pow 函数。以下是在运行 cargo run --example basic 后的输出:
Cargo 工作空间
随着时间的推移,你的项目已经变得相当大。现在,你正在考虑是否可以将代码的公共部分作为单独的 crate 分开,以帮助管理复杂性。嗯,Cargo 工作区允许你做到这一点。工作区的概念是它们允许你在目录中本地拥有 crate,这些 crate 可以共享相同的 Cargo.lock 文件和公共目标或输出目录。为了演示这一点,我们将创建一个新的项目,该项目包含 Cargo 工作区。工作区只是一个包含 Cargo.toml 文件的目录。它没有任何[package]部分,但在其中有一个[workspace]部分。让我们创建一个新的目录名为 workspace_demo,并添加如下所示的 Cargo.toml 文件:
mkdir workspace_demo
cd workspace_demo && touch Cargo.toml
然后我们将工作区部分添加到我们的 Cargo.toml 文件中:
# worspace_demo/Cargo.toml
[workspace]
members = ["my_crate", "app"]
在[工作区]中,members 键是工作区目录内 crate 的列表。现在,在 workspace_demo 目录中,我们将创建两个 crate:my_crate,一个库 crate 和 app,一个使用 my_crate 的二进制 crate。
为了保持简单,my_crate 有一个公共 API,它只是打印一条问候消息:
// workspace_demo/my_crate/lib.rs
pub fn greet() {
println!("Hi from my_crate");
}
现在,从我们的 app crate 中,我们有 main 函数,它调用 my_crate 的 greet 函数:
// workspace_demo/app/main.rs
fn main() {
my_crate::greet();
}
然而,我们需要让 Cargo 知道我们的 my_crate 依赖项。由于 my_crate 是一个本地 crate,我们需要在 app 的 Cargo.toml 文件中将它指定为路径依赖项,如下所示:
# workspace_demo/app/Cargo.toml
[package]
name = "app"
version = "0.1.0"
authors = ["creativcoder"]
edition = "2018"
[dependencies]
my_crate = { path = "../my_crate" }
现在,当我们运行 cargo build 时,二进制文件将在 workspace_demo 目录的目标目录中生成。相应地,我们可以在 workspace_demo 目录中添加多个本地 crate。现在,如果我们想从 crates.io 添加第三方依赖项,我们需要在所有需要它的 crate 中添加它。然而,在 cargo build 期间,Cargo 确保在 Cargo.lock 文件中只有一个版本的该依赖项。这确保第三方依赖项不会被重建和重复。
扩展 Cargo 和工具
Cargo 也可以扩展以集成外部工具以增强开发体验。它被设计成尽可能可扩展。开发者可以创建命令行工具,Cargo 可以通过简单的 cargo binary-name 语法调用它们。在本节中,我们将查看一些这些工具。
子命令和 Cargo 安装
Cargo 的自定义命令属于子命令类别。这些工具通常是来自 crates.io、GitHub 或本地项目目录的二进制文件,可以通过使用 cargo install 或仅在本地 Cargo 项目中使用 cargo install 来安装。cargo-watch 工具就是一个这样的例子。
cargo-watch
Cargo-watch 通过在后台自动构建你的项目来帮助你缩短修复、编译、运行周期。默认情况下,这仅运行 Rust 的类型检查器(cargo check 命令),并且不经过代码生成阶段(这需要时间)并缩短编译时间。也可以使用-x 标志提供自定义命令来代替 cargo check。
我们可以通过运行 cargo install cargo-watch 来安装 cargo-watch,然后在任何 Cargo 项目中,我们可以通过调用 cargo watch 来运行它。现在,每当我们对项目进行更改时,cargo-watch 都会在后台运行 cargo check,并为我们重新编译项目。在下面的代码中,我们犯了一个拼写错误并进行了纠正,cargo-watch 为我们重新编译了项目:
如果您熟悉 Node.js 生态系统中的 watchman 或 nodemon 软件包,这将是一个非常相似的经历。
cargo-edit
cargo-edit 子命令用于自动将依赖项添加到您的 Cargo.toml 文件中。它可以添加所有类型的依赖项,包括开发依赖项和构建依赖项,还允许您添加任何依赖项的特定版本。您可以通过运行 cargo install cargo-edit 来安装它。此子命令提供了四个命令:cargo add、cargo rm、cargo edit 和 cargo upgrade。
cargo-deb
这是另一个有用的社区开发子命令,可以创建 Debian 软件包 (.deb),以便在 Debian Linux 上轻松分发 Rust 可执行文件。我们可以通过运行 cargo install cargo-deb 来安装它。我们将在本章末尾使用此工具将我们的 imgtool 命令行可执行文件打包成 .deb 软件包。
cargo-outdated
此命令显示您 Cargo 项目中的过时 crate 依赖项。您可以通过运行 cargo install cargo-outdated 来安装它。一旦安装,您可以在项目目录中运行 cargo outdated 来查看过时的 crate(如果有)。
现在,这些子命令与 Cargo 无缝协作的方式是,开发者使用命名约定创建这些二进制 crate,例如 cargo-[cmd],当您安装那个二进制 crate 时,Cargo 会将安装的二进制文件暴露给您的 $PATH 变量,然后可以通过 cargo 来调用。这是一个简单而有效的方法,Cargo 已经采用这种方法来通过社区开发的子命令扩展自身。还有许多其他类似的 Cargo 扩展。您可以在 github.com/rust-lang/cargo/wiki/Third-party-cargo-subcommands 找到所有社区精选的子命令列表。
cargo install 也用于安装任何在 Rust 中开发的二进制 crate 或可执行文件/应用程序。它们默认安装在 /home/<用户>/.cargo/bin/ 目录中。我们将使用它来安装我们的 imgtool 应用程序——我们将在本章末尾构建它——使其在系统范围内可用。
使用 clippy 检查代码
代码风格检查是一种有助于维护库的质量并使其遵循标准编码习惯和规范的实践。在 Rust 生态系统中的事实上的代码风格检查工具是 clippy。Clippy 为我们提供了一组 lint(截至本书编写时约为 291 个),以确保 Rust 代码的高质量。在本节中,我们将安装 clippy 并在我们的 libawesome 库上尝试它,向其中添加一些虚拟代码,并查看 clippy 提出的建议。在项目中使用 clippy 有多种方式,但我们将使用 cargo clippy 子命令方式,因为它很简单。Clippy 可以对代码进行分析,因为它是一个编译器插件,并且可以访问大量编译器的内部 API。
要使用 clippy,我们需要通过运行 rustup component add clippy 来安装它。如果您还没有安装,rustup 会为您安装。现在,为了展示 clippy 如何指出我们代码中的不良风格,我们在 myexponent crate 的 pow 函数中的 if 条件内放置了一些虚拟语句,如下所示:
// myexponent/src/lib.rs
fn pow(base: i64, exponent: usize) -> i64 {
/////////////////// Dummy code for clippy demo
let x = true;
if x == true {
}
///////////////////
let mut res = 1;
...
}
添加了这些行后,通过在 myexponent 目录中运行 cargo clippy,我们得到了以下输出:
太好了!Clippy 找到了一种常见的代码风格,它是多余的,即检查布尔值是 true 或 false。或者,我们也可以直接将前面的 if 条件写成 if x {}。Clippy 还会进行许多其他检查,其中一些甚至可以指出您代码中的潜在错误,例如 rust-lang-nursery.github.io/rust-clippy/master/index.html#absurd_extreme_comparisons。要查看所有可用的 lint 和配置 clippy 的各种方式,请访问 github.com/rust-lang/rust-clippy。
探索清单文件 - Cargo.toml
Cargo 严重依赖于项目的清单文件,即 Cargo.toml 文件,以获取有关项目的各种信息。让我们更详细地看看这个文件的结构和它可以包含的项目。如您之前所见,cargo new 创建了一个几乎为空的清单文件,只包含必要的字段,以便项目可以构建。每个清单文件都分为几个部分,指定了项目的不同属性。我们将查看在中等大小的 Cargo 项目清单文件中通常可以找到的部分。以下是一个来自更大应用程序的假想 Cargo.toml 文件:
# cargo_manifest_example/Cargo.toml
# We can write comments with `#` within a manifest file
[package]
name = "cargo-metadata-example"
version = "1.2.3"
description = "An example of Cargo metadata"
documentation = "https://docs.rs/dummy_crate"
license = "MIT"
readme = "README.md"
keywords = ["example", "cargo", "mastering"]
authors = ["Jack Daniels <jack@danie.ls>", "Iddie Ezzard <iddie@ezzy>"]
build = "build.rs"
edition = "2018"
[package.metadata.settings]
default-data-path = "/var/lib/example"
[features]
default=["mysql"]
[build-dependencies]
syntex = "⁰.58"
[dependencies]
serde = "1.0"
serde_json = "1.0"
time = { git = "https://github.com/rust-lang/time", branch = "master" }
mysql = { version = "1.2", optional = true }
sqlite = { version = "2.5", optional = true }
让我们回顾一下尚未解释的部分,从 [package] 部分开始:
-
描述:它包含有关项目的较长的自由格式文本字段。
-
许可证:它包含软件许可证标识符,如
spdx.org/licenses/中列出的。 -
读取文件:它允许您链接到项目存储库中的文件。这应该显示为项目介绍的入口点。
-
documentation: 如果是库 crate,它包含 crate 的文档链接。
-
keywords: 它是一个单词列表,有助于通过搜索引擎或通过 crates.io 网站发现您的项目。
-
authors: 列出了项目的关键作者。
-
build: 它定义了一段 Rust 代码(通常是 build.rs),在程序的其他部分编译之前编译并运行。这通常用于生成代码或构建 crate 所依赖的本地库。
-
edition: 此键指定在编译项目时要使用哪个版本。在我们的例子中,我们使用的是 2018 版本。之前的版本是 2015,如果没有 edition 键存在,则假定它是默认版本。注意:使用 2018 版本创建的项目是向后兼容的,这意味着它们也可以将 2015 的 crate 作为依赖项。
接下来是 [package.metadata.settings]。通常,Cargo 会对其不认识的键和部分进行抱怨,但包含元数据的部分是一个例外。它们被 Cargo 忽略,因此可以用于您项目所需的任何可配置的键/值对。
[features]、[dependencies] 和 [build-dependencies] 部分相互关联。依赖项可以通过版本号声明,如 SemVer 指南中所述:
serde = "1.0"
这意味着 serde 是一个强制依赖项,我们想要最新版本,1.0.*。实际版本将在 Cargo.lock 中固定。
使用 caret 符号可以扩展 Cargo 允许查找的版本范围:
syntex = "⁰.58"
这里,我们表示我们想要最新的主要版本,0..,它必须至少是 0.58.*。
Cargo 还允许您直接将依赖项指定到 Git 仓库,前提是仓库是一个由 Cargo 创建的项目,并且遵循 Cargo 预期的目录结构。我们可以这样指定来自 GitHub 的依赖项:
time = { git = "https://github.com/rust-lang/time", branch = "master" }
这也适用于其他在线 Git 仓库,如 GitLab。同样,实际的版本(或 Git 的情况下的更改集修订版)将由 cargo update 命令在 Cargo.lock 中固定。
清单还有两个可选依赖项,mysql 和 sqlite:
mysql = { version = "1.2", optional = true }
sqlite = { version = "2.5", optional = true }
这意味着程序可以在不依赖任何一方的情况下构建。[features] 部分包含默认功能的列表:
default = ["mysql"]
这意味着如果您在构建程序时没有手动覆盖功能集,则只会拉入 mysql,而不是 sqlite。功能的一个示例用法是当您的库有某些优化调整时。然而,在嵌入式平台上这将是昂贵的,因此库作者可以将它们作为功能发布,这样它们只会在有能力的系统上可用。另一个例子是当您构建一个命令行应用程序,并提供一个作为额外功能的 GUI 前端时。
这就是如何使用 Cargo.toml 清单文件描述 Cargo 项目的快速简要概述。关于如何使用 Cargo 配置项目还有很多可以探索的。更多信息请查看doc.rust-lang.org/cargo/reference/manifest.html。
设置 Rust 开发环境
Rust 对大多数代码编辑器都有良好的支持,无论是 vim、Emacs、intellij IDE、Sublime、Atom 还是 Visual Studio Code。Cargo 也受到这些编辑器的良好支持,生态系统中有几个工具可以增强体验,如下所示:
-
rustfmt:它根据 Rust 风格指南中提到的约定格式化代码。
-
clippy:它会警告你常见的错误和潜在的代码问题。Clippy 依赖于标记为不稳定的编译器插件,因此它仅适用于 nightly Rust。使用 rustup,你可以轻松切换到 nightly。
-
racer:它可以查询 Rust 标准库,并提供代码补全和工具提示。
在上述编辑器中,Intellij IDE 和 Visual Studio Code(vscode)提供了最成熟的 IDE 体验。在本章中,我们将介绍如何设置 vscode 的开发环境,因为它更易于访问且更轻量级。对于 vscode,Rust 社区有一个名为 rls-vscode 的扩展,我们将在本节中安装它。此扩展由 Rust 语言服务器(RLS)组成,它内部使用了我们之前列出的许多工具。我们将使用 Visual Studio Code 1.23.1(d0182c341)和 Ubuntu 16.04 来设置它。
安装 vscode 超出了本书的范围。你可以在操作系统的软件仓库中查找,并访问code.visualstudio.com获取更多信息。
让我们实际打开本章开头创建的 imgtool 应用程序在 vscode 中:
cd imgtool
code . # opens the current directory in vscode
一旦我们打开我们的项目,vscode 会自动识别我们的项目为 Rust 项目,并给我们推荐下载 vscode 扩展。它看起来可能像这样:
如果你没有收到推荐,你总是可以在左上角的搜索栏中输入 Rust。然后我们可以点击安装,并在扩展页面按“重新加载”,这将重启 vscode 并使其在我们的项目中可用:
下次你打开项目中 main.rs 文件并开始输入时,扩展程序会启动并提示你安装任何与 Rust 相关的缺失工具链,你可以点击安装。然后它开始下载该工具链:
几分钟后,状态将发生变化,如下所示:
现在,我们可以开始了。
注意:由于 RLS 还处于预览阶段,您在首次安装时可能会遇到 RLS 卡住的情况。通过重新启动 vscode 并在删除它之后重新安装 RLS,应该可以工作。如果不行,请随意在其 GitHub 页面 rls-vscode 上提出问题。
在我们的 imgtool 项目打开的情况下,让我们看看当尝试导入一个模块时 RLS 的响应:
如您所见,它为 Rust 标准库中 fs 模块中可用的项目执行自动完成。最后,让我们看看 RLS 是如何为我们处理代码格式的。让我们将所有代码放在同一行上以演示这一点:
让我们保存文件。然后我们可以使用 Ctrl + Shift + I 或 Ctrl + Shift + P 并选择 Format Document。这将立即格式化文档,并在您点击保存时对您的代码运行 cargo check:
关于其他代码编辑器的更多信息,Rust 有一个名为 areweideyet.com 的页面,列出了所有编辑器的状态,包括类别,显示了它们对该语言的支持程度。请务必查看它们!
现在,让我们继续实现我们的 imgtool 应用程序。
使用 Cargo 构建项目 – imgtool
现在,我们相当了解如何使用 Cargo 管理项目。为了深入理解这些概念,我们将构建一个使用第三方 crate 的命令行应用程序。这个练习的全部目的是熟悉使用第三方 crate 构建项目的常规工作流程,因此我们将跳过我们编写代码的许多细节。尽管如此,我们鼓励您查看代码中使用的 API 的文档。
我们将使用一个名为 image 的 crate,它来自 crates.io。这个 crate 提供了各种图像处理 API。我们的命令行应用程序将很简单;它将接受一个图像文件的路径作为参数,每次运行时都将其旋转 90 度,并将其写回同一文件。
我们将进入之前创建的 imgtool 目录。首先,我们需要告诉 Cargo 我们想要使用 image crate。我们可以使用 cargo add image@0.19.0 命令从命令行添加版本为 0.19.0 的 image crate。以下是我们的更新后的 Cargo.toml 文件:
[package]
name = "imgtool"
version = "0.1.0"
authors = ["creativcoder"]
edition = "2018"
[dependencies]
image = "0.19.0"
然后,我们将调用 cargo build。这将从 crates.io 拉取 image crate 及其依赖项,最后编译我们的项目。一旦完成,我们就可以在 main.rs 文件中使用它了。对于我们的应用程序,我们将提供一个图像路径作为参数。在我们的 main.rs 文件中,我们想要读取此图像的路径:
// imgtool/src/main.rs
use std::env;
use std::path::Path;
fn main() {
let image_path = env::args().skip(1).next().unwrap();
let path = Path::new(&image_path);
}
首先,我们通过从 env 模块中调用 args() 函数来读取传递给 imgtool 的参数。这返回一个字符串,作为图像文件的路径。然后我们获取图像路径并从中创建一个 Path 实例。接下来是来自 image crate 的旋转功能。请注意,如果你正在运行 Rust 2015 版本,你需要一个额外的 extern crate image; 声明在 main.rs 的顶部,以便你能够访问 image crate 的 API。在 Rust 2018 版本中,这不再需要:
// imgtool/src/main.rs
use std::env;
use std::path::Path;
fn main() {
let image_path = env::args().skip(1).next().unwrap();
let path = Path::new(&image_path);
let img = image::open(path).unwrap();
let rotated = img.rotate90();
rotated.save(path).unwrap();
}
从 image crate 中,我们使用 open 函数打开我们的图片并将其存储在 img 中。然后我们在 img 上调用 rotate90。这返回一个旋转后的图像缓冲区,我们通过调用 save 并传递路径将其保存回原始图像路径。前述代码中的大多数函数调用都返回一个名为 Result 的包装值,因此我们在 Result 值上调用 unwrap() 来告诉编译器我们不在乎函数调用是否失败,假设它已经成功,我们只想从 Result 类型中获取包装的值。我们将在第六章“错误处理”中学习关于 Result 类型以及适当的错误处理方法。对于演示,在项目的 asset 文件夹下,你可以找到一个名为 Ferris 的螃蟹的图片(assets/ferris.png)。在运行代码之前,我们将看到以下图片:
现在是时候使用这张图片作为参数来运行我们的应用程序了。现在,你有两种方式可以运行 imgtool 二进制文件并传递图片作为参数:
-
通过先运行 cargo build,然后手动调用二进制文件作为 ./target/debug/imgtool assets/ferris.png 来执行。
-
通过直接运行 cargo run – assets/ferris.png。双横线标志着 Cargo 自身参数的结束。之后的所有内容都将传递给我们的可执行文件(这里,这是 imgtool)。
运行 cargo run – assets/ferris.png 后,我们可以看到 Ferris 翻了个跟头:
太好了!我们的应用程序运行正常。我们现在可以通过在 imgtool 目录中运行 cargo install 来安装我们的工具,然后从终端的任何位置使用它。此外,如果你使用的是 Ubuntu,我们可以使用 cargo deb 子命令来创建一个 deb 包,以便你可以将其分发给其他用户。运行 cargo deb 命令会产生一个 .deb 文件,如下面的截图所示:
现在,是你探索与前面代码相关内容的时候了:
-
使用 Rust 标准库文档
doc.rust-lang.org/std/来了解 Rust 中的 unwrap() 函数及其可用类型。 -
在标准库文档中查找 Path 类型,看看你是否可以修改程序以不覆盖文件,而是创建一个新文件,其新文件后缀为 _rotated。
-
使用图像 crate(
docs.rs/image)的文档页面中的搜索栏,尝试查找具有不同角度的其他旋转方法,并修改代码以使用它们。
摘要
在本章中,我们了解了标准的 Rust 构建工具 Cargo。我们简要地了解了如何使用 Cargo 初始化、构建和运行测试。我们还探索了 Cargo 之外的工具,这些工具可以使开发体验更加流畅和高效,例如 RLS 和 clippy。我们看到了如何通过安装 RLS 扩展来将这些工具与 Visual Studio Code 编辑器集成。最后,我们创建了一个小型的 CLI 工具,通过使用 Cargo 中的第三方 crate 来操作图像。
在下一章中,我们将讨论测试、文档化和基准测试我们的代码。
第三章:测试、文档和基准
在本章中,我们将继续学习 Cargo,了解如何编写测试,如何编写代码文档,以及如何使用基准测试来衡量代码的性能。然后,我们将运用这些技能来构建一个简单的 crate,模拟逻辑门,为您提供编写单元测试、集成测试以及文档测试的端到端体验。
在本章中,我们将涵盖以下主题:
-
测试的动机
-
组织测试和测试原语
-
单元测试和集成测试
-
文档测试
-
基准测试
-
使用 Travis CI 进行持续集成
测试的动机
“那些不可能的事情只是需要更长的时间。” **
软件系统就像带有小齿轮和齿轮的机器。如果任何一个单独的齿轮出现故障,整个机器很可能以不可靠的方式运行。在软件中,这些单独的齿轮是函数、模块或您使用的任何库。对软件系统个别组件的功能测试是维护高质量代码的有效和实用方法。它不能证明不存在错误,但它有助于在将代码部署到生产环境中建立信心,并在项目需要长期维护时保持代码库的稳定性。此外,没有单元测试,软件的大规模重构是难以进行的。在软件中智能和平衡地使用单元测试的好处是深远的。在实现阶段,编写良好的单元测试成为软件组件的非正式规范。在维护阶段,现有的单元测试作为防止代码库回归的 harness,鼓励立即修复。在像 Rust 这样的编译语言中,这甚至更好,因为由于编译器的有用错误诊断,涉及回归的单元测试(如果有)将更加有指导性。
单元测试的另一个良好副作用是它们鼓励程序员编写模块化代码,这些代码主要依赖于输入参数,即无状态函数。这使程序员远离编写依赖于全局可变状态的代码。编写依赖于全局可变状态的测试是困难的。此外,仅仅思考为一段代码编写测试的行为就帮助程序员找出实现中的愚蠢错误。它们还作为非常好的文档,帮助任何试图理解代码库不同部分如何相互交互的新手。
我们可以得出的结论是,测试对于任何软件项目都是不可或缺的。现在,让我们来看看如何在 Rust 中编写测试,首先从学习组织测试开始!
组织测试
在开发软件时,我们通常编写两种基本的测试:单元测试和集成测试。它们服务于不同的目的,并且与被测试的代码库的交互方式也不同。单元测试总是旨在轻量级,测试单个组件,以便开发者可以经常运行它们,从而提供更短的反馈循环,而集成测试则是重量级的,旨在模拟现实世界场景,基于其环境和规范进行断言。Rust 的内置测试框架为我们提供了编写和组织这些测试的合理默认值:
-
单元测试: 单元测试通常在包含要测试的代码的同一模块中编写。当这些测试的数量增加时,它们会被组织成一个实体,作为一个嵌套模块。通常,在当前模块中创建一个子模块,按照惯例命名为
tests,并在其上添加#[cfg(test)]属性,然后将所有与测试相关的函数放入其中。这个属性简单地告诉编译器在运行cargo test时包含测试模块中的代码。稍后我们将详细介绍属性。 -
集成测试: 集成测试在 crate 根部的
tests/目录中单独编写。它们被编写成好像测试是正在测试的 crate 的消费者。tests/目录中的任何.rs文件都可以添加一个use声明来引入需要测试的任何公共 API。
要编写上述任何一种测试,我们需要熟悉一些测试原语。
测试原语
Rust 的内置测试框架基于一些原语,主要由属性和宏组成。在我们编写任何实际的测试之前,了解如何有效地使用它们是非常重要的。
属性
属性是 Rust 代码中项目的一个注释。项目是 crate 中的顶级语言结构,如函数、模块、结构体、枚举和常量声明,以及其他仅在 crate 根定义的东西。属性通常是编译器内置的,但也可以通过编译器插件由用户创建。它们指示编译器为它们下面的项目或模块注入额外的代码或意义。我们将在第七章,高级概念中详细介绍这些内容。为了保持话题的连贯性,我们在这里将讨论两种属性形式:
-
#[<name>]: 这适用于每个项目,通常出现在它们的定义上方。例如,Rust 中的测试函数使用#[test]属性进行标注。这表示该函数被视为测试框架的一部分。 -
#![<name>]: 这适用于整个 crate。注意那里有一个额外的!。它通常位于 crate 根部的顶部。
如果我们正在创建一个库 crate,crate 根通常是lib.rs,而当我们创建一个二进制 crate 时,crate 根将是main.rs文件。
除了#[cfg(test)]这样的属性形式之外,还有其他形式的属性,这些属性在模块内编写测试时使用。这个属性被添加到测试模块的顶部,以提示编译器有条件地编译模块,但仅在测试模式下编译代码时才这样做。属性不仅限于在测试代码中使用;在 Rust 中它们被广泛使用。我们将在接下来的章节中看到更多关于它们的例子。
断言宏
在测试中,当给定一个测试用例时,我们试图断言我们的软件组件在给定输入范围内的预期行为。通常,语言提供称为断言函数的函数来执行这些断言。Rust 为我们提供了断言函数,作为宏实现,帮助我们实现相同的功能。让我们看看一些常用的例子:
assert!(true);
assert!(a == b, "{} was not equal to {}", a, b);
assert!:这是最简单的断言宏,它接受一个布尔值进行断言。如果值为false,则测试会崩溃,显示失败发生的行。它还可以接受一个格式字符串,后跟相应数量的变量,用于提供自定义错误消息:
let a = 23;
let b = 87;
assert_eq!(a, b, "{} and {} are not equal", a, b);
-
assert_eq!:它接受两个值,如果它们不相等则失败。它还可以接受一个格式字符串,用于自定义错误消息。 -
assert_ne!:这与assert_eq!类似,因为它接受两个值,但只有在值不相等时才进行断言。 -
debug_assert!:这与assert!类似。调试断言宏也可以用于除测试代码之外的代码。这主要用于代码中,以断言在运行时应该保持的任何合同或不变量。这些断言仅在调试构建中有效,并在以调试模式运行时帮助捕获断言违规。当代码以优化模式编译时,这些宏调用将被完全忽略并优化为无操作。还有类似的变体,如debug_assert_eq!和debug_assert_ne!,它们的工作方式与assert!类宏相同。
要比较这些断言宏内的值,Rust 依赖于特质。例如,assert!(a == b)中的==实际上变成了一个方法调用,a.eq(&b),它返回一个bool值。eq方法来自PartialEq特质。Rust 中的大多数内置类型都实现了PartialEq和Eq特质,以便它们可以被比较。这些特质的细节以及PartialEq和Eq之间的区别在第四章,“类型、泛型和特质”中进行了讨论。
对于用户定义的类型,我们需要实现这些特质。幸运的是,Rust 为我们提供了一个方便的宏,称为 derive,它接受一个或多个要实现的特质名称。它可以通过在用户定义类型上放置 #[derive(Eq, PartialEq)] 注解来使用。注意括号内的特质名称。Derive 是一个过程宏,它简单地为出现在其上的类型生成 impl 块的代码,并实现特质的方 法或任何关联函数。我们将在第九章 宏编程中讨论这些宏。
除了这些,让我们开始编写一些测试!
单元测试
通常,单元测试是一个实例化应用程序的小部分并独立于代码库的其他部分验证其行为的函数**。**在 Rust 中,单元测试通常在模块内编写。理想情况下,它们应该只旨在覆盖模块的功能和接口。
第一个单元测试
以下是我们非常第一个单元测试:
// first_unit_test.rs
#[test]
fn basic_test() {
assert!(true);
}
单元测试是以函数的形式编写的,并带有 #[test] 属性。前面的 basic_test 函数中没有什么复杂的内容。我们有一个基本的 assert! 调用,传递 true。为了更好的组织,你也可以创建一个名为 tests 的子模块(按照惯例),并将所有相关的测试代码放在其中。
运行测试
我们运行这个测试的方式是通过以测试模式编译我们的代码。编译器会忽略测试注解函数的编译,除非被指示以测试模式构建。这可以通过在编译测试代码时传递 --test 标志给 rustc 来实现。之后,可以通过简单地执行编译后的二进制文件来运行测试。对于前面的测试,我们将通过运行以下命令以测试模式编译它:
rustc --test first_unit_test.rs
使用 --test 标志,rustc 会放置一个带有一些测试框架代码的 main 函数,并将所有定义的测试函数作为线程并行调用。默认情况下,所有测试都是并行运行的,除非通过环境变量 RUST_TEST_THREADS=1 指示。这意味着如果我们想以单线程模式运行前面的测试,我们可以通过 RUST_TEST_THREADS=1 ./first_unit_test 来执行。
现在,Cargo 已经支持运行测试,所有这些通常都是通过调用 cargo test 命令来内部完成的。这个命令会为我们编译并运行带有测试注解的函数。在接下来的示例中,我们将主要使用 Cargo 来运行我们的测试。
隔离测试代码
当我们的测试变得复杂时,可能会有一些额外的辅助方法,我们可能会创建,这些方法仅在测试代码的上下文中使用。在这种情况下,将测试相关代码与实际代码隔离是有益的。我们可以通过将所有测试相关代码封装在一个模块中,并在其上放置 #[cfg(test)] 注解来实现这一点。
#[cfg(...)] 属性中的 cfg 通常用于条件编译,并不仅限于测试代码。它可以包括或排除不同架构或配置标志的代码。在这里,配置标志是 test。你可能还记得,上一章中的测试已经使用了这种形式。这有一个优点,即你的测试代码只有在运行 cargo test 时才会被编译并包含在编译的二进制文件中,否则会被忽略。
假设你想为测试程序生成测试数据,但没有理由在发布构建中包含那段代码。让我们通过运行 cargo new unit_test --lib 来创建一个项目来演示这一点。在 lib.rs 中,我们定义了一些测试和函数:
// unit_test/src/lib.rs
// function we want to test
fn sum(a: i8, b: i8) -> i8 {
a + b
}
#[cfg(test)]
mod tests {
fn sum_inputs_outputs() -> Vec<((i8, i8), i8)> {
vec![((1, 1), 2), ((0, 0), 0), ((2, -2), 0)]
}
#[test]
fn test_sums() {
for (input, output) in sum_inputs_outputs() {
assert_eq!(crate::sum(input.0, input.1), output);
}
}
}
我们可以通过运行 cargo test 来运行这些测试。让我们回顾一下前面的代码。我们在 sum_inputs_outputs 函数中生成已知输入和输出对,该函数被 test_sums 函数使用。#[test] 属性使 test_sums 函数不包含在我们的发布编译中。然而,sum_inputs_outputs 没有标记为 #[test],如果它在 tests 模块外部声明,它将被包含在编译中。通过使用 #[cfg(test)] 与 mod tests {} 子模块,并将所有测试代码及其相关函数封装在这个模块中,我们得到了保持代码和生成的二进制文件清洁的好处,不包含测试代码。
我们还将 sum 函数定义为私有,没有使用 pub 可见性修饰符,这意味着模块内的单元测试也允许你测试私有函数和方法。非常方便!
失败测试
在某些测试用例中,你可能希望你的 API 方法根据某些输入失败,并且希望测试框架断言这种失败。Rust 提供了一个名为 #[should_panic] 的属性来实现这一点。以下是一个引发 panic 并使用此属性的测试用例:
// panic_test.rs
#[test]
#[should_panic]
fn this_panics() {
assert_eq!(1, 2);
}
#[should_panic] 属性可以与 #[test] 属性一起使用,表示运行 this_panics 函数应该导致不可恢复的失败,这在 Rust 中被称为 panic。
忽略测试
编写测试的另一个有用属性是 #[ignore]。如果你的测试代码非常复杂,使用 #[ignore] 注解可以让测试运行器在运行 cargo test 时忽略这些测试函数。然后你可以选择单独运行这些测试,通过向测试运行器或 cargo test 命令提供 --ignored 参数来实现。以下是一个包含愚蠢循环的代码示例,当使用 cargo test 运行时,默认会被忽略:
// silly_loop.rs
pub fn silly_loop() {
for _ in 1..1_000_000_000 {};
}
#[cfg(test)]
mod tests {
#[test]
#[ignore]
pub fn test_silly_loop() {
::silly_loop();
}
}
注意 test_silly_loop 测试函数上的 #[ignore] 属性。以下是忽略测试的输出:
https://github.com/OpenDocCN/freelearn-rust-zh/raw/master/docs/ms-rs-2e/img/fe9815c7-ab4a-44d5-a9c2-34f6393962db.png注意:也可以通过向 Cargo 提供测试函数名来运行单个测试,例如,cargo test some_test_func。
集成测试
虽然单元测试可以测试你的 crate 的私有接口和单个模块,但集成测试更像是一种黑盒测试,旨在从消费者的角度测试 crate 公共接口的端到端使用。在编写代码方面,编写集成测试和单元测试之间没有太大的区别。唯一的区别在于目录结构,并且需要将项目公开,这已经由 crate 的设计者公开了。
第一次集成测试
如我们之前所述,Rust 期望所有集成测试都位于tests/目录中。tests/目录中的文件被编译为似乎它们是单独的二进制 crate,同时使用我们正在测试的库。对于以下示例,我们将通过运行cargo new integration_test --lib创建一个新的 crate,与之前的单元测试具有相同的函数sum,但现在我们添加了一个tests/目录,其中定义了一个如下所示的集成测试函数:
// integration_test/tests/sum.rs
use integration_test::sum;
#[test]
fn sum_test() {
assert_eq!(sum(6, 8), 14);
}
我们首先将函数sum引入作用域。其次,我们有一个名为sum_test的函数,它调用sum并断言返回值。当我们尝试运行cargo test时,我们遇到了以下错误:
这个错误看起来是合理的。我们希望我们的 crate 的用户使用sum函数,但在我们的 crate 中,我们默认将其定义为私有函数。因此,在sum函数前添加pub修饰符并运行cargo test后,我们的测试再次变为绿色:
这里是我们integration_test示例 crate 的目录树视图:
.
├── Cargo.lock
├── Cargo.toml
├── src
│ └── lib.rs
└── tests
└── sum.rs
作为集成测试的一个例子,这非常简单,但它的要点是,当我们编写集成测试时,我们使用正在测试的 crate,就像任何其他库的用户使用它一样。
共享通用代码
正如集成测试通常所做的那样,我们需要在运行测试之前放置一些设置和清理相关的代码。通常,我们希望这些代码在tests/目录下的所有文件中共享。为了共享代码,我们可以通过创建一个共享通用代码的目录,或者使用一个名为foo.rs的模块,并在我们的集成测试文件中通过放置一个mod声明来声明我们依赖于它。因此,在我们的前一个tests/目录中,我们添加了一个名为common.rs的模块,其中包含两个名为setup和teardown的函数:
// integration_test/tests/common.rs
pub fn setup() {
println!("Setting up fixtures");
}
pub fn teardown() {
println!("Tearing down");
}
在我们的两个函数中,我们可以包含任何类型的固定相关代码。考虑一下,如果你有一个依赖于文本文件存在的集成测试。在我们的setup函数中,我们可以创建文本文件,而在我们的teardown函数中,我们可以通过删除文件来清理资源。
要在我们的tests/sum.rs集成测试代码中使用这些函数,我们按照如下方式添加mod声明:
// integration_test/tests/sum.rs
use integration_test::sum;
mod common;
use common::{setup, teardown};
#[test]
fn sum_test() {
assert_eq!(sum(6, 8), 14);
}
#[test]
fn test_with_fixture() {
setup();
assert_eq!(sum(7, 14), 21);
teardown();
}
我们添加了另一个函数,test_with_fixture,它包括对setup和teardown的调用。我们可以通过cargo test test_with_fixture运行这个测试。正如你可能从输出中注意到的,我们在setup或teardown函数内部看不到任何println!调用。这是因为默认情况下,测试框架会隐藏或捕获测试函数内的打印语句,以使测试结果更整洁,并且只显示测试框架的输出。如果我们想在测试中查看打印语句,我们可以通过cargo test test_with_fixture -- --nocapture运行测试,这将给出以下输出:
我们现在可以看到我们的打印语句了。我们需要在cargo test test_with_fixture -- --nocapture中使用--,因为我们实际上想将--nocapture标志传递给我们的测试运行器。--标记了cargo本身的参数结束,并且任何随后的参数都传递给由 cargo 调用的二进制文件,即我们的带有测试框架的编译二进制文件。
集成测试就到这里。在本章结束时,我们将创建一个项目,在那里我们可以看到单元测试和集成测试协同工作。接下来,我们将学习如何编写 Rust 代码的文档,这是软件开发中一个被忽视但相当重要的部分。
文档
文档是任何开源软件面向程序员社区广泛采用的一个非常关键的部分。虽然你的代码,应该是可读的,告诉你它是如何工作的,但文档应该告诉你设计决策的原因和如何以及公共 API 的示例用法。一个良好的文档,带有全面的README.md页面,可以大大提高你项目的可发现性。
Rust 社区非常重视文档,并在各个级别提供了工具,使编写代码文档变得容易。它还使文档对用户来说易于展示和消费。对于编写文档,它支持 Markdown 方言。Markdown 是一种非常流行的标记语言,并且现在是编写文档的标准。Rust 有一个专门的工具叫做rustdoc,它可以解析 Markdown 文档注释,将它们转换为 HTML,并生成美丽且可搜索的文档页面。
编写文档
要编写文档,我们有特殊的符号来标记文档注释的开始(以下称为 doc 注释)。文档的编写方式与编写注释类似,但与普通注释相比,它们被处理得不同,并且由 rustdoc 解析。doc 注释分为两个级别,并使用不同的符号来标记 doc 注释的开始:
-
项目级别:这些注释是针对模块内的项目,如结构体、枚举声明、函数、特质常量等。它们应该出现在项目上方。对于单行注释,它们以
///开头,而多行注释以/**开头,以*/结尾。 -
模块级别:这些是在根级别出现的注释,即
main.rs、lib.rs或任何其他模块,并使用//!来标记行注释的开始——或者使用/*!来标记多行注释——在结束前使用*/。它们适合提供对 crate 的一般概述和示例用法。
在文档注释中,你可以使用常规的 Markdown 语法来编写文档。它还支持在反引号(```rs`let a = 23;````)内编写有效的 Rust 代码,这将成为文档测试的一部分。
之前用于编写注释的符号实际上是#[doc="your doc comment"]属性的语法糖。这些被称为文档属性。当 rustdoc 解析///或/**行时,它会将它们转换为这些文档属性。或者,你也可以使用这些文档属性来编写文档。
生成和查看文档
要生成文档,我们可以在项目目录中使用cargo doc命令。它会在target/doc/目录下生成包含许多 HTML 文件和预定义样式的文档。默认情况下,它还会为 crate 的依赖项生成文档。我们可以通过运行cargo doc --no-deps来告诉 Cargo 忽略为依赖项生成文档。
要查看文档,可以在target/doc目录内导航以启动一个 HTTP 服务器。Python 的简单 HTTP 服务器在这里很有用。然而,还有更好的方法!将--open选项传递给cargo doc将直接在默认浏览器中打开文档页面。
cargo doc可以与cargo watch结合使用,以在编写文档并获得对项目上任何文档更改的实时反馈时获得无缝体验。
托管文档
在你的文档生成后,你需要将其托管在某个地方供公众查看和使用。这里有三种可能性:
-
docs.rs:托管在
crates.io上的 crate 会自动生成并托管在docs.rs上的文档页面。 -
GitHub pages:如果你的 crate 在 GitHub 上,你可以将其文档托管在
gh-pages分支上。 -
外部网站:你可以管理自己的 Web 服务器来托管文档。Rust 的标准库文档就是这样一个很好的例子:
doc.rust-lang.org/std/。
作为附加说明,如果你的项目文档超过两到三页,并且需要详细的介绍,那么有一个更好的选项来生成类似书籍的文档。这是通过使用mdbook项目来实现的。有关更多信息,请查看他们的 GitHub 页面github.com/rust-lang-nursery/mdBook。
文档属性
我们提到,我们编写的文档注释会被转换成文档属性形式。除了这些,还有其他文档属性可以调整生成的文档页面,这些属性可以在 crate 级别或项目级别应用。它们被写成#[doc(key = value)]的形式。以下是一些最有用的文档属性:
crate 级属性:
-
#![doc(html_logo_url = "image url")]: 允许您在文档页面的左上角添加一个标志。 -
#![doc(html_root_url = "https://docs.rs/slotmap/0.2.1")]: 允许您设置文档页面的 URL。 -
#![doc(html_playground_url = "https://play.rust-lang.org/")]: 允许您在文档中的代码示例附近放置一个运行按钮,以便您可以直接在在线 Rust playground 中运行它。
项目级属性:
-
#[doc(hidden)]: 假设您已经为公开函数foo编写了文档,作为自己的笔记。然而,您不希望您的消费者查看这些文档。您可以使用此属性告诉 rustdoc 忽略为foo生成文档。 -
#[doc(include)]: 这可以用来包含来自其他文件的文档。如果文档真的很长,这有助于您将文档与代码分离。
对于更多此类属性,请访问doc.rust-lang.org/beta/rustdoc/the-doc-attribute.html。
文档测试
在为 crate 的公开 API 编写任何文档时包含代码示例通常是一个好习惯。尽管如此,维护这些示例也存在一个注意事项。您的代码可能会更改,您可能会忘记更新示例。文档测试(doctests)就是为了提醒您更新示例代码。Rust 允许您在文档注释中嵌入反引号内的代码。然后 Cargo 可以运行嵌入在文档中的示例代码,并将其视为单元测试套件的一部分。这意味着文档示例会在您运行单元测试时运行,迫使您更新它们。这非常神奇!
文档测试也是通过 Cargo 执行的。我们创建了一个名为doctest_demo的项目来展示文档测试。在lib.rs中,我们有以下代码:
// doctest_demo/src/lib.rs
//! This crate provides functionality for adding things
//!
//! # Examples
//! ```
//! use doctest_demo::sum;
//!
//! let work_a = 4;
//! let work_b = 34;
//! let total_work = sum(work_a, work_b);
//! ```rs
/// Sum two arguments
///
/// # Examples
///
/// ```
/// assert_eq!(doctest_demo::sum(1, 1), 2);
/// ```rs
pub fn sum(a: i8, b: i8) -> i8 {
a + b
}
如您所见,模块级和函数级文档测试之间的区别不大。它们的使用方式几乎相同。只是模块级文档测试显示了 crate 的整体使用情况,覆盖了多个 API 界面,而函数级文档测试仅覆盖它们出现的特定函数。
当您运行cargo test时,文档测试会与其他所有测试一起运行。以下是我们运行doctest_demo crate 中的cargo test时的输出:
基准测试
当业务需求发生变化,并且你的程序需要更高效地执行时,首先要采取的步骤是找出程序中缓慢的区域。你如何判断瓶颈在哪里?你可以通过在各个预期的范围或输入量级上测量程序的单个部分来了解。这被称为基准测试你的代码。基准测试通常在开发的最后阶段进行(但不必如此),以提供关于代码中性能陷阱的见解。
对于一个程序,有多种方式进行基准测试。最简单的方法是使用 Unix 工具 time 来测量你更改后的程序执行时间。但这并不提供精确的微级洞察。Rust 为我们提供了一个内置的微基准测试框架。通过微基准测试,我们指的是它可以用来独立基准测试代码的各个部分,并且不受外部因素的影响。然而,这也意味着我们不应该仅仅依赖于微基准测试,因为现实世界的结果可能会被扭曲。因此,微基准测试通常随后会进行代码的剖析和宏基准测试。尽管如此,微基准测试通常是提高你代码性能的起点,因为各个部分对程序的总体运行时间贡献很大。
在本节中,我们将讨论 Rust 提供的用于执行微基准测试的内置工具。Rust 从开发初期就降低了编写基准测试代码的门槛,而不是作为最后的手段。运行基准测试的方式与运行测试类似,但使用的是cargo bench命令。
内置的微基准测试工具
Rust 的内置基准测试框架通过运行多次迭代来衡量代码的性能,并报告操作的平均时间。这由以下两点促成:
-
函数上的
#[bench]注解。这表示该函数是一个基准测试。 -
内部编译器 crate
libtest,其中包含一个Bencher类型,基准测试函数使用它来运行多次相同的基准测试代码。此类型位于编译器内部的testcrate 下。
现在,我们将编写并运行一个简单的基准测试。让我们通过运行cargo new --lib bench_example来创建一个新的 Cargo 项目。对于这个项目,不需要对Cargo.toml进行任何更改。src/lib.rs的内容如下:
// bench_example/src/lib.rs
#![feature(test)]
extern crate test;
use test::Bencher;
pub fn do_nothing_slowly() {
print!(".");
for _ in 1..10_000_000 {};
}
pub fn do_nothing_fast() {
}
#[bench]
fn bench_nothing_slowly(b: &mut Bencher) {
b.iter(|| do_nothing_slowly());
}
#[bench]
fn bench_nothing_fast(b: &mut Bencher) {
b.iter(|| do_nothing_fast());
}
注意,我们必须使用external crate声明和#[feature(test)]属性来指定内部 crate test。extern声明对于编译器内部的 crate 是必需的。在编译器的未来版本中,这可能不再需要,你将能够像正常 crate 一样use它们。
如果我们通过运行cargo bench来运行基准测试,我们将看到以下内容:
不幸的是,基准测试是一个不稳定的功能,所以我们将不得不使用夜间编译器来执行这些测试。幸运的是,使用 rustup 在 Rust 编译器的不同发布渠道之间切换很容易。首先,我们将通过运行 rustup update nightly 来确保夜间编译器已安装。然后,在我们的 bench_example 目录中,我们将通过运行 rustup override set nightly 来覆盖此目录的默认工具链。现在,运行 cargo bench 将给出以下输出:
这些是每次迭代的纳秒数,括号内的数字显示了每次运行之间的变化。我们的较慢实现运行速度相当慢且变化很大(如大的 +/- 变化所示)。
在我们标记为 #[bench] 的函数内部,iter 的参数是一个无参数的闭包。如果闭包有参数,它们将位于 || 内。这本质上意味着 iter 被传递了一个可以被基准测试重复运行的函数。我们在函数中打印一个点,这样 Rust 就不会优化掉空循环。如果没有 println!(),那么编译器就会将循环优化为一个无操作,我们会得到错误的结果。有方法可以绕过这个问题,这是通过使用 test 模块中的 black_box 函数来实现的。然而,即使使用了那个函数,也不能保证优化器不会优化你的代码。现在,我们也有其他第三方解决方案来在稳定版 Rust 上运行基准测试。
在稳定版 Rust 上的基准测试
Rust 提供的内置基准测试框架是不稳定的,但幸运的是,有一些社区开发的基准测试 crate 可以在稳定版 Rust 上工作。我们将在这里探索的一个流行的 crate 是 criterion-rs。这个 crate 设计得易于使用,同时提供有关基准测试代码的详细信息。它还维护了上次运行的状
为了演示如何使用这个 crate,我们将创建一个新的 crate,名为 cargo new criterion_demo --lib。我们将 criterion crate 添加到 Cargo.toml 中的 dev-dependencies 部分作为依赖项:
[dev-dependencies]
criterion = "0.1"
[[bench]]
name = "fibonacci"
harness = false
我们还添加了一个新的部分,称为 [[bench]],它指示 cargo 我们有一个名为 fibonacci 的新基准测试,并且它不使用内置的基准测试工具(harness = false),因为我们正在使用 criterion crate 的测试工具。
现在,在 src/lib.rs 中,我们有一个计算第 n 个 fibonacci 数(初始值为 n[0] = 0 和 n[1] = 1)的函数的快速和慢速版本:
// criterion_demo/src/lib.rs
pub fn slow_fibonacci(nth: usize) -> u64 {
if nth <= 1 {
return nth as u64;
} else {
return slow_fibonacci(nth - 1) + slow_fibonacci(nth - 2);
}
}
pub fn fast_fibonacci(nth: usize) -> u64 {
let mut a = 0;
let mut b = 1;
let mut c = 0;
for _ in 1..nth {
c = a + b;
a = b;
b = c;
}
c
}
fast_fibonacci 是获取第 n 个斐波那契数的自底向上的迭代解决方案,而 slow_fibonacci 版本则是较慢的递归版本。现在,criterion-rs 要求我们将基准测试放在一个 benches/ 目录中,我们在 crate 根目录下创建了它。在 benches/ 目录中,我们还创建了一个名为 fibonacci.rs 的文件,它与 Cargo.toml 中的 [[bench]] 下的名称相匹配。其内容如下:
// criterion_demo/benches/fibonacci.rs
#[macro_use]
extern crate criterion;
extern crate criterion_demo;
use criterion_demo::{fast_fibonacci, slow_fibonacci};
use criterion::Criterion;
fn fibonacci_benchmark(c: &mut Criterion) {
c.bench_function("fibonacci 8", |b| b.iter(|| slow_fibonacci(8)));
}
criterion_group!(fib_bench, fibonacci_benchmark);
criterion_main!(fib_bench);
这里有很多事情在进行中!在上面的代码中,我们首先声明了所需的 crate 并导入了我们需要基准测试的 fibonacci 函数(fast_fibonacci 和 slow_fibonacci)。此外,在 extern crate criterion 上有一个 #[macro_use] 属性,这意味着要使用来自 crate 的任何宏,我们需要使用此属性来选择它,因为它们默认没有暴露。这类似于一个 use 语句,它用于暴露模块项。
现在,criterion 有一个概念叫做基准测试组,它可以包含相关的基准测试代码。相应地,我们创建了一个名为 fibonacci_benchmark 的函数,然后将其传递给 criterion_group! 宏。这给这个基准测试组分配了一个名为 fib_bench 的名称。fibonacci_benchmark 函数接收一个对 criterion 对象的可变引用,该对象持有我们的基准测试运行的状态。这暴露了一个名为 bench_function 的方法,我们使用它将我们的基准测试代码传递到一个具有给定名称的闭包中(上面是 fibonacci 8)。然后,我们需要创建主要的基准测试 harness,它使用 criterion_main! 生成带有 main 函数的代码来运行所有这些,在传递我们的基准测试组 fib_bench 之前。现在,是时候运行 cargo bench 并在闭包中包含第一个 slow_fibonacci 函数了。我们得到以下输出:
我们可以看到,我们的 fibonacci 函数的递归版本平均运行时间约为 106.95 纳秒。现在,在同一个基准测试闭包中,如果我们用 fast_fibonacci 替换 slow_fibonacci 并再次运行 cargo bench,我们将得到以下输出:
太棒了!fast_fibonacci 版本平均运行时间仅为 7.8460 纳秒。这是显而易见的,但真正令人兴奋的是详细的基准测试报告,它还显示了一个人性化的消息:性能已提升。criterion 能够显示这个回归报告的原因是它维护了基准测试运行的先前状态,并使用它们的历史记录来报告性能的变化。
编写和测试一个 crate – 逻辑门模拟器
带着所有这些知识,让我们开始我们的逻辑门模拟 crate。通过运行cargo new logic_gates --lib来创建一个新的项目。从实现为函数的原始门开始,例如and、xor等,我们将为这些门编写单元测试。随后,我们将通过实现使用我们的原始门的半加器来编写集成测试。在这个过程中,我们还将为我们的 crate 编写文档。
首先,我们将从一些单元测试开始。以下是初始的 crate 代码的完整内容:
//! This is a logic gates simulation crate built to demonstrate writing unit tests and integration tests
// logic_gates/src/lib.rs
pub fn and(a: u8, b: u8) -> u8 {
unimplemented!()
}
pub fn xor(a: u8, b: u8) -> u8 {
unimplemented!()
}
#[cfg(test)]
mod tests {
use crate::{xor, and};
#[test]
fn test_and() {
assert_eq!(1, and(1, 1));
assert_eq!(0, and(0, 1));
assert_eq!(0, and(1, 0));
assert_eq!(0, and(0, 0));
}
#[test]
fn test_xor() {
assert_eq!(1, xor(1, 0));
assert_eq!(0, xor(0, 0));
assert_eq!(0, xor(1, 1));
assert_eq!(1, xor(0, 1));
}
}
我们从两个逻辑门and和xor开始,这些门已经作为函数实现。我们还有针对它们的测试用例,当运行时因为它们尚未实现而失败。注意,为了表示比特0和1,我们使用u8,因为 Rust 没有原生的类型来表示比特。现在,让我们填写它们的实现,以及一些文档:
/// Implements a boolean `and` gate taking as input two bits and returns a bit as output
pub fn and(a: u8, b: u8) -> u8 {
match (a, b) {
(1, 1) => 1,
_ => 0
}
}
/// Implements a boolean `xor` gate taking as input two bits and returning a bit as output
pub fn xor(a: u8, b: u8) -> u8 {
match (a, b) {
(1, 0) | (0, 1) => 1,
_ => 0
}
}
在前面的代码中,我们只是使用 match 表达式表达了and和xor门的真值表。我们可以看到 match 表达式在表达我们的逻辑时是多么简洁。现在,我们可以通过运行cargo test来运行测试:
全部绿色!我们现在可以使用这些门实现半加器来编写集成测试。半加器完美地适合作为集成测试示例,因为它在组件被一起使用时测试了我们的 crate 的各个部分。在tests/目录下,我们将创建一个名为half_adder.rs的文件,其中包含以下代码:
// logic_gates/tests/half_adder.rs
use logic_gates::{and, xor};
pub type Sum = u8;
pub type Carry = u8;
pub fn half_adder_input_output() -> Vec<((u8, u8), (Sum, Carry))> {
vec![
((0, 0), (0, 0)),
((0, 1), (1, 0)),
((1, 0), (1, 0)),
((1, 1), (0, 1)),
]
}
/// This function implements a half adder using primitive gates
fn half_adder(a: u8, b: u8) -> (Sum, Carry) {
(xor(a, b), and(a, b))
}
#[test]
fn one_bit_adder() {
for (inn, out) in half_adder_input_output() {
let (a, b) = inn;
println("Testing: {}, {} -> {}", a, b, out);
assert_eq!(half_adder(a, b), out);
}
}
在前面的代码中,我们导入了我们的原始门函数xor和and。随后,我们有类似pub type Sum = u8的东西,这被称为类型别名。它们在以下情况下很有帮助:当你有一个每次都难以书写的类型,或者当你有具有复杂签名的类型时。它为我们原始类型提供了一个新名称,纯粹是为了可读性和消除歧义;它对 Rust 分析这些类型的方式没有影响。然后我们在half_adder_input_output函数中使用Sum和Carry,该函数实现了半加器的真值表。这是一个方便的辅助函数,用于测试随后的half_adder函数。这个函数接受两个单比特输入,并从它们中计算出Sum和Carry,然后作为(Sum, Carry)元组返回。进一步,我们有我们的one_bit_adder集成测试函数,其中我们遍历半加器输入输出对,并对half_adder的输出进行断言。通过运行cargo test,我们得到以下输出:
太棒了!让我们也通过运行 cargo doc --open 为我们的 crate 生成文档。--open 标志会在浏览器中为我们打开页面。为了自定义我们的文档,我们还将向 crate 文档页面添加一个图标。为此,我们需要在 lib.rs 的顶部添加以下属性:
#![doc(html_logo_url = "https://d30y9cdsu7xlg0.cloudfront.net/png/411962-200.png")]
生成后,文档页面看起来是这样的:
这太棒了!我们在测试之旅上已经走了很长的路。接下来,让我们看看自动化测试套件的方面。
与 Travis CI 进行持续集成
在大型软件系统中,对于代码的每一次更改,我们通常都希望自动运行我们的单元测试和集成测试。此外,在协作项目中,手动方式显然不切实际。幸运的是,持续集成是一种旨在自动化软件开发这些方面的实践。Travis CI 是一个公共持续集成服务,允许您根据事件钩子在云中自动运行您项目的测试。事件钩子的一个例子是在推送新提交时。
Travis 通常用于自动化运行构建和测试以及报告失败的构建,但也可以用于创建发布版本,甚至部署到预发布或生产环境。在本节中,我们将关注 Travis 的一个方面,即为我们项目执行自动测试。GitHub 已经集成了 Travis,可以为我们项目的每个新提交运行测试。为了实现这一点,我们需要以下内容:
-
我们在 GitHub 上的项目
-
通过使用 GitHub 登录创建的 Travis 账户
-
您的项目已在 Travis 中启用构建
-
在您的仓库根目录下的
.travis.yml文件,告诉 Travis 要运行什么
第一步是前往 travis-ci.org/ 并使用您的 GitHub 凭据登录。从那里,我们可以在 Travis 中添加我们的 GitHub 仓库。Travis 对 Rust 项目有良好的原生支持,并持续更新其 Rust 编译器。它为 Rust 项目提供了一个基本的 .travis.yml 文件,如下所示:
language: rust
rust:
- stable
- beta
- nightly
matrix:
allow_failures:
- rust: nightly
Rust 项目还建议针对 beta 和 nightly 频道进行测试,但您可以选择通过删除相应的行来仅针对单个版本进行目标。此推荐设置在所有三个版本上运行测试,但允许快速移动的 nightly 编译器失败。
在您的仓库中拥有这个 .travis.yml 文件,GitHub 将在您每次推送代码并运行测试时通知 Travis CI。我们还可以将构建状态徽章附加到仓库的 README.md 文件中,当测试通过时显示绿色徽章,当测试失败时显示红色徽章。
让我们将 Travis 与我们的 logic_gates crate 集成。为此,我们必须在 crate 根目录下添加一个 .travis.yml 文件。以下是为 .travis.yml 文件的内容:
language: rust
rust:
- stable
- beta
- nightly
matrix:
allow_failures:
- rust: nightly
fast_finish: true
cache: cargo
script:
- cargo build --verbose
- cargo test --verbose
将此推送到 GitHub 后,我们接下来需要在他们的页面上启用 Travis 以用于我们的项目,如下所示:
之前的截图来自我的 TravisCI 账户。现在,我们将通过向我们的logic_gates仓库添加一个简单的README.md文件来提交一个 commit,以触发 Travis 构建运行器。在此过程中,我们还将向README.md文件添加一个构建徽章,以便向消费者展示我们仓库的状态。为此,我们将点击右侧的构建通过徽章:
这将打开一个包含徽章链接的弹出菜单:
我们将复制此链接并将其添加到README.md文件的顶部,如下所示:
[<https://travis-ci.org/$USERNAME/$REPO_NAME.svg?branch=master>](https://travis-ci.org/creativcoder/logic_gates)
您需要将$USERNAME和$REPO_NAME替换为您自己的详细信息。
在此更改并提交README.md文件之后,我们将开始看到 Travis 构建开始并成功:
太棒了!如果您更有雄心,您还可以尝试在 GitHub 仓库的gh-pages分支上托管logic_gates crate 的文档。您可以通过使用可在github.com/roblabla/cargo-travis找到的cargo-travis项目来实现这一点。
对于一个更通用的 CI 设置,它涵盖了主要平台,您可以使用信任项目提供的模板,该模板可在github.com/japaric/trust找到。
最后,为了在crates.io上发布您的 crate,您可以按照 Cargo 参考文档中给出的说明操作:doc.rust-lang.org/cargo/reference/publishing.html。
摘要
在本章中,我们熟悉了使用rustc和cargo工具编写单元测试、集成测试、文档测试和基准测试。然后,我们实现了一个逻辑门模拟 crate,并体验了整个 crate 开发工作流程。之后,我们学习了如何将 Travis CI 集成到我们的 GitHub 项目中。
在下一章中,我们将探讨 Rust 的类型系统以及如何在编译时使用它来在我们的程序中表达正确的语义。
1564



被折叠的 条评论
为什么被折叠?



