Generator CUID

Czym jest CUID?

CUID (Collision-Resistant Unique Identifier) to otwartoźródłowy algorytm generowania unikalnych identyfikatorów, które dobrze działają w systemach rozproszonych bez centralnego koordynatora. W przeciwieństwie do zwykłego UUID, CUID jest zaprojektowany do poziomego skalowania — wiele serwerów lub kart przeglądarki może niezależnie generować identyfikatory z minimalnym ryzykiem kolizji.

Każdy CUID zaczyna się od małej litery c, co sprawia, że format jest natychmiast rozpoznawalny. Pozostałe znaki to małe litery alfanumeryczne (base36), więc CUID jest bezpieczny dla adresów URL i może być używany bezpośrednio jako segment ścieżki URL lub klucz główny bazy danych bez dodatkowego kodowania.

Oryginalna specyfikacja CUID (v1) została stworzona przez Erica Elliotta i spopularyzowana przez pakiet npm cuid. Została zastąpiona przez CUID v2, który zapewnia bezpieczeństwo kryptograficzne. Ta strona — i generator powyżej — generuje identyfikatory CUID v1, klasyczny format wciąż szeroko stosowany w produkcyjnych bazach kodu.

Struktura CUID

CUID v1 ma około 25 znaków i składa się z pięciu połączonych segmentów, z których każdy zawiera inny rodzaj entropii:

Segmenty są po prostu połączone — nie ma separatorów. Całkowita długość nieznacznie się różni w zależności od bieżącej wartości znacznika czasu, ale pozostaje na poziomie około 25 znaków.

Jak CUID Zapobiega Kolizjom

Odporność na kolizje wynika z nakładania niezależnych źródeł entropii, tak że nawet w scenariuszach najgorszego przypadku (tysiące identyfikatorów generowanych na milisekundę na wielu maszynach) prawdopodobieństwo dwóch identycznych identyfikatorów pozostaje znikomo małe.

CUID vs UUID v4

Zarówno CUID, jak i UUID v4 są szeroko stosowane do generowania identyfikatorów po stronie klienta. Podchodzą do tego samego problemu w różny sposób:

UUID v4 jest bezpieczniejszym wyborem dla scenariuszy wrażliwych na bezpieczeństwo, ponieważ nie ujawnia informacji o czasie. CUID ma przewagę, gdy chcesz identyfikatory, które są mniej więcej sortowalne, krótsze i bez myślników — przydatne do użycia w adresach URL, nazwach plików lub logach, gdzie chcesz szybko zidentyfikować, kiedy rekord został utworzony.

CUID v1 vs CUID2

Specyfikacja CUID została znacznie zrewidowana. Zrozumienie różnic pomaga wybrać właściwą wersję dla projektu:

Dla nowych projektów CUID v2 jest zalecanym wyborem. Jego konstrukcja oparta na SHA-3 oznacza, że wyjście jest nieprzejrzyste — żaden znacznik czasu, licznik ani odcisk palca nie może być odtworzony z identyfikatora. Używaj CUID v1 tylko wtedy, gdy potrzebujesz wstecznej kompatybilności z istniejącym zestawem danych lub chcesz implementacji bez zależności.

Przypadki Użycia

Przykłady Kodu

Zainstaluj oficjalny pakiet CUID v2 (zalecany) lub napisz minimalną implementację v1 bez zależności:

// npm install @paralleldrive/cuid2  (recommended — CUID v2)
import { createId } from '@paralleldrive/cuid2'

const id = createId()
// → 'tz4a98xxat96iws9zmbrgj3a'

// Custom length
import { init } from '@paralleldrive/cuid2'
const createShortId = init({ length: 10 })
createShortId() // → 'zxp1l6mf4c'

Jeśli wolisz implementację Node.js bez zależności algorytmu v1:

// Pure Node.js — CUID v1 style (no dependencies)
let counter = 0

function pad(str, size) {
  return str.padStart(size, '0').slice(-size)
}

function fingerprint() {
  const os = require('os')
  const source = [process.pid, os.hostname().length].join('')
  let hash = 0
  for (const c of source) {
    hash = ((hash << 5) - hash) + c.charCodeAt(0)
    hash |= 0
  }
  return pad(Math.abs(hash).toString(36), 4)
}

function cuid() {
  const timestamp = Date.now().toString(36)
  const cnt       = pad((counter++ & 0xffff).toString(36), 4)
  const fp        = fingerprint()
  const rnd       = pad(Math.floor(Math.random() * 0xffffffff).toString(36), 4)
              + pad(Math.floor(Math.random() * 0xffffffff).toString(36), 4)
  return 'c' + timestamp + cnt + fp + rnd
}

console.log(cuid()) // → 'clrc4gkwz001ag2hs3k7f9m2q'

Używanie CUID jako klucza głównego bazy danych z Prisma i PostgreSQL:

-- Use CUID as a primary key in PostgreSQL
CREATE TABLE users (
  id   TEXT        PRIMARY KEY DEFAULT gen_cuid(),
  name TEXT        NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- Prisma schema (auto-generates CUID by default)
model User {
  id        String   @id @default(cuid())
  name      String
  createdAt DateTime @default(now())
}

Często Zadawane Pytania