Генерация UUID в Node.js

UUID — это 128-битная строка (универсально-уникальный идентификатор), которую удобно использовать для маркировки ресурсов и доступа к данным. Из-за большой длины совпадения идентификаторов крайне редки, поэтому UUID можно генерировать автономно без запроса к централизованной базе.

Краткое определение

UUID (Universally Unique Identifier) — 128-битный идентификатор, предназначенный для глобально уникальной маркировки объектов; в виде строки обычно представлен в шестнадцатеричном формате с дефисами.

Использование встроенного модуля crypto

Node.js содержит модуль crypto с методом randomUUID(), который генерирует UUID v4.

const crypto = require("crypto")
const uuid = crypto.randomUUID()
console.log(uuid) // пример: '3a6f1e58-2b1f-4f3a-8f2e-0d4f5a3b2c1d'

Если нужно отключить использование кэша источника энтропии при генерации, передайте опцию disableEntropyCache:

const uuid = crypto.randomUUID({ disableEntropyCache: true })

Important: встроенный crypto не требует дополнительных зависимостей и хорошо подходит для большинства сценариев.

Пакет uuid (npm)

Пакет uuid — сторонняя библиотека с поддержкой нескольких версий UUID. Установите её так:

npm install uuid

Версии UUID в пакете:

• v1 — на основе времени (включает метку времени и MAC/случайные данные);
• v3 и v5 — детерминированные: UUID строится из namespace и имени (MD5 / SHA-1);
• v4 — случайно генерируемые UUID.

Пример генерации UUID v4:

const { v4: uuidv4 } = require("uuid")
const id = uuidv4()
console.log(id)

Когда выбирать uuid: если нужна поддержка разных версий UUID (v1, v3, v5) или вам подходят их семантики — пакет удобен.

Nano ID

Nano ID — альтернатива для компактных и быстрых идентификаторов. В отличие от UUID (128 бит, формат с дефисами), Nano ID генерирует короткие URL-безопасные строки и обычно используется когда важна компактность результата.

Установка и пример:

npm install nanoid

const { nanoid } = require("nanoid")
const id = nanoid()
console.log(id) // пример: 'V1StGXR8_Z5jdHi6B-myT'

Notes: Nano ID обычно компактнее и работает быстрее по сравнению с некоторыми реализациями UUID-пакетов. Если вам важен минимальный размер идентификатора и вы не требуете стандартизованного формата UUID, Nano ID — хороший выбор.

Как выбрать метод: мини-методология

1. Требуется ли соответствие стандарту UUID (например, для интеграции) — да → используйте crypto.randomUUID() или uuid.
2. Нужна ли компактность и простые URL-safe идентификаторы — да → рассмотрите Nano ID.
3. Нужны ли разные версии (v1/v3/v5) — да → используйте uuid.
4. Избегаете зависимостей — используйте встроенный crypto.

Сравнительная матрица

Хэштеги инцидентов и критерии приёмки

Критерии приёмки для выбранного подхода:

• Идентификатор уникален в пределах ожидаемого домена (проверка на тестовых данных).
• Формат соответствует требованиям интеграции (если есть внешние потребители).
• Производительность: генерация X идентификаторов/сек (замерьте в вашем окружении).
• Отсутствие дополнительных ненужных зависимостей для продакшн-билда.

Чек-лист по ролям

Для разработчика:

• Нужен ли стандартный UUID или достаточно короткого ID?
• Есть ли требование к версии UUID?
• Выполнены ли юнит-тесты генерируемых ID?

Для инженера DevOps:

• Можно ли избежать внешних зависимостей в контейнере?
• Есть ли требования к предсказуемости/энтропии в окружении?

Для инженера по безопасности:

• Источник энтропии надёжен (особенно в виртуализованных средах).
• Нет ли возможности угадывания/подстановки ID при атаке.

Decision flow (быстрый выбор)

flowchart TD
  A[Нужно ли строгое соответствие UUID?] -->|Да| B[Использовать crypto.randomUUID'' или uuid]
  A -->|Нет| C[Нужна ли компактность/URL-safe?]
  C -->|Да| D[Использовать Nano ID]
  C -->|Нет| B

Примеры использования в проекте

• Токены сессий — рассмотрите Nano ID для компактности, если формат допускается.
• Идентификаторы записей БД — crypto.randomUUID() или uuid.v4(), если нужна стандартность.
• Интеграция с внешними сервисами — следуйте их требованиям к формату.

Когда подход может не сработать

• Если требуется глобальная гарантия отсутствия коллизий с существующей системой референций, нужна централизованная проверка, а не только UUID.
• В крайне энтропийно-ограниченных средах (редко) генерация случайных UUID может требовать дополнительной проверки источника случайных чисел.

Вывод

Для большинства задач в Node.js начните с builtin crypto.randomUUID() — он не добавляет зависимостей и генерирует стандартизованные UUID. Если важна компактность и скорость при сохранении простоты, используйте Nano ID. Если нужна поддержка разных версий UUID или детерминированные идентификаторы на основе namespace/name — выбирайте пакет uuid.

Important: всегда проверяйте требования интеграций и измеряйте производительность/размеры в вашем окружении перед финальным решением.