Generator UUID

Co to jest UUID?

UUID (Universally Unique Identifier) to 128-bitowy identyfikator używany w systemach komputerowych do unikalnej identyfikacji informacji. UUID jest standaryzowany zgodnie z RFC 4122 i dzięki swojej ogromnej entropii gwarantuje praktycznie zerowe prawdopodobieństwo kolizji – to znaczy, że dwa niezależnie wygenerowane UUID będą prawie na pewno unikalne.

UUID ma standardowy format: xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx, gdzie każdy x to cyfra szesnastkowa (0-9, a-f), M oznacza wersję UUID, a N oznacza wariant.

Wersje UUID

UUID v1 (znacznik czasu + adres MAC)

UUID v1 jest oparte na aktualnym znaczniku czasu (timestamp) i losowej wartości (w przeglądarce zamiast adresu MAC). Wykorzystuje 100-nanosekundowe interwały od 15 października 1582 roku (kalendarz gregoriański).

Zastosowanie:

• Sytuacje, gdy potrzebujesz chronologicznego sortowania UUID
• Debugowanie i logowanie (UUID zawiera informację o czasie utworzenia)
• Systemy rozproszone z synchronizacją czasową

Przykład: 6ba7b810-9dad-11d1-80b4-00c04fd430c8

Zalety:

• UUID można sortować chronologicznie według czasu utworzenia
• Przydatne do audytu i debugowania
• Zawiera informację o znaczniku czasu

Wady:

• Potencjalne ryzyko bezpieczeństwa – zawiera znacznik czasu
• W przeglądarce nie zawiera prawdziwego adresu MAC (zastąpionej wartością losową)
• Słaba lokalizacja DB (znacznik czasu jest w bitach niskiego rzędu)

UUID v3 (hash MD5)

UUID v3 jest generowane za pomocą hasha MD5 przestrzeni nazw UUID i nazwy. Jest deterministyczne – ta sama przestrzeń nazw + nazwa zawsze utworzą to samo UUID.

Zastosowanie:

• Konwersja URL, nazw DNS lub innych identyfikatorów na UUID
• Sytuacje, gdy potrzebujesz powtarzalnego UUID
• Mapowanie między różnymi systemami identyfikacji

Przykład: a3bb189e-8bf9-3888-9912-ace4e6543002

Zalety:

• Deterministyczne (ten sam wejście = ten sam wynik)
• Idealne do konwersji znanych identyfikatorów
• Brak kolizji dla różnych wejść

Wady:

• MD5 to przestarzały algorytm (preferuj v5)
• Wymaga przestrzeni nazw i nazwy
• Nie można odzyskać oryginalnego wejścia

UUID v4 (losowe) - ZALECANE

Najczęściej używana wersja UUID. UUID v4 jest generowane czysto losowo za pomocą kryptograficznie bezpiecznego generatora liczb losowych (crypto.getRandomValues()).

Zastosowanie:

• Klucze główne baz danych
• Identyfikatory sesji (session IDs)
• Unikalne nazwy plików
• Tokeny API
• Ogólne zastosowania, gdzie potrzebujesz gwarantowanie unikalnego ID

Przykład: f47ac10b-58cc-4372-a567-0e02b2c3d479

Zalety:

• Maksymalna entropia i bezpieczeństwo
• Brak zależności od czasu lub parametrów systemowych
• Najprostsza implementacja

Prawdopodobieństwo kolizji: Przy generowaniu 1 miliarda UUID na sekundę przez 100 lat szansa na kolizję wynosi około 0,00000006%.

UUID v5 (hash SHA-1)

UUID v5 jest takie samo jak v3, ale używa SHA-1 zamiast MD5. Nowocześniejsza i bezpieczniejsza alternatywa dla v3.

Zastosowanie:

• Takie samo jak v3, ale z lepszym bezpieczeństwem
• Preferowane przed v3 w nowych projektach
• Generowanie UUID z URL, nazw DNS, OID, X.500 DN

Przykład: 886313e1-3b8a-5372-9b90-0c9aee199e5d

Zalety:

• Deterministyczne
• SHA-1 jest bardziej odporne niż MD5
• Odpowiednie do mapowania między systemami

Wady:

• SHA-1 również jest uważane za przestarzałe (ale nadal bezpieczniejsze niż MD5)
• Wymaga przestrzeni nazw i nazwy

UUID v6 (posortowany znacznik czasu)

UUID v6 to ulepszona wersja v1 z przestawionymi bitami czasowymi dla lepszego indeksowania w bazach danych. Zaprojektowana, aby rozwiązać problemy z lokalizacją w bazach danych.

Zastosowanie:

• Klucze główne baz danych z sortowaniem czasowym
• Systemy wymagające chronologicznego sortowania i wydajności DB
• Nowocześniejsza alternatywa dla v1

Przykład: 1ec9414c-232a-6b00-b3c8-9e6bdeced846

Zalety:

• Lepsza lokalizacja DB niż v1 (znacznik czasu w bitach wysokiego rzędu)
• Chronologiczne sortowanie
• Kompatybilne ze standardem UUID

Wady:

• Mniej używane niż v1/v4
• Nadal zawiera informacje o czasie (ryzyko bezpieczeństwa)

UUID v7 (znacznik czasu Unix)

UUID v7 używa znacznika czasu Unix (milisekundy od 1970) + losowe bity. Najnowsza wersja UUID z najlepszą lokalizacją DB.

Zastosowanie:

• Nowoczesne klucze główne baz danych
• Systemy wymagające wydajności + sortowania czasowego
• Zastępuje v1/v6 w nowych projektach

Przykład: 017f22e2-79b0-7cc3-98c4-dc0c0c07398f

Zalety:

• Najlepsza lokalizacja DB spośród wszystkich wersji
• Znacznik czasu Unix jest standardowy
• Łączy zalety losowości i sortowania czasowego

Wady:

• Stosunkowo nowa specyfikacja (RFC 4122bis)
• Mniej obsługiwane w starszych systemach

Której wersji UUID użyć?

Przewodnik decyzyjny

Potrzebujesz maksymalnego bezpieczeństwa i losowości? → Użyj UUID v4 (najczęstszy wybór)

Potrzebujesz sortowania czasowego i wydajności DB? → Użyj UUID v7 (nowoczesne) lub UUID v6 (standard)

Potrzebujesz powtarzalnego UUID z istniejących identyfikatorów? → Użyj UUID v5 (SHA-1) lub UUID v3 (MD5, starsze)

Potrzebujesz znacznika czasu i śladu audytu? → Użyj UUID v1 (starsze, gorsza wydajność DB)

Bazy danych

Dla nowych projektów: UUID v7 lub v4

• v7 jest idealne do sortowania czasowego + wydajności
• v4 dla maksymalnej losowości bez informacji o czasie

Dla starszych systemów: UUID v1 lub v6

• v6 ma lepszą lokalizację DB niż v1
• v1 jest szeroko obsługiwane

Zalety UUID jako klucza głównego:

• Globalna unikalność – Możesz łączyć dane z różnych baz danych bez konfliktu
• Bezpieczeństwo – W przeciwieństwie do sekwencyjnych ID (1, 2, 3…) nie można odgadnąć kolejnych wartości
• Systemy rozproszone – UUID można generować niezależnie na wielu serwerach bez koordynacji
• Łączenie baz danych – Podczas scalania dwóch baz danych nie powstają konflikty

Wady:

• Większy rozmiar (16 bajtów vs 4-8 bajtów dla liczb całkowitych)
• Wolniejsze indeksowanie w niektórych bazach danych (używaj v6/v7 dla lepszej wydajności)
• Mniej czytelne dla człowieka

API i usługi webowe

• REST API – Unikalne identyfikatory dla zasobów
• GraphQL – Globalne identyfikatory dla węzłów
• Webhooki – Śledzenie żądań i odpowiedzi
• Tokeny – Identyfikatory sesji, tokeny odświeżania

Pliki i przechowywanie

• Nazwy plików – Zapobieganie kolizjom podczas przesyłania
• S3/Cloud Storage – Unikalne ścieżki do obiektów
• Klucze pamięci podręcznej – Identyfikatory w systemach pamięci podręcznej

Aplikacje frontendowe

• Komponenty React/Vue – Unikalne klucze dla list
• Tymczasowe ID – ID przed zapisaniem do bazy danych
• Pamięć lokalna – Klucze dla zapisanych danych
• Aplikacje offline-first – Generowanie ID bez połączenia z serwerem

Zaawansowane funkcje generatora

Generowanie UUID z niestandardowym czasem

Dla wersji opartych na czasie (v1, v6, v7) możesz wybrać dowolny znacznik czasu za pomocą selektora daty i godziny. Jest to przydatne do:

Testowanie:

• Symulacja UUID utworzonych w przeszłości
• Testowanie sortowania czasowego w bazach danych
• Reprodukcja UUID do debugowania

Migracja danych:

• Generowanie UUID z historycznymi znacznikami czasu
• Uzupełnianie danych z poprawnymi wartościami znacznika czasu
• Import danych z różnych okresów czasu

Audyt i zgodność:

• Rekonstrukcja UUID według czasu powstania rekordu
• Retroaktywne generowanie identyfikatorów

Przykład użycia:

1. Wybierz wersję v1, v6 lub v7
2. Ustaw datę i godzinę za pomocą selektora daty i godziny
3. Wygeneruj UUID z własnym znacznikiem czasu

Hash-based UUID (v3, v5)

Dla deterministycznych UUID możesz użyć wersji v3 (MD5) lub v5 (SHA-1):

Jak używać:

1. Wybierz przestrzeń nazw według typu swojego identyfikatora
2. Wprowadź nazwę/wartość
3. Wygeneruj UUID

Przykłady:

Ważne cechy:

• ✅ Deterministyczne: To samo wejście = zawsze to samo UUID
• ✅ Powtarzalne: Możesz ponownie utworzyć UUID w dowolnym momencie
• ✅ Spójne: To samo UUID w różnych systemach
• ❌ Nie można dekodować: Z UUID nie można odzyskać oryginalnej nazwy
• ℹ️ Jedno UUID: Dla v3/v5 zawsze generuje się tylko jedno UUID (to samo wejście = ten sam wynik)

Praktyczne zastosowanie:

// Przykład: Konwersja URL na UUID v5
Namespace: URL
Název: https://example.com/api/users/123
Výsledek: 886313e1-3b8a-5372-9b90-0c9aee199e5d

// Stejný vstup = zawsze stejné UUID
Namespace: DNS
Název: google.com
Výsledek: zawsze stejné UUID pro google.com

Jak bezpiecznie używać UUID?

Bezpieczeństwo kryptograficzne

Nasz generator używa crypto.getRandomValues(), który jest kryptograficznie bezpiecznym generatorem liczb losowych. W przeciwieństwie do Math.random(), który jest przewidywalny i nieodpowiedni do celów bezpieczeństwa, crypto.getRandomValues() zapewnia prawdziwą entropię odpowiednią do:

• Generowania tokenów bezpieczeństwa
• Identyfikatorów sesji
• Kluczy API
• Aplikacji kryptograficznych

Porównanie wersji UUID

UUID a inne identyfikatory

Implementacja w różnych językach

JavaScript/TypeScript

// UUID v4 - Najprostszy sposób (nowoczesne przeglądarki)
const uuid = crypto.randomUUID();

// UUID v4 - Implementacja ręczna
function generateUUIDv4() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
    const r = (crypto.getRandomValues(new Uint8Array(1))[0] & 0x0f) >> (c === 'x' ? 0 : 2);
    const v = c === 'x' ? r : (r & 0x3) | 0x8;
    return v.toString(16);
  });
}

// UUID v7 - Zalecane dla baz danych
function generateUUIDv7() {
  const timestamp = Date.now();
  const timeHi = (timestamp >> 16).toString(16).padStart(8, '0');
  const timeLow = (timestamp & 0xFFFF).toString(16).padStart(4, '0');

  const randomBytes = crypto.getRandomValues(new Uint8Array(10));
  const randomHex = Array.from(randomBytes)
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');

  return `${timeHi}-${timeLow}-7${randomHex.substr(0, 3)}-${randomHex.substr(3, 4)}-${randomHex.substr(7)}`;
}

Python

import uuid

# UUID v4
uuid_v4 = str(uuid.uuid4())
# Output: '6ba7b810-9dad-11d1-80b4-00c04fd430c8'

# UUID v1
uuid_v1 = str(uuid.uuid1())

Java

import java.util.UUID;

// UUID v4
String uuidV4 = UUID.randomUUID().toString();

PHP

// UUID v4 (PHP 7+)
function generateUUID() {
    return sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
        mt_rand(0, 0xffff), mt_rand(0, 0xffff),
        mt_rand(0, 0xffff),
        mt_rand(0, 0x0fff) | 0x4000,
        mt_rand(0, 0x3fff) | 0x8000,
        mt_rand(0, 0xffff), mt_rand(0, 0xffff), mt_rand(0, 0xffff)
    );
}

C#

using System;

// UUID v4
Guid uuid = Guid.NewGuid();
string uuidString = uuid.ToString();

Najlepsze praktyki

Zapisywanie UUID w bazie danych

PostgreSQL:

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

MySQL 8.0+:

CREATE TABLE users (
    id BINARY(16) PRIMARY KEY DEFAULT (UUID_TO_BIN(UUID())),
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Wskazówka: W MySQL przechowuj UUID jako BINARY(16) zamiast CHAR(36), aby zaoszczędzić miejsce i przyspieszyć indeksowanie.

Walidacja UUID

function isValidUUID(uuid) {
  const regex = /^[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 regex.test(uuid);
}

Konwersja UUID

// Usunięcie myślników
const compact = uuid.replace(/-/g, '');

// Dodanie myślników z powrotem
function formatUUID(compactUuid) {
  return [
    compactUuid.substring(0, 8),
    compactUuid.substring(8, 12),
    compactUuid.substring(12, 16),
    compactUuid.substring(16, 20),
    compactUuid.substring(20, 32)
  ].join('-');
}

Rozwiązywanie problemów (Troubleshooting)

UUID v3/v5 nie działa

Problem: Po wybraniu v3 lub v5 nic się nie generuje

Rozwiązanie:

1. ✅ Sprawdź, czy wypełniłeś pole “Nazwa” - jest ono obowiązkowe!
2. ✅ Wybierz odpowiednią przestrzeń nazw według typu swojego wejścia
3. ✅ Przykłady prawidłowych wejść:
   • DNS: example.com, google.com
   • URL: https://example.com/page
   • Dowolny tekst: moja-aplikacja-v1

Wskazówka: Spróbuj najpierw prostej wartości, np. test i przestrzeń nazw DNS.

Czasowe UUID (v1, v6, v7) ma dziwny czas

Problem: Wygenerowane UUID ma nieoczekiwany znacznik czasu

Rozwiązanie:

1. ✅ Sprawdź selektor daty i godziny - czy ustawiono prawidłowy czas?
2. ✅ Selektor daty i godziny używa Twojej lokalnej strefy czasowej
3. ✅ Pozostaw selektor daty i godziny pusty, aby użyć aktualnego czasu

UUID nie można skopiować

Problem: Przycisk “Kopiuj wszystko” nie działa

Rozwiązanie:

1. ✅ Sprawdź, czy wygenerowałeś UUID (nie są puste)
2. ✅ Niektóre przeglądarki wymagają HTTPS dla API schowka
3. ✅ Alternatywnie wybierz tekst w polu tekstowym i skopiuj ręcznie (Ctrl+C)

Często zadawane pytania (FAQ)

Alternatywy dla UUID

ULID (Universally Unique Lexicographically Sortable Identifier)

• 128-bitowy identyfikator (tak samo jak UUID)
• Sortowalny leksykograficznie według czasu utworzenia
• Bardziej kompaktowa reprezentacja (26 znaków zamiast 36)
• Kodowanie base32 bez rozróżniania wielkości liter

Przykład: 01ARZ3NDEKTSV4RRFFQ69G5FAV

NanoID

• Mniejszy rozmiar niż UUID (standardowo 21 znaków)
• Przyjazny dla URL (bez znaków specjalnych)
• Szybsze generowanie
• Konfigurowalna długość i alfabet

Przykład: V1StGXR8_Z5jdHi6B-myT

Snowflake ID (Twitter)

• 64-bitowy identyfikator (mniejszy niż UUID)
• Sortowalny czasowo
• Zawiera ID pracownika i numer sekwencyjny
• Wymaga scentralizowanej konfiguracji

Przykład: 1234567890123456789

Wydajność i optymalizacja

Szybkość generowania

Nasz generator potrafi wygenerować:

• 1 UUID: < 1 ms
• 100 UUID: ~10-20 ms
• 1000 UUID: ~100-200 ms

Wskazówki dotyczące wydajności

1. Generowanie wsadowe – Jeśli potrzebujesz wielu UUID, generuj je jednocześnie zamiast pojedynczo
2. Zapisywanie w DB – Indeksuj kolumny UUID dla szybkiego wyszukiwania
3. Kompresja – Przechowuj UUID w formie binarnej (16 bajtów) zamiast ciągu (36 bajtów)
4. Buforowanie – W niektórych przypadkach możesz wstępnie wygenerować i buforować UUID

Dla programistów

Struktura UUID v4

xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
|        |    |    |    |
|        |    |    |    └─ 48 bitów losowych danych (node)
|        |    |    └────── 16 bitów losowych danych z wariantem (clock_seq)
|        |    └─────────── 12 bitów losowych danych + 4 bity wersji (time_hi_and_version)
|        └──────────────── 16 bitów losowych danych (time_mid)
└───────────────────────── 32 bity losowych danych (time_low)

• Wersja (4 bity): zawsze 0100 (binarnie) = 4 (szesnastkowo)
• Wariant (2-3 bity): zawsze 10 (binarnie) dla RFC 4122

Testowanie UUID

// Test Jest
describe('UUID Generator', () => {
  test('generates valid UUID v4', () => {
    const uuid = generateUUIDv4();
    const regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
    expect(regex.test(uuid)).toBe(true);
  });

  test('generates unique UUIDs', () => {
    const uuid1 = generateUUIDv4();
    const uuid2 = generateUUIDv4();
    expect(uuid1).not.toBe(uuid2);
  });
});

Aspekty bezpieczeństwa

Czego nie robić z UUID

❌ Nie używaj UUID v1 do wrażliwych aplikacji – Zawiera znacznik czasu, co może stanowić ryzyko bezpieczeństwa

❌ Nie używaj Math.random() do generowania UUID – Nie jest kryptograficznie bezpieczny

❌ Nie polegaj na UUID do autoryzacji – UUID można odgadnąć (choć z ekstremalnie małym prawdopodobieństwem)

❌ Nie przechowuj UUID w ciasteczkach bez szyfrowania – Użyj podpisanych ciasteczek lub JWT

Co robić

✅ Używaj UUID v4 w większości przypadków – Najwyższa entropia i bezpieczeństwo

✅ Łącz UUID z innymi środkami bezpieczeństwa – Do zarządzania sesjami użyj HTTPS, ciasteczek HttpOnly i krótkiej daty ważności

✅ Waliduj UUID na serwerze – Zawsze sprawdzaj format i wersję UUID

✅ Używaj kryptograficznie bezpiecznych źródeł losowości – crypto.getRandomValues() w przeglądarce, /dev/urandom w systemie Linux

Ciekawostki

• Liczba możliwych UUID v4: 2^122 ≈ 5.3 × 10^36 (340 undecillionów)
• Potrzebna kolizja: Aby uzyskać 50% szansy na kolizję, musisz wygenerować 2.71 × 10^18 UUID (2.71 kwintylionów)
• Rozmiar wszystkich możliwych UUID: Gdybyśmy każde UUID przechowywali jako 16 bajtów, cała przestrzeń zajęłaby 85 zettabajtów (85 miliardów terabajtów)
• Pochodzenie: UUID zostało zestandaryzowane jako część DCE (Distributed Computing Environment) w 1990 roku