Rust 程序设计语言

将 Crate 发布到 Crates.io

我们使用了来自 crates.io 的包作为我们项目的依赖项，但您也可以通过发布自己的包来与他人分享您的代码。位于 crates.io 的 crate 注册中心分发您的包的源代码，因此它主要托管开源代码。

Rust 和 Cargo 具有一些特性，使您发布的包更容易被人们找到和使用。接下来我们将讨论其中的一些特性，然后解释如何发布包。

编写有用的文档注释

准确地为您的包编写文档将帮助其他用户了解如何以及何时使用它们，因此值得投入时间来编写文档。在第 3 章中，我们讨论了如何使用双斜杠 // 来注释 Rust 代码。Rust 还有一种特殊的注释类型用于文档，方便地称为文档注释，它将生成 HTML 文档。HTML 显示文档注释的内容，这些注释是针对那些有兴趣了解如何使用您的 crate 而不是您的 crate 是如何实现的程序员的公共 API 条目。

文档注释使用三个斜杠 /// 而不是两个，并支持 Markdown 符号来格式化文本。将文档注释放在它们所文档化的条目之前。列表 14-1 展示了一个名为 my_crate 的 crate 中 add_one 函数的文档注释。

/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

在这里，我们给出了 add_one 函数作用的描述，以标题 Examples 开始一个章节，然后提供演示如何使用 add_one 函数的代码。我们可以通过运行 cargo doc 从此文档注释生成 HTML 文档。此命令运行随 Rust 分发的 rustdoc 工具，并将生成的 HTML 文档放在 target/doc 目录中。

为了方便起见，运行 cargo doc --open 将为您当前 crate 的文档（以及您的 crate 所有依赖项的文档）构建 HTML，并在 Web 浏览器中打开结果。导航到 add_one 函数，您将看到文档注释中的文本是如何呈现的，如图 14-1 所示

图 14-1：add_one 函数的 HTML 文档

常用章节

我们在列表 14-1 中使用了 # Examples Markdown 标题来在 HTML 中创建一个标题为“Examples”的章节。以下是 crate 作者在文档中常用的其他章节

• Panics：文档化的函数可能发生 panic 的场景。不希望程序 panic 的函数调用者应确保他们不会在这些情况下调用该函数。
• Errors：如果函数返回 Result，描述可能发生的错误类型以及可能导致返回这些错误的条件，对调用者可能很有帮助，以便他们可以编写代码以不同的方式处理不同类型的错误。
• Safety：如果函数是 unsafe 的（我们在第 20 章中讨论了不安全性），则应有一个章节解释该函数为何不安全，并涵盖该函数期望调用者维护的不变性。

大多数文档注释不需要所有这些章节，但这是一个很好的清单，可以提醒您用户会对您的代码的哪些方面感兴趣。

文档注释作为测试

在文档注释中添加示例代码块可以帮助演示如何使用您的库，这样做还有一个额外的好处：运行 cargo test 将运行您的文档中的代码示例作为测试！没有什么比带有示例的文档更好了。但是，没有什么比因为代码自文档编写以来已更改而导致示例无法工作更糟糕的了。如果我们使用列表 14-1 中 add_one 函数的文档运行 cargo test，我们将看到测试结果中类似这样的部分

   Doc-tests my_crate

running 1 test
test src/lib.rs - add_one (line 5) ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.27s

现在，如果我们更改函数或示例，以至于示例中的 assert_eq! 发生 panic，并再次运行 cargo test，我们将看到文档测试捕获到示例和代码彼此不同步！

注释包含的条目

文档注释 //! 的样式将文档添加到包含注释的条目，而不是添加到注释后面的条目。我们通常在 crate 根文件（按照惯例为 src/lib.rs）或模块内部使用这些文档注释，以记录整个 crate 或模块。

例如，要添加文档来描述包含 add_one 函数的 my_crate crate 的用途，我们将以 //! 开头的文档注释添加到 src/lib.rs 文件的开头，如列表 14-2 所示

//! # My Crate
//!
//! `my_crate` is a collection of utilities to make performing certain
//! calculations more convenient.

/// Adds one to the number given.
// --snip--
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

请注意，在以 //! 开头的最后一行之后没有任何代码。因为我们以 //! 而不是 /// 开头注释，所以我们正在记录包含此注释的条目，而不是跟随此注释的条目。在这种情况下，该条目是 src/lib.rs 文件，它是 crate 根。这些注释描述了整个 crate。

当我们运行 cargo doc --open 时，这些注释将显示在 my_crate 文档的首页上，位于 crate 中公共条目列表的上方，如图 14-2 所示

图 14-2：my_crate 的渲染文档，包括描述整个 crate 的注释

条目内的文档注释对于描述 crate 和模块尤其有用。使用它们来解释容器的总体用途，以帮助您的用户了解 crate 的组织结构。

使用 pub use 导出方便的公共 API

发布 crate 时，公共 API 的结构是一个主要考虑因素。使用您 crate 的人在结构方面不如您熟悉，如果您的 crate 具有大型模块层次结构，他们可能难以找到他们想要使用的部分。

在第 7 章中，我们介绍了如何使用 pub 关键字使条目公开，以及如何使用 use 关键字将条目引入作用域。但是，在您开发 crate 时对您有意义的结构可能对您的用户来说不是很方便。您可能希望将您的结构体组织成包含多个级别的层次结构，但是然后想要使用您在层次结构深处定义的类型的人可能难以找到该类型的存在。他们也可能对必须输入 use my_crate::some_module::another_module::UsefulType; 而不是 use my_crate::UsefulType; 感到恼火。

好消息是，如果该结构对于其他人从另一个库中使用不方便，您不必重新安排您的内部组织：相反，您可以通过使用 pub use 重新导出条目，以创建一个与您的私有结构不同的公共结构。重新导出在一个位置获取一个公共条目，并使其在另一个位置公开，就好像它是在另一个位置定义的一样。

例如，假设我们创建了一个名为 art 的库，用于建模艺术概念。在此库中，有两个模块：一个 kinds 模块，其中包含两个名为 PrimaryColor 和 SecondaryColor 的枚举，以及一个 utils 模块，其中包含一个名为 mix 的函数，如列表 14-3 所示

//! # Art
//!
//! A library for modeling artistic concepts.

pub mod kinds {
    /// The primary colors according to the RYB color model.
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// The secondary colors according to the RYB color model.
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

pub mod utils {
    use crate::kinds::*;

    /// Combines two primary colors in equal amounts to create
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        // --snip--
        unimplemented!();
    }
}

图 14-3 显示了 cargo doc 生成的此 crate 的文档首页的外观

图 14-3：art 文档的首页，列出了 kinds 和 utils 模块

请注意，PrimaryColor 和 SecondaryColor 类型未列在首页上，mix 函数也未列出。我们必须单击 kinds 和 utils 才能看到它们。

另一个依赖于此库的 crate 将需要 use 语句，这些语句将 art 中的条目引入作用域，并指定当前定义的模块结构。列表 14-4 显示了一个使用 art crate 中 PrimaryColor 和 mix 条目的 crate 示例，其内部结构已导出

use art::kinds::PrimaryColor;
use art::utils::mix;

fn main() {
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}

列表 14-4 中代码的作者，即使用 art crate 的代码，必须弄清楚 PrimaryColor 在 kinds 模块中，而 mix 在 utils 模块中。art crate 的模块结构与 art crate 的开发人员更相关，而不是与使用它的人相关。内部结构不包含任何对试图理解如何使用 art crate 的人有用的信息，而是引起混乱，因为使用它的开发人员必须弄清楚在哪里查找，并且必须在 use 语句中指定模块名称。

要从公共 API 中删除内部组织结构，我们可以修改列表 14-3 中的 art crate 代码，以添加 pub use 语句，以便在顶层重新导出条目，如列表 14-5 所示

//! # Art
//!
//! A library for modeling artistic concepts.

pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;

pub mod kinds {
    // --snip--
    /// The primary colors according to the RYB color model.
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// The secondary colors according to the RYB color model.
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

pub mod utils {
    // --snip--
    use crate::kinds::*;

    /// Combines two primary colors in equal amounts to create
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        SecondaryColor::Orange
    }
}

cargo doc 为此 crate 生成的 API 文档现在将在首页上列出并链接重新导出的内容，如图 14-4 所示，使 PrimaryColor 和 SecondaryColor 类型以及 mix 函数更容易找到。

图 14-4：art 文档的首页，列出了重新导出的内容

art crate 的用户仍然可以像列表 14-4 中演示的那样查看和使用列表 14-3 中的内部结构，或者他们可以使用列表 14-5 中更方便的结构，如列表 14-6 所示

use art::mix;
use art::PrimaryColor;

fn main() {
    // --snip--
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}

在存在许多嵌套模块的情况下，使用 pub use 在顶层重新导出类型可以显着改善使用 crate 的人的体验。pub use 的另一个常见用途是在当前 crate 中重新导出依赖项的定义，以使该 crate 的定义成为您的 crate 公共 API 的一部分。

创建一个有用的公共 API 结构更像是一门艺术而不是一门科学，您可以迭代以找到最适合您用户的 API。选择 pub use 使您可以灵活地组织 crate 的内部结构，并将该内部结构与您呈现给用户的结构分离。查看一些您已安装的 crate 的代码，以查看它们的内部结构是否与它们的公共 API 不同。

设置 Crates.io 账户

在您可以发布任何 crate 之前，您需要在 crates.io 上创建一个账户并获取 API 令牌。为此，请访问 crates.io 的主页并通过 GitHub 账户登录。（GitHub 账户目前是必需的，但该网站将来可能会支持其他创建账户的方式。）登录后，访问您的账户设置 https://crates.io/me/并检索您的 API 密钥。然后运行 cargo login 命令，并在提示时粘贴您的 API 密钥，如下所示

$ cargo login
abcdefghijklmnopqrstuvwxyz012345

此命令将通知 Cargo 您的 API 令牌，并将其本地存储在 ~/.cargo/credentials 中。请注意，此令牌是秘密：不要与任何人分享。如果您出于任何原因与任何人分享，您应该撤销它并在 crates.io 上生成一个新令牌.

向新 Crate 添加元数据

假设您有一个想要发布的 crate。在发布之前，您需要在 crate 的 Cargo.toml 文件的 [package] 部分添加一些元数据。

您的 crate 需要一个唯一的名称。当您在本地处理 crate 时，您可以随意命名 crate。但是，crates.io 上的 crate 名称以先到先得的方式分配。一旦某个 crate 名称被占用，任何人都不能再发布具有该名称的 crate。在尝试发布 crate 之前，搜索您想要使用的名称。如果该名称已被使用，您将需要找到另一个名称并编辑 Cargo.toml 文件 [package] 部分下的 name 字段，以使用新名称进行发布，如下所示

文件名：Cargo.toml

[package]
name = "guessing_game"

即使您选择了唯一的名称，当您此时运行 cargo publish 以发布 crate 时，您也会收到警告，然后收到错误

$ cargo publish
    Updating crates.io index
warning: manifest has no description, license, license-file, documentation, homepage or repository.
See https://doc.rust-lang.net.cn/cargo/reference/manifest.html#package-metadata for more info.
--snip--
error: failed to publish to registry at https://crates.io

Caused by:
  the remote server responded with an error (status 400 Bad Request): missing or empty metadata fields: description, license. Please see https://doc.rust-lang.net.cn/cargo/reference/manifest.html for more information on configuring these field

出现此错误是因为您缺少一些关键信息：需要描述和许可证，以便人们知道您的 crate 的作用以及他们可以在哪些条款下使用它。在 Cargo.toml 中，添加一个只有一两个句子的描述，因为它会与您的 crate 一起出现在搜索结果中。对于 license 字段，您需要给出一个许可证标识符值。Linux 基金会的软件软件包数据交换 (SPDX) 列出了您可以用于此值的标识符。例如，要指定您已使用 MIT 许可证许可您的 crate，请添加 MIT 标识符

文件名：Cargo.toml

[package]
name = "guessing_game"
license = "MIT"

如果您想使用未出现在 SPDX 中的许可证，您需要将该许可证的文本放在一个文件中，将该文件包含在您的项目中，然后使用 license-file 来指定该文件的名称，而不是使用 license 键。

关于哪个许可证适合您的项目的指南超出了本书的范围。Rust 社区中的许多人使用与 Rust 相同的方式许可他们的项目，即使用 MIT OR Apache-2.0 的双重许可证。此实践表明，您还可以指定用 OR 分隔的多个许可证标识符，以便为您的项目拥有多个许可证。

添加了唯一的名称、版本、您的描述和许可证后，准备发布的项目的 Cargo.toml 文件可能如下所示

文件名：Cargo.toml

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"
description = "A fun game where you guess what number the computer has chosen."
license = "MIT OR Apache-2.0"

[dependencies]

Cargo 的文档 描述了您可以指定的其他元数据，以确保其他人可以更轻松地发现和使用您的 crate。

发布到 Crates.io

现在您已经创建了账户，保存了您的 API 令牌，选择了您的 crate 的名称，并指定了所需的元数据，您就可以发布了！发布 crate 会将特定版本上传到 crates.io供其他人使用。

请注意，发布是永久的。版本永远无法被覆盖，代码也无法删除。crates.io 的一个主要目标是充当代码的永久档案，以便所有依赖于来自 crates.io 的 crate 的项目构建将继续工作。允许版本删除会使实现该目标变得不可能。但是，您可以发布的 crate 版本数量没有限制。

再次运行 cargo publish 命令。现在应该成功了

$ cargo publish
    Updating crates.io index
   Packaging guessing_game v0.1.0 (file:///projects/guessing_game)
   Verifying guessing_game v0.1.0 (file:///projects/guessing_game)
   Compiling guessing_game v0.1.0
(file:///projects/guessing_game/target/package/guessing_game-0.1.0)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.19s
   Uploading guessing_game v0.1.0 (file:///projects/guessing_game)

恭喜！您现在已经与 Rust 社区分享了您的代码，任何人都可以轻松地将您的 crate 添加为他们项目的依赖项。

发布现有 Crate 的新版本

当您对 crate 进行了更改并准备发布新版本时，您需要更改 Cargo.toml 文件中指定的 version 值并重新发布。使用 语义版本控制规则 来决定基于您所做的更改类型的适当的下一个版本号。然后运行 cargo publish 以上传新版本。

使用 cargo yank 从 Crates.io 弃用版本

虽然您无法删除 crate 的先前版本，但您可以阻止任何未来的项目将它们添加为新依赖项。当 crate 版本由于某种原因损坏时，这很有用。在这种情况下，Cargo 支持撤回 crate 版本。

撤回版本会阻止新项目依赖于该版本，同时允许所有依赖于它的现有项目继续运行。本质上，撤回意味着所有带有 Cargo.lock 的项目都不会崩溃，并且任何未来生成的 Cargo.lock 文件都不会使用撤回的版本。

要撤回 crate 的版本，请在您先前发布的 crate 的目录中，运行 cargo yank 并指定您要撤回的版本。例如，如果我们发布了一个名为 guessing_game 的 crate 版本 1.0.1，并且我们想要撤回它，在 guessing_game 的项目目录中，我们将运行

$ cargo yank --vers 1.0.1
    Updating crates.io index
        Yank guessing_game@1.0.1

通过向命令添加 --undo，您还可以撤消撤回并允许项目再次开始依赖于某个版本

$ cargo yank --vers 1.0.1 --undo
    Updating crates.io index
      Unyank guessing_game@1.0.1

撤回不会删除任何代码。例如，它不能删除意外上传的秘密。如果发生这种情况，您必须立即重置这些秘密。