|
|
|
@ -98,20 +98,20 @@ test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
|
|
|
|
|
|
|
|
|
|
### 使用 `pub use` 导出合适的公有 API
|
|
|
|
|
|
|
|
|
|
第七章介绍了如何使用 `mod` 关键字来将代码组织进模块中,如何使用 `pub` 关键字将项变为公有,和如何使用 `use` 关键字将项引入作用域。然而对你开发来说很有道理的结果可能对用户来说就不太方便了。你可能希望将结构组织进有多个层次的层级中,不过想要使用被定义在很深层级中的类型的人可能很难发现这些类型是否存在。他们也可能会厌烦使用 `use my_crate::some_module::another_module::UsefulType;` 而不是 `use my_crate::UsefulType;` 来使用类型。
|
|
|
|
|
第七章介绍了如何使用 `mod` 关键字来将代码组织进模块中,如何使用 `pub` 关键字将项变为公有,和如何使用 `use` 关键字将项引入作用域。然而你开发时候使用的文件架构可能并不方便用户。你的结构可能是一个包含多个层级的分层结构,不过这对于用于来说并不方便。这是因为想要使用被定义在很深层级中的类型的人可能很难发现这些类型的存在。他们也可能会厌烦使用 `use my_crate::some_module::another_module::UsefulType;` 而不是 `use my_crate::UsefulType;` 来使用类型。
|
|
|
|
|
|
|
|
|
|
公有 API 的结构是你发布 crate 时主要需要考虑的。crate 用户没有你那么熟悉其结构,并且如果模块层级过大他们可能会难以找到所需的部分。
|
|
|
|
|
|
|
|
|
|
好消息是,如果结果对于用户来说 **不是** 很方便,你也无需重新安排内部组织:你可以选择使用 `pub use` 重导出(re-export)项来使公有结构不同于私有结构。重导出获取位于一个位置的公有项并将其公开到另一个位置,好像它就定义在这个新位置一样。
|
|
|
|
|
好消息是,即使文件结构对于用户来说 **不是** 很方便,你也无需重新安排内部组织:你可以选择使用 `pub use` 重导出(re-export)项来使公有结构不同于私有结构。重导出获取位于一个位置的公有项并将其公开到另一个位置,好像它就定义在这个新位置一样。
|
|
|
|
|
|
|
|
|
|
例如,假设我们创建了一个模块化的充满艺术化气息的库 `art`。在这个库中是一个包含两个枚举 `PrimaryColor` 和 `SecondaryColor` 的模块 `kinds`,以及一个包含函数 `mix` 的模块 `utils`,如示例 14-3 所示:
|
|
|
|
|
例如,假设我们创建了一个描述美术信息的库 `art`。这个库中包含了一个有两个枚举 `PrimaryColor` 和 `SecondaryColor` 的模块 `kinds`,以及一个包含函数 `mix` 的模块 `utils`,如示例 14-3 所示:
|
|
|
|
|
|
|
|
|
|
<span class="filename">文件名: src/lib.rs</span>
|
|
|
|
|
|
|
|
|
|
```rust,ignore
|
|
|
|
|
//! # Art
|
|
|
|
|
//!
|
|
|
|
|
//! 一个模块化的充满艺术化气息的库。
|
|
|
|
|
//! 一个描述美术信息的库。
|
|
|
|
|
|
|
|
|
|
pub mod kinds {
|
|
|
|
|
/// 采用 RGB 色彩模式的主要颜色。
|
|
|
|
@ -148,7 +148,7 @@ pub mod utils {
|
|
|
|
|
|
|
|
|
|
<span class="caption">图 14-3:包含 `kinds` 和 `utils` 模块的库 `art` 的文档首页</span>
|
|
|
|
|
|
|
|
|
|
注意 `PrimaryColor` 和 `SecondaryColor` 类型没有在首页中列出,`mix` 函数也没有。必须点击 `kinds` 或 `utils` 才能看到他们。
|
|
|
|
|
注意 `PrimaryColor` 和 `SecondaryColor` 类型、以及 `mix` 函数都没有在首页中列出。我们必须点击 `kinds` 或 `utils` 才能看到他们。
|
|
|
|
|
|
|
|
|
|
另一个依赖这个库的 crate 需要 `use` 语句来导入 `art` 中的项,这包含指定其当前定义的模块结构。示例 14-4 展示了一个使用 `art` crate 中 `PrimaryColor` 和 `mix` 项的 crate 的例子:
|
|
|
|
|
|
|
|
|
@ -176,7 +176,7 @@ fn main() {
|
|
|
|
|
```rust,ignore
|
|
|
|
|
//! # Art
|
|
|
|
|
//!
|
|
|
|
|
//! 一个模块化的充满艺术化气息的库。
|
|
|
|
|
//! 一个描述美术信息的库。
|
|
|
|
|
|
|
|
|
|
pub use kinds::PrimaryColor;
|
|
|
|
|
pub use kinds::SecondaryColor;
|
|
|
|
@ -216,7 +216,7 @@ fn main() {
|
|
|
|
|
|
|
|
|
|
对于有很多嵌套模块的情况,使用 `pub use` 将类型重导出到顶级结构对于使用 crate 的人来说将会是大为不同的体验。
|
|
|
|
|
|
|
|
|
|
创建一个有用的公有 API 结构更像是一门艺术而非科学,你可以反复检视他们来找出最适合用户的 API。选择 `pub use` 提供了解耦组织 crate 内部结构和与终端用户体现的灵活性。观察一些你所安装的 crate 的代码来看看其内部结构是否不同于公有 API。
|
|
|
|
|
创建一个有用的公有 API 结构更像是一门艺术而非科学,你可以反复检视他们来找出最适合用户的 API。`pub use` 提供了解耦组织 crate 内部结构和与终端用户体现的灵活性。观察一些你所安装的 crate 的代码来看看其内部结构是否不同于公有 API。
|
|
|
|
|
|
|
|
|
|
### 创建 Crates.io 账号
|
|
|
|
|
|
|
|
|
@ -292,7 +292,7 @@ license = "MIT OR Apache-2.0"
|
|
|
|
|
|
|
|
|
|
现在我们创建了一个账号,保存了 API token,为 crate 选择了一个名字,并指定了所需的元数据,你已经准备好发布了!发布 crate 会上传特定版本的 crate 到 [crates.io](https://crates.io)<!-- ignore --> 以供他人使用。
|
|
|
|
|
|
|
|
|
|
发布 crate 时请多加小心,因为发布是 **永久性的**(*permanent*)。对应版本不可能被覆盖,其代码也不可能被删除。[crates.io](https://crates.io)<!-- ignore --> 的一个主要目标是作为一个代码的永久文档服务器,这样所有依赖 [crates.io](https://crates.io)<!-- ignore --> 中 crate 的项目都能一直正常工作。允许删除版本将不可能满足这个目标。然而,可以被发布的版本号却没有限制。
|
|
|
|
|
发布 crate 时请多加小心,因为发布是 **永久性的**(*permanent*)。对应版本不可能被覆盖,其代码也不可能被删除。[crates.io](https://crates.io)<!-- ignore --> 的一个主要目标是作为一个存储代码的永久文档服务器,这样所有依赖 [crates.io](https://crates.io)<!-- ignore --> 中的 crate 的项目都能一直正常工作。而允许删除版本没办法达成这个目标。然而,可以被发布的版本号却没有限制。
|
|
|
|
|
|
|
|
|
|
再次运行 `cargo publish` 命令。这次它应该会成功:
|
|
|
|
|
|
|
|
|
|