Модули, Cargo и проект: счётчик слов

Раздели код на модули и крейты, подключай зависимости с crates.io, пиши тесты с `cargo test` и собери из всего изученного утилиту командной строки, которая считает слова в текстовом файле.

  • Продвинутый
  • 22 мин
  • 10 вопросов
  • Урок 10 из 10

В этом уроке ты узнаешь

  • Различать пакеты, крейты и модули и работать с pub и use
  • Подключать зависимость с crates.io и читать Cargo.toml
  • Писать функции #[test] и запускать их через cargo test
  • Собрать полноценную CLI-программу из библиотечной и исполняемой частей

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

Пакеты, крейты и модули

  • Пакет — проект Cargo с файлом Cargo.toml. Именно его создаёт cargo new.
  • Крейт (crate) — единица компиляции. src/main.rs даёт исполняемый (binary) крейт, а src/lib.rs — библиотечный. В одном пакете могут быть оба.
  • Модуль — пространство имён внутри крейта, создаётся через mod. Элементы модуля по умолчанию закрыты; чтобы они были видны снаружи, пишут pub.
  • Путь — имя, записанное через ::, например geometry::square_area; use делает длинный путь доступным по короткому имени.
Rust
mod geometry {
    pub fn square_area(side: f64) -> f64 {
        side * side
    }

    pub fn circle_area(r: f64) -> f64 {
        round2(std::f64::consts::PI * r * r)
    }

    fn round2(x: f64) -> f64 {
        (x * 100.0).round() / 100.0
    }
}

use geometry::circle_area;

fn main() {
    println!("{}", geometry::square_area(1.5));
    println!("{}", circle_area(2.0));
}

Ожидаемый результат

2.25
12.57
round2 не помечена pub: внутри модуля её можно использовать, но вызов geometry::round2(1.0) из main дал бы ошибку E0603 (function round2 is private).

Когда модуль разрастается, его переносят в отдельный файл: строка mod counter; в main.rs или lib.rs говорит Rust искать код модуля в файле src/counter.rs. В путях модулей crate:: означает корень крейта, а super:: — родительский модуль.

Чтобы читать дальше, зарегистрируйся бесплатно

Остальные разделы урока, тест и заметки открываются с аккаунтом Educora. Регистрация занимает минуту, а прогресс сохраняется на всех твоих устройствах.

Зависимости и crates.io

crates.io — официальный реестр библиотек сообщества Rust. Чтобы подключить библиотеку, достаточно команды cargo add: она добавляет строку в раздел [dependencies] файла Cargo.toml, а при следующей сборке Cargo скачивает и компилирует библиотеку. Требование версии вроде "1.0" означает «любая версия, совместимая с 1.x» (SemVer). Точно выбранные версии записываются в Cargo.lock, чтобы проект одинаково собирался на любом компьютере.

Terminal
cargo add serde --features derive
cargo add clap --features derive
cargo update
Text
[package]
name = "wordcount"
version = "0.1.0"
edition = "2024"

[dependencies]
clap = { version = "4", features = ["derive"] }
serde = { version = "1.0", features = ["derive"] }
На практике cargo add записывает полный номер последней версии. serde преобразует данные в JSON и другие форматы, а clap разбирает аргументы командной строки. Нашему счётчику слов они не нужны — это лишь пример.
КомандаЧто делает
cargo add nameдобавляет зависимость
cargo updateобновляет зависимости до новейших допустимых версий
cargo testзапускает все тесты
cargo doc --openгенерирует документацию проекта и зависимостей и открывает её в браузере
cargo install --path .устанавливает твою утилиту как системную команду

Проект: библиотечная часть

Создай проект командой cargo new wordcount и отдели логику от работы с файлами и экраном: чистая функция подсчёта слов будет в src/lib.rs, а код, который читает файл и печатает результат, — в src/main.rs. Такое разделение упрощает тестирование. Функция делит текст по пробелам, убирает из каждого слова знаки препинания, переводит его в нижний регистр, считает в HashMap и сортирует результат по количеству (от большего к меньшему), а при равенстве — по алфавиту.

Rust
// src/lib.rs
use std::collections::HashMap;

pub fn count_words(text: &str) -> Vec<(String, usize)> {
    let mut counts: HashMap<String, usize> = HashMap::new();
    for raw in text.split_whitespace() {
        let word = raw
            .chars()
            .filter(|c| c.is_alphanumeric())
            .collect::<String>()
            .to_lowercase();
        if !word.is_empty() {
            *counts.entry(word).or_insert(0) += 1;
        }
    }
    let mut result: Vec<(String, usize)> = counts.into_iter().collect();
    result.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
    result
}
sort_by принимает замыкание, сравнивающее два элемента: b.1.cmp(&a.1) даёт порядок по убыванию количества, а .then(...) при равенстве упорядочивает слова по алфавиту. Так исчезает случайный порядок HashMap.

Тесты

В Rust тесты обычно пишут рядом с кодом, который они проверяют. Атрибут #[cfg(test)] компилирует модуль только при cargo test, а #[test] помечает функцию как тест. assert_eq!(a, b) проверяет равенство двух значений, assert!(условие) — истинность условия; при неудаче тест паникует и показывает оба значения.

Rust
// end of src/lib.rs
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn counts_and_sorts() {
        let result = count_words("b a B, c a b");
        assert_eq!(result[0], (String::from("b"), 3));
        assert_eq!(result[1], (String::from("a"), 2));
        assert_eq!(result.len(), 3);
    }

    #[test]
    fn ignores_punctuation_only_text() {
        assert!(count_words("  ...  ").is_empty());
    }
}
use super::*; подключает в тесты всё из родительского модуля, включая count_words. После очистки слово B, превращается в b, поэтому b считается три раза.
Text
$ cargo test
   Compiling wordcount v0.1.0 (/home/murad/wordcount)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.84s
     Running unittests src/lib.rs (target/debug/deps/wordcount-3f2a9c1d8e7b6a50)

running 2 tests
test tests::counts_and_sorts ... ok
test tests::ignores_punctuation_only_text ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Сокращённый вывод: время и хеш в имени файла на каждом компьютере свои. Тесты выполняются параллельно, поэтому порядок строк test ... может меняться.

Проект: main.rs и запуск

main.rs обращается к библиотеке по имени пакета: use wordcount::count_words;. env::args() даёт аргументы командной строки (нулевой аргумент — имя самой программы), а fs::read_to_string читает файл и возвращает Result. Ошибки мы пишем в стандартный поток ошибок через eprintln! и завершаемся с кодом неудачи через process::exit(1).

Rust
// src/main.rs
use std::env;
use std::fs;
use std::process;

use wordcount::count_words;

fn main() {
    let args: Vec<String> = env::args().collect();
    if args.len() < 2 {
        eprintln!("Usage: wordcount <file>");
        process::exit(1);
    }
    let text = match fs::read_to_string(&args[1]) {
        Ok(text) => text,
        Err(e) => {
            eprintln!("Cannot read {}: {}", args[1], e);
            process::exit(1);
        }
    };
    let words = count_words(&text);
    let total: usize = words.iter().map(|(_, n)| n).sum();
    println!("Total words: {total}");
    println!("Unique words: {}", words.len());
    for (word, n) in words.iter().take(3) {
        println!("{word}: {n}");
    }
}
Text
The sea, the wind and the sun.
The wind is cold; the sea is deep.
Файл poem.txt, сохранённый в папке проекта.
Text
$ cargo run -q -- poem.txt
Total words: 15
Unique words: 8
the: 5
is: 2
sea: 2
Из 15 слов различных 8. is, sea и wind встречаются по 2 раза; показаны первые два по алфавиту.

Запомни

  • Пакет — проект с Cargo.toml; main.rs даёт исполняемый крейт, lib.rs — библиотечный.
  • Элементы модуля по умолчанию закрыты; pub открывает их, а use сокращает пути.
  • cargo add подключает зависимость с crates.io, а Cargo.lock запоминает точные версии.
  • Тесты — это функции #[test] в модуле #[cfg(test)], их запускают через cargo test.
  • Логика в lib.rs, а ввод-вывод в main.rs — так код легко тестировать.
Заметил ошибку или неточность в уроке?

Проверь себя

Вопросов: 10. Каждый правильный ответ приносит XP.

Вопрос 1 / 10

Вопрос 1 / 10. Какова видимость функции внутри модуля по умолчанию?