Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Пути для ссылки на элемент в дереве модулей

Чтобы показать Rust, где найти элемент в дереве модулей, мы используем путь так же, как мы используем путь при навигации по файловой системе. Чтобы вызвать функцию, нам нужно знать её путь.

Путь может принимать две формы:

  • Абсолютный путь — это полный путь, начинающийся с корня крейта; для кода из внешнего крейта абсолютный путь начинается с имени крейта, а для кода из текущего крейта он начинается с литерала crate.
  • Относительный путь начинается с текущего модуля и использует self, super или идентификатор в текущем модуле.

За как абсолютными, так и относительными путями следуют один или несколько идентификаторов, разделённых двойными двоеточиями (::).

Возвращаясь к листингу 7-1, предположим, что мы хотим вызвать функцию add_to_waitlist. Это то же самое, что спросить: каков путь функции add_to_waitlist? Листинг 7-3 содержит листинг 7-1 с удалёнными некоторыми модулями и функциями.

Мы покажем два способа вызвать функцию add_to_waitlist из новой функции eat_at_restaurant, определённой в корне крейта. Эти пути корректны, но остаётся ещё одна проблема, которая не даст этому примеру скомпилироваться как есть. Мы объясним почему чуть позже.

Функция eat_at_restaurant является частью публичного API нашего библиотечного крейта, поэтому мы помечаем её ключевым словом pub. В разделе «Раскрытие путей с помощью ключевого слова pub» мы рассмотрим pub более подробно.

Имя файла: src/lib.rs
mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Абсолютный путь
    crate::front_of_house::hosting::add_to_waitlist();

    // Относительный путь
    front_of_house::hosting::add_to_waitlist();
}
Листинг 7-3: Вызов функции add_to_waitlist с использованием абсолютного и относительного путей

В первый раз, когда мы вызываем функцию add_to_waitlist в eat_at_restaurant, мы используем абсолютный путь. Функция add_to_waitlist определена в том же крейте, что и eat_at_restaurant, что означает, что мы можем использовать ключевое слово crate для начала абсолютного пути. Затем мы включаем каждый из последовательных модулей, пока не доберёмся до add_to_waitlist. Вы можете представить файловую систему с той же структурой: мы бы указали путь /front_of_house/hosting/add_to_waitlist, чтобы запустить программу add_to_waitlist; использование имени crate для начала от корня крейта похоже на использование / для начала от корня файловой системы в вашей оболочке.

Во второй раз, когда мы вызываем add_to_waitlist в eat_at_restaurant, мы используем относительный путь. Путь начинается с front_of_house, имени модуля, определённого на том же уровне дерева модулей, что и eat_at_restaurant. Здесь эквивалент файловой системы — это использование пути front_of_house/hosting/add_to_waitlist. Начало с имени модуля означает, что путь относительный.

Выбор между относительным и абсолютным путём — это решение, которое вы принимаете в зависимости от вашего проекта, и оно зависит от того, более ли вероятно, что вы будете перемещать код определения элемента отдельно от кода, использующего элемент, или вместе с ним. Например, если бы мы переместили модуль front_of_house и функцию eat_at_restaurant в модуль с именем customer_experience, нам нужно было бы обновить абсолютный путь к add_to_waitlist, но относительный путь остался бы действительным. Однако, если бы мы переместили функцию eat_at_restaurant отдельно в модуль с именем dining, абсолютный путь к вызову add_to_waitlist остался бы прежним, а относительный путь нужно было бы обновить. В целом мы предпочитаем указывать абсолютные пути, потому что более вероятно, что мы захотим перемещать определения кода и вызовы элементов независимо друг от друга.

Давайте попробуем скомпилировать листинг 7-3 и выяснить, почему он ещё не компилируется! Полученные ошибки показаны в листинге 7-4.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: module `hosting` is private
 --> src/lib.rs:9:28
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                            ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
  |                            |
  |                            private module
  |
note: the module `hosting` is defined here
 --> src/lib.rs:2:5
  |
2 |     mod hosting {
  |     ^^^^^^^^^^^

error[E0603]: module `hosting` is private
  --> src/lib.rs:12:21
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                     ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
   |                     |
   |                     private module
   |
note: the module `hosting` is defined here
  --> src/lib.rs:2:5
   |
 2 |     mod hosting {
   |     ^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors
Листинг 7-4: Ошибки компилятора при сборке кода из листинга 7-3

Сообщения об ошибках говорят, что модуль hosting является приватным. Другими словами, у нас есть правильные пути к модулю hosting и функции add_to_waitlist, но Rust не позволяет нам их использовать, потому что у него нет доступа к приватным разделам. В Rust все элементы (функции, методы, структуры, перечисления, модули и константы) по умолчанию приватны для родительских модулей. Если вы хотите сделать элемент, такой как функция или структура, приватным, вы помещаете его в модуль.

Элементы в родительском модуле не могут использовать приватные элементы внутри дочерних модулей, но элементы в дочерних модулях могут использовать элементы в своих родительских модулях. Это потому, что дочерние модули оборачивают и скрывают детали своей реализации, но дочерние модули могут видеть контекст, в котором они определены. Продолжая нашу метафору, подумайте о правилах приватности как о служебных помещениях ресторана: то, что там происходит, приватно для клиентов ресторана, но менеджеры офиса могут видеть и делать всё в ресторане, которым они управляют.

Rust выбрал такую работу системы модулей, чтобы сокрытие внутренних деталей реализации было поведением по умолчанию. Таким образом, вы знаете, какие части внутреннего кода вы можете изменить, не ломая внешний код. Однако Rust даёт вам возможность раскрыть внутренние части кода дочерних модулей внешним родительским модулям, используя ключевое слово pub, чтобы сделать элемент публичным.

Раскрытие путей с помощью ключевого слова pub

Вернёмся к ошибке в листинге 7-4, которая сообщила нам, что модуль hosting является приватным. Мы хотим, чтобы функция eat_at_restaurant в родительском модуле имела доступ к функции add_to_waitlist в дочернем модуле, поэтому мы помечаем модуль hosting ключевым словом pub, как показано в листинге 7-5.

Имя файла: src/lib.rs
mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Абсолютный путь
    crate::front_of_house::hosting::add_to_waitlist();

    // Относительный путь
    front_of_house::hosting::add_to_waitlist();
}
Листинг 7-5: Объявление модуля hosting как pub, чтобы использовать его из eat_at_restaurant

К сожалению, код в листинге 7-5 всё ещё приводит к ошибкам компилятора, как показано в листинге 7-6.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:10:37
   |
10 |     crate::front_of_house::hosting::add_to_waitlist();
   |                                     ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
 3 |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:13:30
   |
13 |     front_of_house::hosting::add_to_waitlist();
   |                              ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
 3 |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors
Листинг 7-6: Ошибки компилятора при сборке кода из листинга 7-5

Что произошло? Добавление ключевого слова pub перед mod hosting делает модуль публичным. С этим изменением, если мы можем получить доступ к front_of_house, мы можем получить доступ к hosting. Но содержимое hosting всё ещё приватно; сделать модуль публичным не значит сделать его содержимое публичным. Ключевое слово pub у модуля позволяет только коду в его родительских модулях ссылаться на него, но не получать доступ к его внутреннему коду. Поскольку модули — это контейнеры, мы не можем многого добиться, сделав публичным только модуль; нам нужно пойти дальше и сделать публичным один или несколько элементов внутри модуля.

Ошибки в листинге 7-6 говорят, что функция add_to_waitlist является приватной. Правила приватности применяются к структурам, перечислениям, функциям и методам так же, как и к модулям.

Давайте также сделаем функцию add_to_waitlist публичной, добавив ключевое слово pub перед её определением, как в листинге 7-7.

Имя файла: src/lib.rs
mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Абсолютный путь
    crate::front_of_house::hosting::add_to_waitlist();

    // Относительный путь
    front_of_house::hosting::add_to_waitlist();
}
Листинг 7-7: Добавление ключевого слова pub к mod hosting и fn add_to_waitlist позволяет нам вызвать функцию из eat_at_restaurant.

Теперь код скомпилируется! Чтобы понять, почему добавление ключевого слова pub позволяет нам использовать эти пути в eat_at_restaurant в соответствии с правилами приватности, давайте посмотрим на абсолютный и относительный пути.

В абсолютном пути мы начинаем с crate, корня дерева модулей нашего крейта. Модуль front_of_house определён в корне крейта. Хотя front_of_house не является публичным, потому что функция eat_at_restaurant определена в том же модуле, что и front_of_house (то есть eat_at_restaurant и front_of_house — соседи), мы можем ссылаться на front_of_house из eat_at_restaurant. Далее идёт модуль hosting, помеченный pub. Мы можем получить доступ к родительскому модулю hosting, поэтому мы можем получить доступ к hosting. Наконец, функция add_to_waitlist помечена pub, и мы можем получить доступ к её родительскому модулю, поэтому этот вызов функции работает!

В относительном пути логика та же, что и в абсолютном, за исключением первого шага: вместо того чтобы начинать от корня крейта, путь начинается от front_of_house. Модуль front_of_house определён в том же модуле, что и eat_at_restaurant, поэтому относительный путь, начинающийся от модуля, в котором определён eat_at_restaurant, работает. Затем, поскольку hosting и add_to_waitlist помечены pub, остальная часть пути работает, и этот вызов функции допустим!

Если вы планируете распространять ваш библиотечный крейт, чтобы другие проекты могли использовать ваш код, ваш публичный API — это ваш контракт с пользователями вашего крейта, который определяет, как они могут взаимодействовать с вашим кодом. Есть много соображений по управлению изменениями в вашем публичном API, чтобы людям было проще зависеть от вашего крейта. Эти соображения выходят за рамки этой книги; если вам интересна эта тема, см. Rust API Guidelines.

Лучшие практики для пакетов с бинарным крейтом и библиотекой

Мы упоминали, что пакет может содержать как корень бинарного крейта src/main.rs, так и корень библиотечного крейта src/lib.rs, и оба крейта по умолчанию будут иметь имя пакета. Как правило, пакеты с таким шаблоном, содержащие и библиотеку, и бинарный крейт, будут иметь ровно столько кода в бинарном крейте, сколько нужно для запуска исполняемого файла, который вызывает код, определённый в библиотечном крейте. Это позволяет другим проектам извлекать выгоду из большей части функциональности, которую предоставляет пакет, потому что код библиотечного крейта можно разделять.

Дерево модулей должно быть определено в src/lib.rs. Затем любые публичные элементы могут использоваться в бинарном крейте путём начала путей с имени пакета. Бинарный крейт становится пользователем библиотечного крейта так же, как совершенно внешний крейт использовал бы библиотечный крейт: он может использовать только публичный API. Это помогает вам разрабатывать хороший API; вы не только автор, но и клиент!

В главе 12 мы продемонстрируем эту организационную практику с программой командной строки, которая будет содержать как бинарный, так и библиотечный крейт.

Начало относительных путей с super

Мы можем строить относительные пути, которые начинаются в родительском модуле, а не в текущем модуле или корне крейта, используя super в начале пути. Это похоже на начало пути файловой системы с синтаксиса .., который означает переход в родительский каталог. Использование super позволяет нам ссылаться на элемент, который, как мы знаем, находится в родительском модуле, что может облегчить перестройку дерева модулей, когда модуль тесно связан с родителем, но родитель может когда-нибудь быть перемещён в другое место дерева модулей.

Рассмотрим код в листинге 7-8, который моделирует ситуацию, когда шеф-повар исправляет неправильный заказ и лично приносит его клиенту. Функция fix_incorrect_order, определённая в модуле back_of_house, вызывает функцию deliver_order, определённую в родительском модуле, указывая путь к deliver_order, начиная с super.

Имя файла: src/lib.rs
fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}
Листинг 7-8: Вызов функции с использованием относительного пути, начинающегося с super

Функция fix_incorrect_order находится в модуле back_of_house, поэтому мы можем использовать super, чтобы перейти к родительскому модулю back_of_house, который в данном случае — crate, корень. Оттуда мы ищем deliver_order и находим его. Успех! Мы думаем, что модуль back_of_house и функция deliver_order, вероятно, останутся в том же отношении друг к другу и будут перемещаться вместе, если мы решим реорганизовать дерево модулей крейта. Поэтому мы использовали super, чтобы у нас было меньше мест для обновления кода в будущем, если этот код будет перемещён в другой модуль.

Делаем структуры и перечисления публичными

Мы также можем использовать pub, чтобы обозначить структуры и перечисления как публичные, но есть несколько дополнительных деталей в использовании pub со структурами и перечислениями. Если мы используем pub перед определением структуры, мы делаем структуру публичной, но поля структуры всё ещё будут приватными. Мы можем сделать каждое поле публичным или нет на индивидуальной основе. В листинге 7-9 мы определили публичную структуру back_of_house::Breakfast с публичным полем toast, но приватным полем seasonal_fruit. Это моделирует случай в ресторане, когда клиент может выбрать тип хлеба, который идёт с блюдом, но шеф-повар решает, какой фрукт сопровождает блюдо, основываясь на том, что в сезоне и в наличии. Доступные фрукты быстро меняются, поэтому клиенты не могут выбрать фрукт или даже увидеть, какой фрукт они получат.

Имя файла: src/lib.rs
mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Заказываем завтрак летом с ржаным тостом.
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Передумали насчёт того, какой хлеб хотим.
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // Следующая строка не скомпилируется, если её раскомментировать; нам не разрешено
    // видеть или изменять сезонные фрукты, которые идут вместе с блюдом.
    // meal.seasonal_fruit = String::from("blueberries");
}
Листинг 7-9: Структура с некоторыми публичными полями и некоторыми приватными полями

Поскольку поле toast в структуре back_of_house::Breakfast является публичным, в eat_at_restaurant мы можем писать и читать поле toast, используя точечную нотацию. Обратите внимание, что мы не можем использовать поле seasonal_fruit в eat_at_restaurant, потому что seasonal_fruit является приватным. Попробуйте раскомментировать строку, изменяющую значение поля seasonal_fruit, чтобы увидеть, какую ошибку вы получите!

Также обратите внимание, что поскольку back_of_house::Breakfast имеет приватное поле, структуре нужно предоставить публичную ассоциированную функцию, которая создаёт экземпляр Breakfast (мы назвали её summer здесь). Если бы у Breakfast не было такой функции, мы не могли бы создать экземпляр Breakfast в eat_at_restaurant, потому что мы не могли бы установить значение приватного поля seasonal_fruit в eat_at_restaurant.

В отличие от структур, если мы делаем перечисление публичным, все его варианты тогда становятся публичными. Нам нужно только pub перед ключевым словом enum, как показано в листинге 7-10.

Имя файла: src/lib.rs
mod back_of_house {
    pub enum Appetizer {
        Soup,
        Salad,
    }
}

pub fn eat_at_restaurant() {
    let order1 = back_of_house::Appetizer::Soup;
    let order2 = back_of_house::Appetizer::Salad;
}
Листинг 7-10: Обозначение перечисления как публичного делает все его варианты публичными.

Поскольку мы сделали перечисление Appetizer публичным, мы можем использовать варианты Soup и Salad в eat_at_restaurant.

Перечисления не очень полезны, если их варианты не публичны; было бы утомительно аннотировать все варианты перечисления с pub в каждом случае, поэтому по умолчанию варианты перечисления являются публичными. Структуры часто полезны и без того, чтобы их поля были публичными, поэтому поля структур следуют общему правилу: всё приватно по умолчанию, если не аннотировано pub.

Есть ещё одна ситуация, связанная с pub, которую мы не рассмотрели, и это наша последняя возможность системы модулей: ключевое слово use. Мы сначала рассмотрим use само по себе, а затем покажем, как объединить pub и use.