csxy_dgut202235010623
/
568tools
mirror of https://github.com/PJ-568/568tools.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'e0f5bb8287'
${ noResults }
568tools/tools/rust-course/basic/crate-module/use.html

656 lines
77 KiB
Raw Normal View History Unescape

添加 Rust 语言圣经（镜像）
2 years ago
<!DOCTYPE HTML>
<html lang="zh-CN" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>使用 use 引入模块及受限可见性 - Rust语言圣经(Rust Course)</title>
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="../../favicon.svg">
<link rel="shortcut icon" href="../../favicon.png">
<link rel="stylesheet" href="../../css/variables.css">
<link rel="stylesheet" href="../../css/general.css">
<link rel="stylesheet" href="../../css/chrome.css">
<link rel="stylesheet" href="../../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="../../highlight.css">
<link rel="stylesheet" href="../../tomorrow-night.css">
<link rel="stylesheet" href="../../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="../../theme/style.css">
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "../../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item affix "><a href="../../about-book.html">关于本书</a></li><li class="chapter-item affix "><a href="../../into-rust.html">进入 Rust 编程世界</a></li><li class="chapter-item affix "><a href="../../first-try/sth-you-should-not-do.html">避免从入门到放弃</a></li><li class="chapter-item affix "><a href="../../community.html">社区和锈书</a></li><li class="chapter-item affix "><li class="part-title">Rust 语言基础学习</li><li class="spacer"></li><li class="chapter-item "><a href="../../first-try/intro.html"><strong aria-hidden="true">1.</strong> 寻找牛刀，以便小试</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item "><a href="../../first-try/installation.html"><strong aria-hidden="true">1.1.</strong> 安装 Rust 环境</a></li><li class="chapter-item "><a href="../../first-try/editor.html"><strong aria-hidden="true">1.2.</strong> 墙推 VSCode!</a></li><li class="chapter-item "><a href="../../first-try/cargo.html"><strong aria-hidden="true">1.3.</strong> 认识 Cargo</a></li><li class="chapter-item "><a href="../../first-try/hello-world.html"><strong aria-hidden="true">1.4.</strong> 不仅仅是 Hello world</a></li><li class="chapter-item "><a href="../../first-try/slowly-downloading.html"><strong aria-hidden="true">1.5.</strong> 下载依赖太慢了？</a></li></ol></li><li class="chapter-item expanded "><a href="../../basic/intro.html"><strong aria-hidden="true">2.</strong> Rust 基础入门</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item "><a href="../../basic/variable.html"><strong aria-hidden="true">2.1.</strong> 变量绑定与解构</a></li><li class="chapter-item "><a href="../../basic/base-type/index.html"><strong aria-hidden="true">2.2.</strong> 基本类型</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item "><a href="../../basic/base-type/numbers.html"><strong aria-hidden="true">2.2.1.</strong> 数值类型</a></li><li class="chapter-item "><a href="../../basic/base-type/char-bool.html"><strong aria-hidden="true">2.2.2.</strong> 字符、布尔、单元类型</a></li><li class="chapter-item "><a href="../../basic/base-type/statement-expression.html"><strong aria-hidden="true">2.2.3.</strong> 语句与表达式</a></li><li class="chapter-item "><a href="../../basic/base-type/function.html"><strong aria-hidden="true">2.2.4.</strong> 函数</a></li></ol></li><li class="chapter-item "><a href="../../basic/ownership/index.html"><strong aria-hidden="true">2.3.</strong> 所有权和借用</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item "><a href="../../basic/ownership/ownership.html"><strong aria-hidden="true">2.3.1.</strong> 所有权</a></li><li class="chapter-item "><a href="../../basic/ownership/borrowing.html"><strong aria-hidden="true">2.3.2.</strong> 引用与借用</a></li></ol></li><li class="chapter-item "><a href="../../basic/compound-type/intro.html"><strong aria-hidden="true">2.4.</strong> 复合类型</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item "><a href="../../basic/compound-type/string-slice.html"><strong aria-hidden="true">2.4.1.</strong> 字符串与切片</a></li><li class="chapter-item "><a href="../../basic/compound-type/tuple.html"><strong aria-hidden="true">2.4.2.</strong> 元组</a></li><li class="chapter-item "><a href="../../basic/compound-type/struct.html"><strong aria-hidden="true">2.4.3.</strong> 结构体</a></li><li class="chapter-item "><a href="../../basic/compound-type/enum.html"><strong aria-hidden="true">2.4.4.</strong> 枚举</a></li><li class="chapter-item "><a href="../../basic/compound-type/array.html"><strong aria-hidden="true">2.4.5.</strong> 数组</a></li></ol></li><li class="chapter-item "><a href="../../basic/flow-control.html"><strong aria-hidden="true">2.5.</strong> 流程控制</a></li><li class="chapter-item "><a href="../../basic/match-pattern/intro.html"><strong a
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Rust语言圣经(Rust Course)</h1>
<div class="right-buttons">
<a href="../../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/sunface/rust-course" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
<a href="https://github.com/sunface/rust-course/edit/main/src/basic/crate-module/use.md" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
// Get viewed page store
var viewed_key = 'mdbook-viewed';
var viewed_map = {};
try {
var viewed_storage = localStorage.getItem(viewed_key);
if (viewed_storage) {
viewed_map = JSON.parse(viewed_storage)
}
} catch (e) { }
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
// Apply viewed style
if (viewed_map[link.pathname]) {
link.classList.add('md-viewed')
}
});
// Mark viewed after 30s
setTimeout(function() {
viewed_map[location.pathname] = 1;
localStorage.setItem(viewed_key, JSON.stringify(viewed_map));
}, 30000)
</script>
<div id="content" class="content">
<!-- Page table of contents -->
<div class="sidetoc"><nav class="pagetoc"></nav></div>
<main>
<h1 id="使用-use-及受限可见性"><a class="header" href="#使用-use-及受限可见性">使用 use 及受限可见性</a></h1>
<p>如果代码中，通篇都是 <code>crate::front_of_house::hosting::add_to_waitlist</code> 这样的函数调用形式，我不知道有谁会喜欢，也许靠代码行数赚工资的人会很喜欢，但是强迫症肯定受不了，悲伤的是程序员大多都有强迫症。。。</p>
<p>因此我们需要一个办法来简化这种使用方式，在 Rust 中，可以使用 <code>use</code> 关键字把路径提前引入到当前作用域中，随后的调用就可以省略该路径，极大地简化了代码。</p>
<h2 id="基本引入方式"><a class="header" href="#基本引入方式">基本引入方式</a></h2>
<p>在 Rust 中，引入模块中的项有两种方式：<a href="https://course.rs/basic/crate-module/module.html#%E7%94%A8%E8%B7%AF%E5%BE%84%E5%BC%95%E7%94%A8%E6%A8%A1%E5%9D%97">绝对路径和相对路径</a>，这两者在前面章节都有讲过，就不再赘述，先来看看使用绝对路径的引入方式。</p>
<h4 id="绝对路径引入模块"><a class="header" href="#绝对路径引入模块">绝对路径引入模块</a></h4>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>mod front_of_house {
pub mod hosting {
pub fn add_to_waitlist() {}
}
}
use crate::front_of_house::hosting;
pub fn eat_at_restaurant() {
hosting::add_to_waitlist();
hosting::add_to_waitlist();
hosting::add_to_waitlist();
}
<span class="boring">}
</span></code></pre></pre>
<p>这里，我们使用 <code>use</code> 和绝对路径的方式，将 <code>hosting</code> 模块引入到当前作用域中，然后只需通过 <code>hosting::add_to_waitlist</code> 的方式，即可调用目标模块中的函数，相比 <code>crate::front_of_house::hosting::add_to_waitlist()</code> 的方式要简单的多，那么还能更简单吗？</p>
<h4 id="相对路径引入模块中的函数"><a class="header" href="#相对路径引入模块中的函数">相对路径引入模块中的函数</a></h4>
<p>在下面代码中，我们不仅要使用相对路径进行引入，而且与上面引入 <code>hosting</code> 模块不同，直接引入该模块中的 <code>add_to_waitlist</code> 函数：</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>mod front_of_house {
pub mod hosting {
pub fn add_to_waitlist() {}
}
}
use front_of_house::hosting::add_to_waitlist;
pub fn eat_at_restaurant() {
add_to_waitlist();
add_to_waitlist();
add_to_waitlist();
}
<span class="boring">}
</span></code></pre></pre>
<p>很明显，三兄弟又变得更短了，不过，怎么觉得这句话怪怪的。。</p>
<h4 id="引入模块还是函数"><a class="header" href="#引入模块还是函数">引入模块还是函数</a></h4>
<p>从使用简洁性来说，引入函数自然是更甚一筹，但是在某些时候，引入模块会更好：</p>
<ul>
<li>需要引入同一个模块的多个函数</li>
<li>作用域中存在同名函数</li>
</ul>
<p>在以上两种情况中，使用 <code>use front_of_house::hosting;</code> 引入模块要比 <code>use front_of_house::hosting::add_to_waitlist;</code> 引入函数更好。</p>
<p>例如，如果想使用 <code>HashMap</code>，那么直接引入该结构体是比引入模块更好的选择，因为在 <code>collections</code> 模块中，我们只需要使用一个 <code>HashMap</code> 结构体：</p>
<pre><pre class="playground"><code class="language-rust edition2021">use std::collections::HashMap;
fn main() {
let mut map = HashMap::new();
map.insert(1, 2);
}
</code></pre></pre>
<p>其实严格来说，对于引用方式并没有需要遵守的惯例，主要还是取决于你的喜好，不过我们建议：<strong>优先使用最细粒度(引入函数、结构体等)的引用方式，如果引起了某种麻烦(例如前面两种情况)，再使用引入模块的方式</strong>。</p>
<h2 id="避免同名引用"><a class="header" href="#避免同名引用">避免同名引用</a></h2>
<p>根据上一章节的内容，我们只要保证同一个模块中不存在同名项就行，模块之间、包之间的同名，谁管得着谁啊，话虽如此，一起看看，如果遇到同名的情况该如何处理。</p>
<h4 id="模块函数"><a class="header" href="#模块函数">模块::函数</a></h4>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>use std::fmt;
use std::io;
fn function1() -&gt; fmt::Result {
// --snip--
}
fn function2() -&gt; io::Result&lt;()&gt; {
// --snip--
}
<span class="boring">}
</span></code></pre></pre>
<p>上面的例子给出了很好的解决方案，使用模块引入的方式，具体的 <code>Result</code> 通过 <code>模块::Result</code> 的方式进行调用。</p>
<p>可以看出，避免同名冲突的关键，就是使用<strong>父模块的方式来调用</strong>，除此之外，还可以给予引入的项起一个别名。</p>
<h4 id="as-别名引用"><a class="header" href="#as-别名引用"><code>as</code> 别名引用</a></h4>
<p>对于同名冲突问题，还可以使用 <code>as</code> 关键字来解决，它可以赋予引入项一个全新的名称：</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>use std::fmt::Result;
use std::io::Result as IoResult;
fn function1() -&gt; Result {
// --snip--
}
fn function2() -&gt; IoResult&lt;()&gt; {
// --snip--
}
<span class="boring">}
</span></code></pre></pre>
<p>如上所示，首先通过 <code>use std::io::Result</code> 将 <code>Result</code> 引入到作用域，然后使用 <code>as</code> 给予它一个全新的名称 <code>IoResult</code>，这样就不会再产生冲突：</p>
<ul>
<li><code>Result</code> 代表 <code>std::fmt::Result</code></li>
<li><code>IoResult</code> 代表 <code>std:io::Result</code></li>
</ul>
<h2 id="引入项再导出"><a class="header" href="#引入项再导出">引入项再导出</a></h2>
<p>当外部的模块项 <code>A</code> 被引入到当前模块中时，它的可见性自动被设置为私有的，如果你希望允许其它外部代码引用我们的模块项 <code>A</code>，那么可以对它进行再导出：</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>mod front_of_house {
pub mod hosting {
pub fn add_to_waitlist() {}
}
}
pub use crate::front_of_house::hosting;
pub fn eat_at_restaurant() {
hosting::add_to_waitlist();
hosting::add_to_waitlist();
hosting::add_to_waitlist();
}
<span class="boring">}
</span></code></pre></pre>
<p>如上，使用 <code>pub use</code> 即可实现。这里 <code>use</code> 代表引入 <code>hosting</code> 模块到当前作用域，<code>pub</code> 表示将该引入的内容再度设置为可见。</p>
<p>当你希望将内部的实现细节隐藏起来或者按照某个目的组织代码时，可以使用 <code>pub use</code> 再导出，例如统一使用一个模块来提供对外的 API，那该模块就可以引入其它模块中的 API，然后进行再导出，最终对于用户来说，所有的 API 都是由一个模块统一提供的。</p>
<h2 id="使用第三方包"><a class="header" href="#使用第三方包">使用第三方包</a></h2>
<p>之前我们一直在引入标准库模块或者自定义模块，现在来引入下第三方包中的模块，关于如何引入外部依赖，我们在 <a href="https://course.rs/first-try/cargo.html#package-%E9%85%8D%E7%BD%AE%E6%AE%B5%E8%90%BD">Cargo 入门</a>中就有讲，这里直接给出操作步骤：</p>
<ol>
<li>修改 <code>Cargo.toml</code> 文件，在 <code>[dependencies]</code> 区域添加一行：<code>rand = &quot;0.8.3&quot;</code></li>
<li>此时，如果你用的是 <code>VSCode</code> 和 <code>rust-analyzer</code> 插件，该插件会自动拉取该库，你可能需要等它完成后，再进行下一步（VSCode 左下角有提示）</li>
</ol>
<p>好了，此时，<code>rand</code> 包已经被我们添加到依赖中，下一步就是在代码中使用：</p>
<pre><pre class="playground"><code class="language-rust edition2021">use rand::Rng;
fn main() {
let secret_number = rand::thread_rng().gen_range(1..101);
}
</code></pre></pre>
<p>这里使用 <code>use</code> 引入了第三方包 <code>rand</code> 中的 <code>Rng</code> 特征，因为我们需要调用的 <code>gen_range</code> 方法定义在该特征中。</p>
<h4 id="cratesiolibrs"><a class="header" href="#cratesiolibrs">crates.io，lib.rs</a></h4>
<p>Rust 社区已经为我们贡献了大量高质量的第三方包，你可以在 <code>crates.io</code> 或者 <code>lib.rs</code> 中检索和使用，从目前来说查找包更推荐 <code>lib.rs</code>，搜索功能更强大，内容展示也更加合理，但是下载依赖包还是得用<code>crates.io</code>。</p>
<p>你可以在网站上搜索 <code>rand</code> 包，看看它的文档使用方式是否和我们之前引入方式相一致：在网上找到想要的包，然后将你想要的包和版本信息写入到 <code>Cargo.toml</code> 中。</p>
<h2 id="使用--简化引入方式"><a class="header" href="#使用--简化引入方式">使用 <code>{}</code> 简化引入方式</a></h2>
<p>对于以下一行一行的引入方式：</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>use std::collections::HashMap;
use std::collections::BTreeMap;
use std::collections::HashSet;
use std::cmp::Ordering;
use std::io;
<span class="boring">}
</span></code></pre></pre>
<p>可以使用 <code>{}</code> 来一起引入进来，在大型项目中，使用这种方式来引入，可以减少大量 <code>use</code> 的使用：</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>use std::collections::{HashMap,BTreeMap,HashSet};
use std::{cmp::Ordering, io};
<span class="boring">}
</span></code></pre></pre>
<p>对于下面的同时引入模块和模块中的项：</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>use std::io;
use std::io::Write;
<span class="boring">}
</span></code></pre></pre>
<p>可以使用 <code>{}</code> 的方式进行简化:</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>use std::io::{self, Write};
<span class="boring">}
</span></code></pre></pre>
<h4 id="self"><a class="header" href="#self">self</a></h4>
<p>上面使用到了模块章节提到的 <code>self</code> 关键字，用来替代模块自身，结合上一节中的 <code>self</code>，可以得出它在模块中的两个用途：</p>
<ul>
<li><code>use self::xxx</code>，表示加载当前模块中的 <code>xxx</code>。此时 <code>self</code> 可省略</li>
<li><code>use xxx::{self, yyy}</code>，表示，加载当前路径下模块 <code>xxx</code> 本身，以及模块 <code>xxx</code> 下的 <code>yyy</code></li>
</ul>
<h2 id="使用--引入模块下的所有项"><a class="header" href="#使用--引入模块下的所有项">使用 <code>*</code> 引入模块下的所有项</a></h2>
<p>对于之前一行一行引入 <code>std::collections</code> 的方式，我们还可以使用</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>use std::collections::*;
<span class="boring">}
</span></code></pre></pre>
<p>以上这种方式来引入 <code>std::collections</code> 模块下的所有公共项，这些公共项自然包含了 <code>HashMap</code>，<code>HashSet</code> 等想手动引入的集合类型。</p>
<p>当使用 <code>*</code> 来引入的时候要格外小心，因为你很难知道到底哪些被引入到了当前作用域中，有哪些会和你自己程序中的名称相冲突：</p>
<pre><pre class="playground"><code class="language-rust edition2021">use std::collections::*;
struct HashMap;
fn main() {
let mut v = HashMap::new();
v.insert(&quot;a&quot;, 1);
}
</code></pre></pre>
<p>以上代码中，<code>std::collection::HashMap</code> 被 <code>*</code> 引入到当前作用域，但是由于存在另一个同名的结构体，因此 <code>HashMap::new</code> 根本不存在，因为对于编译器来说，本地同名类型的优先级更高。</p>
<p>在实际项目中，这种引用方式往往用于快速写测试代码，它可以把所有东西一次性引入到 <code>tests</code> 模块中。</p>
<h2 id="受限的可见性"><a class="header" href="#受限的可见性">受限的可见性</a></h2>
<p>在上一节中，我们学习了<a href="https://course.rs/basic/crate-module/module.html#%E4%BB%A3%E7%A0%81%E5%8F%AF%E8%A7%81%E6%80%A7">可见性</a>这个概念，这也是模块体系中最为核心的概念，控制了模块中哪些内容可以被外部看见，但是在实际使用时，光被外面看到还不行，我们还想控制哪些人能看，这就是 Rust 提供的受限可见性。</p>
<p>例如，在 Rust 中，包是一个模块树，我们可以通过 <code>pub(crate) item;</code> 这种方式来实现：<code>item</code> 虽然是对外可见的，但是只在当前包内可见，外部包无法引用到该 <code>item</code>。</p>
<p>所以，如果我们想要让某一项可以在整个包中都可以被使用，那么有两种办法：</p>
<ul>
<li>在包根中定义一个非 <code>pub</code> 类型的 <code>X</code>(父模块的项对子模块都是可见的，因此包根中的项对模块树上的所有模块都可见)</li>
<li>在子模块中定义一个 <code>pub</code> 类型的 <code>Y</code>，同时通过 <code>use</code> 将其引入到包根</li>
</ul>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>mod a {
pub mod b {
pub fn c() {
println!(&quot;{:?}&quot;,crate::X);
}
#[derive(Debug)]
pub struct Y;
}
}
#[derive(Debug)]
struct X;
use a::b::Y;
fn d() {
println!(&quot;{:?}&quot;,Y);
}
<span class="boring">}
</span></code></pre></pre>
<p>以上代码充分说明了之前两种办法的使用方式，但是有时我们会遇到这两种方法都不太好用的时候。例如希望对于某些特定的模块可见，但是对于其他模块又不可见：</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>// 目标：`a` 导出 `I`、`bar` and `foo`，其他的不导出
pub mod a {
pub const I: i32 = 3;
fn semisecret(x: i32) -&gt; i32 {
use self::b::c::J;
x + J
}
pub fn bar(z: i32) -&gt; i32 {
semisecret(I) * z
}
pub fn foo(y: i32) -&gt; i32 {
semisecret(I) + y
}
mod b {
mod c {
const J: i32 = 4;
}
}
}
<span class="boring">}
</span></code></pre></pre>
<p>这段代码会报错，因为与父模块中的项对子模块可见相反，子模块中的项对父模块是不可见的。这里 <code>semisecret</code> 方法中，<code>a</code> -&gt; <code>b</code> -&gt; <code>c</code> 形成了父子模块链，那 <code>c</code> 中的 <code>J</code> 自然对 <code>a</code> 模块不可见。</p>
<p>如果使用之前的可见性方式，那么想保持 <code>J</code> 私有，同时让 <code>a</code> 继续使用 <code>semisecret</code> 函数的办法是将该函数移动到 <code>c</code> 模块中，然后用 <code>pub use</code> 将 <code>semisecret</code> 函数进行再导出：</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>pub mod a {
pub const I: i32 = 3;
use self::b::semisecret;
pub fn bar(z: i32) -&gt; i32 {
semisecret(I) * z
}
pub fn foo(y: i32) -&gt; i32 {
semisecret(I) + y
}
mod b {
pub use self::c::semisecret;
mod c {
const J: i32 = 4;
pub fn semisecret(x: i32) -&gt; i32 {
x + J
}
}
}
}
<span class="boring">}
</span></code></pre></pre>
<p>这段代码说实话问题不大，但是有些破坏了我们之前的逻辑，如果想保持代码逻辑，同时又只让 <code>J</code> 在 <code>a</code> 内可见该怎么办？</p>
<pre><pre class="playground"><code class="language-rust edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>pub mod a {
pub const I: i32 = 3;
fn semisecret(x: i32) -&gt; i32 {
use self::b::c::J;
x + J
}
pub fn bar(z: i32) -&gt; i32 {
semisecret(I) * z
}
pub fn foo(y: i32) -&gt; i32 {
semisecret(I) + y
}
mod b {
pub(in crate::a) mod c {
pub(in crate::a) const J: i32 = 4;
}
}
}
<span class="boring">}
</span></code></pre></pre>
<p>通过 <code>pub(in crate::a)</code> 的方式，我们指定了模块 <code>c</code> 和常量 <code>J</code> 的可见范围都只是 <code>a</code> 模块中，<code>a</code> 之外的模块是完全访问不到它们的。</p>
<h4 id="限制可见性语法"><a class="header" href="#限制可见性语法">限制可见性语法</a></h4>
<p><code>pub(crate)</code> 或 <code>pub(in crate::a)</code> 就是限制可见性语法，前者是限制在整个包内可见，后者是通过绝对路径，限制在包内的某个模块内可见，总结一下：</p>
<ul>
<li><code>pub</code> 意味着可见性无任何限制</li>
<li><code>pub(crate)</code> 表示在当前包可见</li>
<li><code>pub(self)</code> 在当前模块可见</li>
<li><code>pub(super)</code> 在父模块可见</li>
<li><code>pub(in &lt;path&gt;)</code> 表示在某个路径代表的模块中可见，其中 <code>path</code> 必须是父模块或者祖先模块</li>
</ul>
<h4 id="一个综合例子"><a class="header" href="#一个综合例子">一个综合例子</a></h4>
<pre><pre class="playground"><code class="language-rust edition2021">// 一个名为 `my_mod` 的模块
mod my_mod {
// 模块中的项默认具有私有的可见性
fn private_function() {
println!(&quot;called `my_mod::private_function()`&quot;);
}
// 使用 `pub` 修饰语来改变默认可见性。
pub fn function() {
println!(&quot;called `my_mod::function()`&quot;);
}
// 在同一模块中，项可以访问其它项，即使它是私有的。
pub fn indirect_access() {
print!(&quot;called `my_mod::indirect_access()`, that\n&gt; &quot;);
private_function();
}
// 模块也可以嵌套
pub mod nested {
pub fn function() {
println!(&quot;called `my_mod::nested::function()`&quot;);
}
#[allow(dead_code)]
fn private_function() {
println!(&quot;called `my_mod::nested::private_function()`&quot;);
}
// 使用 `pub(in path)` 语法定义的函数只在给定的路径中可见。
// `path` 必须是父模块（parent module）或祖先模块（ancestor module）
pub(in crate::my_mod) fn public_function_in_my_mod() {
print!(&quot;called `my_mod::nested::public_function_in_my_mod()`, that\n &gt; &quot;);
public_function_in_nested()
}
// 使用 `pub(self)` 语法定义的函数则只在当前模块中可见。
pub(self) fn public_function_in_nested() {
println!(&quot;called `my_mod::nested::public_function_in_nested&quot;);
}
// 使用 `pub(super)` 语法定义的函数只在父模块中可见。
pub(super) fn public_function_in_super_mod() {
println!(&quot;called my_mod::nested::public_function_in_super_mod&quot;);
}
}
pub fn call_public_function_in_my_mod() {
print!(&quot;called `my_mod::call_public_funcion_in_my_mod()`, that\n&gt; &quot;);
nested::public_function_in_my_mod();
print!(&quot;&gt; &quot;);
nested::public_function_in_super_mod();
}
// `pub(crate)` 使得函数只在当前包中可见
pub(crate) fn public_function_in_crate() {
println!(&quot;called `my_mod::public_function_in_crate()&quot;);
}
// 嵌套模块的可见性遵循相同的规则
mod private_nested {
#[allow(dead_code)]
pub fn function() {
println!(&quot;called `my_mod::private_nested::function()`&quot;);
}
}
}
fn function() {
println!(&quot;called `function()`&quot;);
}
fn main() {
// 模块机制消除了相同名字的项之间的歧义。
function();
my_mod::function();
// 公有项，包括嵌套模块内的，都可以在父模块外部访问。
my_mod::indirect_access();
my_mod::nested::function();
my_mod::call_public_function_in_my_mod();
// pub(crate) 项可以在同一个 crate 中的任何地方访问
my_mod::public_function_in_crate();
// pub(in path) 项只能在指定的模块中访问
// 报错！函数 `public_function_in_my_mod` 是私有的
//my_mod::nested::public_function_in_my_mod();
// 试一试 ^ 取消该行的注释
// 模块的私有项不能直接访问，即便它是嵌套在公有模块内部的
// 报错！`private_function` 是私有的
//my_mod::private_function();
// 试一试 ^ 取消此行注释
// 报错！`private_function` 是私有的
//my_mod::nested::private_function();
// 试一试 ^ 取消此行的注释
// 报错！ `private_nested` 是私有的
//my_mod::private_nested::function();
// 试一试 ^ 取消此行的注释
}
</code></pre></pre>
<h2 id="课后练习"><a class="header" href="#课后练习">课后练习</a></h2>
<blockquote>
<p><a href="https://zh.practice.rs/crate-module/use-pub.html">Rust By Practice</a>，支持代码在线编辑和运行，并提供详细的<a href="https://github.com/sunface/rust-by-practice/blob/master/solutions/crate-module/use-pub.md">习题解答</a>。</p>
</blockquote>
<div id="giscus-container"></div>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../../basic/crate-module/module.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="../../basic/comment.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../../basic/crate-module/module.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="../../basic/comment.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script type="text/javascript">
window.playground_copyable = true;
</script>
<script src="../../ace.js" type="text/javascript" charset="utf-8"></script>
<script src="../../editor.js" type="text/javascript" charset="utf-8"></script>
<script src="../../mode-rust.js" type="text/javascript" charset="utf-8"></script>
<script src="../../theme-dawn.js" type="text/javascript" charset="utf-8"></script>
<script src="../../theme-tomorrow_night.js" type="text/javascript" charset="utf-8"></script>
<script src="../../elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="../../clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="../../book.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">
var pagePath = "basic/crate-module/use.md"
</script>
<!-- Custom JS scripts -->
<script type="text/javascript" src="../../assets/custom.js"></script>
<script type="text/javascript" src="../../assets/bigPicture.js"></script>
</body>
</html>