1. Что такое uuid и зачем она нужна?

Библиотека uuid для Rust — это одна из самых популярных и стабильных крейтов для генерации, парсинга и работы с универсальными уникальными идентификаторами (UUID) в соответствии со стандартом RFC 4122. UUID (Universally Unique Identifier) представляет собой 128-битное число, которое гарантированно уникально в пространстве и времени, что делает его идеальным для использования в качестве первичных ключей в базах данных, идентификаторов сессий, трекеров событий и любых других сценариев, где требуется уникальность без централизованного управления.

Зачем нужна эта библиотека? В современной разработке на Rust часто возникает необходимость генерировать уникальные идентификаторы, которые не зависят от порядка создания объектов, не раскрывают информацию о количестве записей (в отличие от автоинкрементных ID) и могут быть безопасно переданы между разными системами. Крейт uuid предоставляет полный набор инструментов для работы с UUID версий 1, 3, 4, 5 и 7 (последняя — временная версия, добавленная в недавних обновлениях). Он поддерживает сериализацию через serde, работу с разными форматами представления (канонический, без дефисов, URN) и интеграцию с популярными базами данных через соответствующие фичи.

Библиотека активно поддерживается сообществом, имеет отличную документацию и используется в тысячах проектов. Она написана на чистом Rust без внешних зависимостей (за исключением опциональных фич), что гарантирует безопасность памяти и высокую производительность. Если вы пишете веб-сервер, распределённую систему, инструмент командной строки или любое другое приложение на Rust, где нужны уникальные идентификаторы — uuid станет вашим незаменимым помощником.

2. Установка

Для добавления библиотеки uuid в ваш проект на Rust выполните одну из следующих команд в корневой директории проекта:

cargo add uuid

Или вручную добавьте зависимость в файл Cargo.toml:

[dependencies]
uuid = { version = "1.10", features = ["v4", "v7", "serde"] }

Обратите внимание на секцию features. По умолчанию библиотека включает только базовые возможности. Для работы с конкретными версиями UUID необходимо явно указать соответствующие фичи:

• v1 — UUID версии 1 (на основе времени и MAC-адреса)
• v3 — UUID версии 3 (на основе MD5-хэша от имени и пространства имён)
• v4 — UUID версии 4 (случайный)
• v5 — UUID версии 5 (на основе SHA-1 хэша от имени и пространства имён)
• v7 — UUID версии 7 (временной с миллисекундной точностью, RFC 9562)
• serde — поддержка сериализации/десериализации через крейт serde
• fast-rng — использование быстрого генератора случайных чисел (рекомендуется для v4)

Если вам нужны все возможности, можно указать:

[dependencies]
uuid = { version = "1.10", features = ["v1", "v3", "v4", "v5", "v7", "serde"] }

3. Быстрый старт — минимальный рабочий пример

Создайте новый проект командой cargo new uuid_example, добавьте зависимость в Cargo.toml как указано выше, затем замените содержимое файла src/main.rs на следующий код:

use uuid::Uuid;

fn main() {
    // Генерируем случайный UUID версии 4
    let my_uuid = Uuid::new_v4();
    println!("Сгенерированный UUID v4: {}", my_uuid);
    
    // Парсим UUID из строки
    let parsed = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000")
        .expect("Не удалось распарсить UUID");
    println!("Распарсенный UUID: {}", parsed);
    
    // Сравнение UUID
    println!("Равны ли UUID? {}", my_uuid == parsed);
}

Запустите проект командой cargo run. Вы должны увидеть вывод, похожий на:

Сгенерированный UUID v4: f47ac10b-58cc-4372-a567-0e02b2c3d479
Распарсенный UUID: 550e8400-e29b-41d4-a716-446655440000
Равны ли UUID? false

Поздравляю! Вы только что сгенерировали и распарсили свой первый UUID на Rust.

4. Основные методы и функции

Ниже представлены 10 наиболее важных методов и функций библиотеки uuid. Для каждого приведена сигнатура, краткое описание и рабочий пример кода.

4.1. Uuid::new_v4() — генерация случайного UUID

Сигнатура: pub fn new_v4() -> Uuid

Описание: Генерирует UUID версии 4, основанный на случайных числах. Это самый распространённый тип UUID, используемый по умолчанию в большинстве приложений.

use uuid::Uuid;

fn main() {
    let uuid = Uuid::new_v4();
    println!("Случайный UUID v4: {}", uuid);
    // Пример вывода: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
}

4.2. Uuid::new_v7() — генерация временного UUID

Сигнатура: pub fn new_v7() -> Uuid

Описание: Генерирует UUID версии 7, который содержит временную метку с миллисекундной точностью и случайные биты. Такие UUID можно сортировать по времени создания, что полезно для индексации в базах данных.

use uuid::Uuid;

fn main() {
    let uuid = Uuid::new_v7();
    println!("Временной UUID v7: {}", uuid);
    // Пример вывода: 018f3a6e-1b2c-7a3d-8e4f-5a6b7c8d9e0f
}

4.3. Uuid::parse_str() — парсинг UUID из строки

Сигнатура: pub fn parse_str(input: &str) -> Result<Uuid, uuid::Error>

Описание: Парсит строковое представление UUID в структуру Uuid. Поддерживает форматы с дефисами, без дефисов, в фигурных скобках и URN-формат.

use uuid::Uuid;

fn main() {
    // Канонический формат с дефисами
    let uuid1 = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000").unwrap();
    
    // Формат без дефисов
    let uuid2 = Uuid::parse_str("550e8400e29b41d4a716446655440000").unwrap();
    
    // URN-формат
    let uuid3 = Uuid::parse_str("urn:uuid:550e8400-e29b-41d4-a716-446655440000").unwrap();
    
    println!("Все три UUID равны: {}", uuid1 == uuid2 && uuid2 == uuid3); // true
}

4.4. Uuid::nil() — создание нулевого UUID

Сигнатура: pub fn nil() -> Uuid

Описание: Создаёт UUID, состоящий из всех нулей (00000000-0000-0000-0000-000000000000). Используется как значение по умолчанию или для обозначения отсутствия идентификатора.

use uuid::Uuid;

fn main() {
    let nil_uuid = Uuid::nil();
    println!("Нулевой UUID: {}", nil_uuid);
    assert!(nil_uuid.is_nil());
}

4.5. Uuid::is_nil() — проверка на нулевой UUID

Сигнатура: pub fn is_nil(&self) -> bool

Описание: Проверяет, является ли данный UUID нулевым (все биты равны нулю). Полезно для валидации данных.

use uuid::Uuid;

fn main() {
    let uuid = Uuid::new_v4();
    println!("Является ли нулевым? {}", uuid.is_nil()); // false
    
    let nil = Uuid::nil();
    println!("Является ли нулевым? {}", nil.is_nil()); // true
}

4.6. Uuid::get_version() — получение версии UUID

Сигнатура: pub fn get_version(&self) -> Option<Version>

Описание: Возвращает версию UUID (1, 3, 4, 5 или 7) в виде перечисления Version. Если версия не распознана, возвращает None.

use uuid::{Uuid, Version};

fn main() {
    let uuid_v4 = Uuid::new_v4();
    let uuid_v7 = Uuid::new_v7();
    
    match uuid_v4.get_version() {
        Some(Version::Random) => println!("Это UUID v4 (случайный)"),
        Some(Version::TimeMac) => println!("Это UUID v1 (временной)"),
        Some(Version::SortRand) => println!("Это UUID v7 (временной сортируемый)"),
        _ => println!("Неизвестная версия"),
    }
    
    println!("Версия v7: {:?}", uuid_v7.get_version()); // Some(SortRand)
}

4.7. Uuid::to_string() — преобразование в строку

Сигнатура: pub fn to_string(&self) -> String

Описание: Преобразует UUID в строку в каноническом формате (с дефисами). Реализует трейт Display, поэтому можно использовать макрос println! напрямую.

use uuid::Uuid;

fn main() {
    let uuid = Uuid::new_v4();
    let uuid_str = uuid.to_string();
    println!("UUID как строка: {}", uuid_str);
    // Длина строки всегда 36 символов: 8-4-4-4-12
    assert_eq!(uuid_str.len(), 36);
}

4.8. Uuid::as_hyphenated() — получение форматированного представления

Сигнатура: pub fn as_hyphenated(&self) -> Hyphenated<'_>

Описание: Возвращает структуру, реализующую Display, которая выводит UUID в каноническом формате с дефисами. Это альтернатива to_string(), которая не выделяет память.

use uuid::Uuid;

fn main() {
    let uuid = Uuid::new_v4();
    // Без выделения памяти
    println!("Гифенированный: {}", uuid.as_hyphenated());
    // Альтернатива: без дефисов
    println!("Простой: {}", uuid.as_simple());
    // В фигурных скобках
    println!("В скобках: {}", uuid.as_braced());
    // URN-формат
    println!("URN: {}", uuid.as_urn());
}

4.9. Uuid::new_v1() — генерация UUID на основе времени и MAC-адреса

Сигнатура: pub fn new_v1(context: &Timestamp) -> Uuid

Описание: Генерирует UUID версии 1, который включает временную метку (100-наносекундные интервалы с 15 октября 1582 года) и MAC-адрес. Требует контекст с информацией о временной метке и узле.

use uuid::{Uuid, Timestamp, Context};
use std::time::SystemTime;

fn main() {
    // Создаём контекст для v1
    let context = Context::new(42); // 42 — идентификатор кластера
    let timestamp = Timestamp::from_unix_time(
        &context,
        SystemTime::now()
            .duration_since(SystemTime::UNIX_EPOCH)
            .unwrap()
            .as_secs() as i64,
        0,
    );
    
    let uuid_v1 = Uuid::new_v1(×tamp);
    println!("UUID v1: {}", uuid_v1);
}

4.10. Uuid::new_v5() — генерация UUID на основе имени и пространства имён

Сигнатура: pub fn new_v5(namespace: &Uuid, name: &[u8]) -> Uuid

Описание: Генерирует UUID версии 5 на основе SHA-1 хэша от имени (произвольные байты) и пространства имён (UUID). Для одного и того же имени и пространства имён всегда будет генерироваться одинаковый UUID.

use uuid::Uuid;

fn main() {
    // Предопределённые пространства имён
    let namespace_dns = Uuid::NAMESPACE_DNS;
    let namespace_url = Uuid::NAMESPACE_URL;
    
    // Генерация UUID для домена
    let uuid_dns = Uuid::new_v5(&namespace_dns, b"example.com");
    println!("UUID для DNS 'example.com': {}", uuid_dns);
    
    // Генерация UUID для URL
    let uuid_url = Uuid::new_v5(&namespace_url, b"https://example.com/page");
    println!("UUID для URL: {}", uuid_url);
    
    // Детерминированность: одинаковые входные данные дают одинаковый UUID
    let uuid_dns2 = Uuid::new_v5(&namespace_dns, b"example.com");
    assert_eq!(uuid_dns, uuid_dns2);
    println!("Детерминированность