Практическое руководство по генерации UUID в JavaScript

Нужен уникальный идентификатор для вашего JavaScript-приложения? Независимо от того, создаёте ли вы приложение с базой данных, управляете пользовательскими сессиями или отслеживаете распределённые запросы, генерация UUID — это фундаментальный навык, необходимый каждому разработчику.

Это руководство охватывает современные подходы к генерации UUID в JavaScript, от встроенного метода crypto.randomUUID() до универсального npm-пакета uuid. Вы узнаете, какой метод подходит для вашего конкретного случая — будь то современное веб-приложение, Node.js-сервис или устаревшая система, требующая широкой совместимости.

Что такое UUID и зачем его использовать?

UUID (Universally Unique Identifier, универсальный уникальный идентификатор) — это 128-битный идентификатор, отформатированный как 36 символов: 550e8400-e29b-41d4-a716-446655440000. Также известные как GUID, эти идентификаторы практически гарантированно уникальны без необходимости централизованного управления или координации с базой данных.

Для frontend и Node.js разработчиков UUID решают критические задачи:

• Записи в базе данных: генерация первичных ключей без конфликтов auto-increment
• Токены сессий: создание непредсказуемых, уникальных идентификаторов сессий
• Именование файлов: предотвращение коллизий имён в загружаемом контенте
• Отслеживание запросов: трассировка операций в микросервисной архитектуре

Современный метод: crypto.randomUUID()

Метод crypto.randomUUID() является текущим стандартом для генерации уникальных ID-значений в современных окружениях. Он встроен в браузеры и Node.js (14.17+), не требует зависимостей и создаёт криптографически безопасные UUID v4 значения.

Реализация в браузере

const uuid = crypto.randomUUID();
console.log(uuid); // "3b99e3e0-7598-4bf8-b9c1-e915af91713c"

Реализация в Node.js

import { randomUUID } from 'crypto';

const uuid = randomUUID();
console.log(uuid); // "b7e44f0a-811f-4c1c-b7f0-48d51f5dbc1f"

Поддержка браузерами: Chrome 92+, Firefox 95+, Safari 15.4+, Edge 92+
Поддержка Node.js: версия 14.17.0+

Используйте crypto.randomUUID(), когда вам нужны безопасные, случайные UUID в современных приложениях без внешних зависимостей.

Резервный метод: crypto.getRandomValues()

Для окружений, которые не поддерживают crypto.randomUUID(), вы можете реализовать генерацию UUID v4 с использованием crypto.getRandomValues(). Этот метод работает в браузерах начиная с Chrome 11 и версиях Node.js с модулем crypto.

function generateUUID() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    const r = crypto.getRandomValues(new Uint8Array(1))[0];
    const v = c === 'x' ? (r & 0x0f) : ((r & 0x03) | 0x08);
    return v.toString(16);
  });
}

const uuid = generateUUID();
console.log(uuid); // "42254574-affd-47cc-9915-0ecae592351b"

Этот подход сохраняет криптографическую безопасность, поддерживая при этом более старые окружения.

npm-пакет uuid для максимальной гибкости

npm-пакет uuid остаётся наиболее универсальным решением для генерации UUID в JavaScript, особенно когда вам нужны конкретные версии UUID или максимальная совместимость.

Установка

npm install uuid

Базовое использование (UUID v4)

import { v4 as uuidv4 } from 'uuid';

const uuid = uuidv4();
console.log(uuid); // "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"

Другие версии UUID

import { v1, v3, v5 } from 'uuid';

// v1: на основе временной метки (сортируемые)
const uuid1 = v1(); 

// v3/v5: на основе имени (детерминированные)
const uuid5 = v5('hello.example.com', v5.DNS);

Пакет uuid поддерживает все версии UUID (v1-v5), что делает его идеальным, когда вам нужны:

• UUID на основе временных меток для сортируемых идентификаторов (v1)
• Детерминированные UUID из пар пространство имён/имя (v3, v5)
• Обратная совместимость со старыми версиями Node.js
• React Native или другие нестандартные окружения

Когда следует избегать Math.random()

Хотя вы можете встретить реализации UUID с использованием Math.random(), они должны использоваться только для тестирования или в небезопасных контекстах:

// ⚠️ НЕ БЕЗОПАСНО - Только для тестирования
function testUUID() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    const r = Math.random() * 16 | 0;
    const v = c === 'x' ? r : (r & 0x3 | 0x8);
    return v.toString(16);
  });
}

Math.random() не обладает криптографической безопасностью и не должен использоваться для production-UUID.

Лучшие практики и валидация

Валидация UUID

Всегда валидируйте UUID из внешних источников:

function isValidUUID(uuid) {
  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
  return uuidRegex.test(uuid);
}

console.log(isValidUUID('550e8400-e29b-41d4-a716-446655440000')); // true

Выбор правильного метода

• Современное веб-приложение или Node.js 14.17+: используйте crypto.randomUUID()
• Требуется поддержка устаревших браузеров: реализуйте с помощью crypto.getRandomValues()
• Конкретные версии UUID (v1, v3, v5): используйте npm-пакет uuid
• Максимальная совместимость: используйте npm-пакет uuid
• Только быстрое тестирование/прототипы: реализация с Math.random()

Заключение

Генерация UUID в JavaScript не должна быть сложной. Для большинства современных приложений crypto.randomUUID() предоставляет простое, безопасное решение. Когда вам нужна более широкая совместимость или конкретные версии UUID, npm-пакет uuid вас выручит. Просто помните, что нужно избегать Math.random() для production-использования и валидировать любые UUID из внешних источников.

Выбирайте метод, который соответствует вашему окружению и требованиям — ваше будущее «я» (и ваша команда) поблагодарят вас за чистые, надёжные уникальные идентификаторы во всей кодовой базе.

Часто задаваемые вопросы

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.