TypeScript Academy · Lezione

Tipi brandizzati/opachi per evitare scambi tra unità

Prevenga gli scambi tra unità o tag intersecando i tipi di base con proprietà brand fantasma; costruisca i valori esclusivamente tramite funzioni factory.

Lezione 1 di 38 passaggi

Tipi brandizzati/opachi per evitare scambi tra unità è una lezione TypeScript Academy gratuita su CoddyKit. Questa è la lezione 1 di 3. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento TypeScript Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso TypeScript Academy include 3 lezioni in totale.

Introduzione

Obiettivo: separare a livello di tipo valori dall'aspetto simile. Un semplice number non distingue i metri dai secondi; un marcatore brand può farlo.

  • Nessun sovraccarico a runtime
  • API e refactoring più sicuri
  • Creazione esclusivamente tramite factory

Marcare le unità primitive

I marcatori Brand mantengono separate le unità in fase di compilazione; un ordine errato degli argomenti fallisce il controllo dei tipi.

type Meter = number & { readonly __brand: "meter" }
type Second = number & { readonly __brand: "second" }

function meter(n: number): Meter { return n as Meter }
function second(n: number): Second { return n as Second }

const d = meter(100)
const t = second(9)

function speed(dist: Meter, time: Second) { return (dist as number) / (time as number) }

// speed(t, d)  // compile error: brands do not match

Helper generico per i brand

Usi un helper generico Brand in tutti i domini: ID tipizzati, token, cursori e così via.

type Brand<Tag extends string, T> = T & { readonly __brand: Tag }

type UserId = Brand<"UserId", string>
type OrderId = Brand<"OrderId", string>

function userId(x: string): UserId { return x as UserId }
function orderId(x: string): OrderId { return x as OrderId }

function findUser(id: UserId) { /* ... */ }

const u = userId("u_123")
const o = orderId("o_456")
// findUser(o) // error: OrderId not assignable to UserId

Brand con unique symbol

Il brand unique symbol evita le collisioni tra nomi e l'inquinamento dei namespace globali.

declare const MeterSym: unique symbol

type Meter2 = number & { readonly [MeterSym]: "meter" }

function asMeter2(n: number): Meter2 { return n as Meter2 }

const m2 = asMeter2(5)
// const wrong: Meter2 = 5  // discourage raw assignment; prefer factories

Factory e validazione

Inserisca il brand all'interno di una factory: prima esegua la validazione, poi applichi il brand e infine utilizzi il valore. Eviti gli as ad hoc nei punti di chiamata.

type NonEmptyString = string & { readonly __brand: "NonEmpty" }

function nonEmpty(s: string): NonEmptyString | null {
  return s.trim().length > 0 ? (s as NonEmptyString) : null
}

function makeSlug(s: NonEmptyString) {
  return (s as string).toLowerCase().replace(/\s+/g, "-")
}

const ok = nonEmpty(" Hello ")
if (ok) { makeSlug(ok) }  // safe: validated & branded first

Suggerimenti e insidie

Buone pratiche:

  • Mantenga i nomi dei brand brevi e significativi.
  • Renda disponibili le factory come unico modo per ottenere valori brandizzati.
  • Non esponga i brand nei tipi delle API pubbliche, se non è necessario.
  • I brand esistono solo a livello di tipo: nessun overhead a runtime.

Verifica del branding

Verifica rapida: quale pattern evita di confondere unità e tag?

Riepilogo

Riepilogo: i tipi branded/opaque separano valori dall'aspetto uguale (metri e secondi, UserId e OrderId). Li produca tramite factory, li utilizzi nelle API ed elimini le confusioni accidentali.

Gratis per iniziare

Impara TypeScript con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi
101
Lezioni
352

Domande Frequenti

La lezione «Tipi brandizzati/opachi per evitare scambi tra unità» è gratuita?

Sì — il testo completo di «Tipi brandizzati/opachi per evitare scambi tra unità» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso TypeScript Academy, passa a CoddyKit PRO. Il corso TypeScript Academy include 3 lezioni in totale.

Cosa imparerò in «Tipi brandizzati/opachi per evitare scambi tra unità»?

Prevenga gli scambi tra unità o tag intersecando i tipi di base con proprietà brand fantasma; costruisca i valori esclusivamente tramite funzioni factory. Eserciti TypeScript Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare TypeScript Academy?

Non è richiesta alcuna esperienza precedente. TypeScript Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 3.

Quanto tempo richiede la lezione «Tipi brandizzati/opachi per evitare scambi tra unità»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione TypeScript Academy?

Sì. Ogni lezione TypeScript Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Tipi brandizzati/opachi per evitare scambi tra unità
  2. ID con tag e pattern di modellazione del dominio
  3. Modellazione del dominio — aggregati, invarianti e servizi
← Torna a TypeScript Academy