Dekoder UUID

Struktura UUID

UUID (Universally Unique Identifier) to 128-bitowa wartość reprezentowana jako 32 cyfry szesnastkowe podzielone na pięć grup przez myślniki:

Wersja i wariant to jedyne dwa pola gwarantowane w każdym UUID. Wszystkie pozostałe pola zależą od wersji.

Pole wersji

Nibble wersji to pierwsza cyfra szesnastkowa trzeciej grupy (pozycja 14 w pełnym ciągu). Identyfikuje, która wersja UUID została użyta do wygenerowania identyfikatora.

const hex = uuid.replace(/-/g, '')
const version = parseInt(hex[12], 16)  // single hex digit → 1, 2, 3, 4, 5, 6, 7, or 8

Wersja 7 (UUID v7) to najnowsza szeroko używana wersja, wprowadzona w RFC 9562 (2024). Koduje uniksowy znacznik czasu w milisekundach w wysokich bitach dla sortowalności.

Pole wariantu

Wariant jest kodowany w wysokich bitach pierwszego bajtu czwartej grupy. Identyfikuje konwencje układu i kolejności bajtów używane przez UUID.

W praktyce niemal wszystkie UUID, które napotkasz, używają wariantu RFC 4122 / RFC 9562 (wzorzec bitów 10xx xxxx, pierwszy bajt czwartej grupy w zakresie 0x80–0xBF). Warianty NCS, Microsoft COM i Reserved to starsze formaty rzadko spotykane w nowoczesnych systemach.

Tabela wersji UUID

RFC 4122 zdefiniował wersje 1–5. RFC 9562 (2024) dodał wersje 6, 7 i 8:

Dekodowanie znaczników czasu UUID v1

UUID v1 osadza 60-bitowy znacznik czasu gregoriański (interwały 100-nanosekundowe od 15 października 1582) podzielony na trzy pola: time_low (bity 0–31), time_mid (bity 32–47) i time_hi (bity 48–59). To narzędzie składa je ponownie i konwertuje do standardowej daty UTC.

// UUID v1: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
//           ^^^^^^^^ ^^^^ ^^^^ ^^^^^ ^^^^^^^^^^^^
//           time-low  mid  hi  clk   node (MAC)
//                          ^
//                          version nibble (1)

const hex = '6ba7b8109dad11d180b400c04fd430c8'

const tLow = parseInt(hex.slice(0, 8),  16)  // 0x6ba7b810
const tMid = parseInt(hex.slice(8, 12), 16)  // 0x9dad
const tHi  = parseInt(hex.slice(13, 16), 16) // 0x1d1 (skip version nibble at index 12)

// Reconstruct 60-bit timestamp (100-ns intervals since Oct 15, 1582)
const t = (BigInt(tHi) << 48n) | (BigInt(tMid) << 32n) | BigInt(tLow)

// Subtract Gregorian offset (Oct 15, 1582 → Jan 1, 1970 in 100-ns units)
const GREGORIAN_OFFSET = 122192928000000000n
const unixMs = (t - GREGORIAN_OFFSET) / 10000n

console.log(new Date(Number(unixMs)).toISOString())
// → 1998-02-04T22:13:53.578Z

UUID v1 powinien być traktowany jako wrażliwy: osadzony adres MAC i precyzyjny znacznik czasu mogą zidentyfikować zarówno generującą maszynę, jak i czas generowania.

Dekodowanie znaczników czasu UUID v7

UUID v7 osadza 48-bitowy uniksowy znacznik czasu w milisekundach w pierwszych 48 bitach (pierwsza grupa + pierwsze 4 cyfry drugiej grupy). To narzędzie odczytuje te bity i konwertuje je do daty UTC z precyzją do milisekund.

// UUID v7: 018e4bc8-1000-7000-8000-000000000001
//           ^^^^^^^^^^^^
//           48-bit Unix ms timestamp

const hex = '018e4bc8100070008000000000000001'

// First 48 bits (12 hex chars) = Unix timestamp in milliseconds
const ms = parseInt(hex.slice(0, 12), 16)  // 0x018e4bc81000

console.log(new Date(ms).toISOString())
// → 2024-03-11T…Z

// Everything after byte 6 is random (except version/variant bits)

W przeciwieństwie do UUID v1, znacznik czasu UUID v7 używa znajomej epoki uniksowej (1 stycznia 1970) i nie osadza żadnych informacji o hoście. Pozostałe 74 bity są losowe.

Jak to narzędzie wykrywa wersję i wariant UUID

Dekoder odczytuje pozycję 14 (nibble wersji) i pozycję 19 (nibble wariantu) kanonicznego ciągu UUID. Nie jest potrzebny żaden zewnętrzny stan ani kontekst — wszystkie informacje są zawarte w ciągu UUID.

// Detect UUID version from the 13th hex character (index 12)
function uuidVersion(uuid) {
  const clean = uuid.replace(/-/g, '')
  return parseInt(clean[12], 16)
}

uuidVersion('550e8400-e29b-41d4-a716-446655440000') // → 4
uuidVersion('018e4bc8-1000-7000-8000-000000000001') // → 7
uuidVersion('6ba7b810-9dad-11d1-80b4-00c04fd430c8') // → 1

// Detect variant from the 17th hex character (index 16, first char of 4th group)
function uuidVariant(uuid) {
  const clean = uuid.replace(/-/g, '')
  const b = parseInt(clean[16], 16)
  if ((b & 0x8) === 0)      return 'NCS'
  if ((b & 0xC) === 0x8)    return 'RFC 4122'
  if ((b & 0xE) === 0xC)    return 'Microsoft'
  return 'Reserved'
}

Specjalne UUID

Nil UUID

Nil UUID 00000000-0000-0000-0000-000000000000 to same zera. Jest zdefiniowany przez RFC 4122 jako wartość wartownicza oznaczająca 'brak UUID' — analogiczna do null. Nie jest prawidłowym wygenerowanym UUID.

Max UUID

Max UUID ffffffff-ffff-ffff-ffff-ffffffffffff to same jedynki (0xFF w każdym bajcie). Zdefiniowany w RFC 9562, jest dopełnieniem nil UUID i służy jako maksymalna wartość wartownicza.

Często zadawane pytania