1. Что это и зачем нужна

UUID (Universally Unique Identifier) — это стандарт идентификации, используемый в разработке программного обеспечения для создания уникальных ключей без необходимости централизованного управления. Библиотека uuid для JavaScript (Node.js) предоставляет простой и надежный способ генерации UUID версий 1, 3, 4, 5 и 7 (в последних версиях). Она является одной из самых популярных и скачиваемых библиотек в экосистеме Node.js, с более чем 50 миллионами загрузок в неделю.

Зачем это нужно? В современной разработке практически каждое приложение нуждается в уникальных идентификаторах: для записей в базе данных, идентификации пользователей, сессий, заказов, файлов и многого другого. Использование UUID позволяет избежать коллизий (совпадений идентификаторов) даже в распределенных системах, где несколько серверов генерируют идентификаторы одновременно. Например, если у вас есть микросервисная архитектура, где каждый сервис создает записи независимо, UUID гарантирует, что два сервиса никогда не создадут запись с одинаковым ID.

Библиотека uuid поддерживает несколько версий стандарта: v1 (на основе времени и MAC-адреса), v4 (случайная генерация), v7 (временная метка + случайные данные — новый стандарт, оптимизированный для баз данных). Версия 4 является наиболее распространенной благодаря своей простоте и высокой степени уникальности. Версия 7 рекомендуется для новых проектов, так как она обеспечивает естественную сортировку по времени, что улучшает производительность индексов в базах данных.

2. Установка

Установка библиотеки uuid в проект Node.js выполняется через npm (Node Package Manager). Откройте терминал в корневой папке вашего проекта и выполните команду:

npm install uuid

Если вы используете yarn:

yarn add uuid

После установки библиотека будет доступна для импорта в вашем коде. Для TypeScript проектов также доступны типы (устанавливаются автоматически вместе с пакетом).

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

Создайте файл example.js и добавьте следующий код:

import { v4 as uuidv4 } from 'uuid';

// Генерация одного UUID v4
const myUUID = uuidv4();
console.log('Сгенерированный UUID:', myUUID);
// Пример вывода: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

Запустите файл командой node example.js. Вы увидите сгенерированный UUID в консоли. Это минимальный пример, демонстрирующий основную функциональность библиотеки — генерацию одного идентификатора.

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

Библиотека uuid предоставляет несколько функций для генерации UUID разных версий. Рассмотрим каждую из них подробно.

4.1. v1() — UUID версии 1 (на основе времени)

Сигнатура: v1(options?, buffer?, offset?)

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

import { v1 as uuidv1 } from 'uuid';

const uuid1 = uuidv1();
console.log('UUID v1:', uuid1);
// Пример: 'c9b1deb4-3b7d-11ec-8d3d-0242ac130003'

// С опциями: отключить MAC-адрес (использовать случайный узел)
const uuid1NoMac = uuidv1({ node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab] });
console.log('UUID v1 с кастомным узлом:', uuid1NoMac);

4.2. v4() — UUID версии 4 (случайный)

Сигнатура: v4(options?, buffer?, offset?)

Описание: Генерирует UUID версии 4, используя криптографически стойкий генератор случайных чисел. Это самая популярная версия, так как она проста и не требует никакой информации об устройстве. Вероятность коллизии крайне мала (примерно 5.3 × 10⁻³⁶ для 122 случайных бит).

import { v4 as uuidv4 } from 'uuid';

const uuid4 = uuidv4();
console.log('UUID v4:', uuid4);
// Пример: '110ec58a-a0f2-4ac4-8393-c866d813b8d1'

// Генерация нескольких UUID
for (let i = 0; i < 3; i++) {
  console.log(`UUID v4 #${i + 1}:`, uuidv4());
}

4.3. v7() — UUID версии 7 (временная метка + случайные данные)

Сигнатура: v7(options?, buffer?, offset?)

Описание: Генерирует UUID версии 7, который сочетает временную метку (миллисекунды с эпохи Unix) со случайными данными. Эта версия была добавлена в RFC 9562 и рекомендуется для новых приложений, так как она обеспечивает естественную сортировку по времени, что улучшает производительность индексов B-деревьев в базах данных (например, PostgreSQL, MySQL).

import { v7 as uuidv7 } from 'uuid';

const uuid7 = uuidv7();
console.log('UUID v7:', uuid7);
// Пример: '018f3a6e-1b3c-7b00-8d3d-0242ac130003'

// С опцией кастомной временной метки
const customTime = Date.now() - 3600000; // 1 час назад
const uuid7Custom = uuidv7({ msecs: customTime });
console.log('UUID v7 с кастомным временем:', uuid7Custom);

4.4. v3() — UUID версии 3 (на основе MD5-хеша)

Сигнатура: v3(name, namespace, buffer?, offset?)

Описание: Генерирует UUID версии 3 на основе MD5-хеша от имени (строки) и пространства имен (UUID). Это детерминированный метод: для одних и тех же входных данных всегда будет получен один и тот же UUID. Полезно для создания стабильных идентификаторов на основе данных.

import { v3 as uuidv3 } from 'uuid';

// Пространства имен определены в стандарте
const NAMESPACE_URL = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';

const uuid3 = uuidv3('https://example.com', NAMESPACE_URL);
console.log('UUID v3 для URL:', uuid3);
// Пример: '9073926b-929f-31c2-abc9-fad77ae3e8eb'

// Другой пример для DNS
const NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
const uuid3Dns = uuidv3('example.com', NAMESPACE_DNS);
console.log('UUID v3 для DNS:', uuid3Dns);

4.5. v5() — UUID версии 5 (на основе SHA-1 хеша)

Сигнатура: v5(name, namespace, buffer?, offset?)

Описание: Аналогичен v3, но использует SHA-1 вместо MD5. SHA-1 считается более безопасным, чем MD5, поэтому v5 рекомендуется вместо v3 для новых проектов, требующих детерминированных UUID.

import { v5 as uuidv5 } from 'uuid';

const NAMESPACE_OID = '6ba7b812-9dad-11d1-80b4-00c04fd430c8';

const uuid5 = uuidv5('1.3.6.1.4.1', NAMESPACE_OID);
console.log('UUID v5 для OID:', uuid5);
// Пример: 'f4a7e5b1-3b7d-5bad-9bdd-2b0d7b3dcb6d'

4.6. validate() — Проверка корректности UUID

Сигнатура: validate(uuid)

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

import { validate } from 'uuid';

console.log(validate('9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d')); // true
console.log(validate('not-a-uuid')); // false
console.log(validate('')); // false
console.log(validate('550e8400-e29b-41d4-a716-446655440000')); // true

4.7. version() — Определение версии UUID

Сигнатура: version(uuid)

Описание: Определяет версию переданного UUID. Возвращает число (1, 3, 4, 5, 7) или выбрасывает ошибку TypeError, если строка не является корректным UUID.

import { version } from 'uuid';

const uuidV4 = '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d';
console.log('Версия UUID:', version(uuidV4)); // 4

const uuidV1 = 'c9b1deb4-3b7d-11ec-8d3d-0242ac130003';
console.log('Версия UUID:', version(uuidV1)); // 1

// Пример с обработкой ошибки
try {
  version('invalid-uuid');
} catch (error) {
  console.error('Ошибка:', error.message); // TypeError: Invalid UUID
}

4.8. stringify() и parse() — Преобразование между строкой и байтами

Сигнатура: stringify(buf, offset?) и parse(uuid)

Описание: parse() преобразует строку UUID в массив байтов (Uint8Array). stringify() делает обратное преобразование — из массива байтов в строку. Полезно для работы с бинарными данными или при передаче UUID в компактном формате.

import { parse, stringify } from 'uuid';

const uuidStr = '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d';

// Преобразование в байты
const bytes = parse(uuidStr);
console.log('Байты UUID:', bytes);
// Uint8Array(16) [155, 29, 235, 77, 59, 125, 75, 173, 155, 221, 43, 13, 123, 220, 182, 214]

// Обратное преобразование
const restoredStr = stringify(bytes);
console.log('Восстановленная строка:', restoredStr);
// '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

// Работа с частью буфера
const buffer = new Uint8Array(32);
const offset = 8;
stringify(bytes, buffer, offset);
console.log('Строка в буфере с offset:', new TextDecoder().decode(buffer.slice(offset, offset + 36)));

4.9. NIL — Константа нулевого UUID

Сигнатура: NIL (константа)

Описание: Представляет нулевой UUID — '00000000-0000-0000-0000-000000000000'. Используется как значение по умолчанию или для обозначения отсутствия идентификатора.

import { NIL } from 'uuid';

console.log('Нулевой UUID:', NIL); // '00000000-0000-0000-0000-000000000000'
console.log('Длина:', NIL.length); // 36

// Использование в качестве значения по умолчанию
function getUser(id = NIL) {
  if (id === NIL) {
    console.log('ID не указан, используем значение по умолчанию');
  }
  return { id, name: 'User' };
}
console.log(getUser()); // { id: '00000000-0000-0000-0000-000000000000', name: 'User' }

5. Реальный практический пример (100-200 строк кода)

Рассмотрим пример создания простого REST API для управления задачами (Todo List) с использованием Express.js и UUID. Этот пример демонстрирует, как UUID используются в реальном проекте для идентификации записей.

// todo-api.js
import express from 'express';
import { v4 as uuidv4, v7 as uuidv7, validate, version } from 'uuid';

const app = express();
app.use(express.json());

// Хранилище задач в памяти (для примера)
const tasks = new Map();

// Вспомогательная функция для логирования
function logAction(action, details) {
  const timestamp = new Date().toISOString();
  console.log(`[${timestamp}] ${action}:`, details);
}

// 1. Создание новой задачи
app.post('/tasks', (req, res) => {
  const { title, description, priority = 'medium' } = req.body;
  
  if (!title || typeof title !== 'string') {
    return res.status(400).json({ error: '