UUID в JavaScript

Что такое UUID в JavaScript

crypto.randomUUID() — встроенное решение. Метод доступен в защищённом контексте: на HTTPS-страницах, на localhost и в Node начиная с 16.7, и возвращает канонический UUID v4 в нижнем регистре, например 550e8400-e29b-41d4-a716-446655440000. Он использует тот же криптостойкий генератор, что и остальной Web Crypto API, поэтому писать свой на Math.random() не нужно: такой генератор небезопасен и регулярно приводит к ошибкам.

Чего платформа не даёт — так это другой версии. Если нужен v7, формат RFC 9562, где первые 48 бит — метка времени Unix и вставки в базу идут последовательно, установите пакет uuid и импортируйте v7. Если нужен только v4 и приходится поддерживать старую среду без randomUUID, соберите значение из crypto.getRandomValues и выставьте ниблы версии и варианта самостоятельно, как в примере ниже.

Как использовать

1. В браузере или Node 16.7+ вызовите crypto.randomUUID() — устанавливать ничего не нужно.
2. Для v7 установите пакет uuid и импортируйте v7.
3. Нужно значение прямо сейчас или пакет для тестовых данных? Используйте генератор выше.

Сценарии

• Ключи в React и Vue, идентификаторы запросов и оптимистичных обновлений, которые не должны совпадать у разных клиентов.
• Тестовые данные, где каждой строке нужен свой идентификатор, создаваемый скриптом, а не хранимый в файле.
• Имена файлов и загрузок, которые не должны раскрывать имя или индекс и обязаны безопасно попадать в заголовки.

Сравнение UUID в JavaScript с другими форматами

Примеры кода

Браузер / Node 16.7+

// версия 4, криптостойко, без зависимостей
const id = crypto.randomUUID();
// '550e8400-e29b-41d4-a716-446655440000'

Node и v7

import { v7 as uuidv7, v4 as uuidv4 } from 'uuid';

const ordered = uuidv7();   // 019535d9-3df7-79fb-b466-fa907fa17f9e
const random  = uuidv4();

// v7 сортируется по времени создания: ORDER BY id близок к ORDER BY created_at

Запасной вариант

function uuidv4() {
  const b = crypto.getRandomValues(new Uint8Array(16));
  b[6] = (b[6] & 0x0f) | 0x40;   // версия 4
  b[8] = (b[8] & 0x3f) | 0x80;   // вариант RFC 4122
  const hex = [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
  return `${hex.slice(0,8)}-${hex.slice(8,12)}-${hex.slice(12,16)}-${hex.slice(16,20)}-${hex.slice(20)}`;
}

UUID v5 из имени

import { v5 as uuidv5 } from 'uuid';

// Одно и то же пространство имён и имя всегда дают один UUID
const NS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
uuidv5('example.com', NS);   // одинаково у всех вызовов

Частые вопросы