TypeScript Academy · Lezione

Gestire unknown in modo type-safe

Restringa i valori unknown prima di utilizzarli in sicurezza.

Lezione 4 di 413 passaggi

Gestire unknown in modo type-safe è una lezione TypeScript Academy gratuita su CoddyKit. Questa è la lezione 4 di 4. 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 4 lezioni in totale.

Lavorare in sicurezza con unknown

Tipizzare i dati esterni come unknown è solo metà del lavoro. L'altra metà consiste nel restringerli a un tipo concreto prima di utilizzarli. In questa lezione esamineremo le principali tecniche di restringimento del tipo.

function describe(v: unknown): string {
  if (typeof v === 'string') return 'string: ' + v;
  if (typeof v === 'number') return 'number: ' + v;
  return 'other';
}
console.log(describe('hi'), describe(7), describe(true));

Restringere il tipo con typeof

Il controllo con typeof è lo strumento più semplice. Restringe unknown ai tipi primitivi: string, number, boolean, function, object e altri.

function double(v: unknown): number {
  if (typeof v === 'number') {
    return v * 2; // v is number here
  }
  return 0;
}
console.log(double(21), double('no'));

Restringere il tipo con instanceof

Per le istanze di classe, utilizzi instanceof. Restringe unknown alla classe specifica, consentendo di usare in sicurezza i relativi metodi e proprietà.

function handle(v: unknown): string {
  if (v instanceof Date) {
    return v.toISOString(); // v is Date
  }
  return 'not a date';
}
console.log(handle(new Date(0)));

Restringere il tipo con l'operatore in

L'operatore in verifica se una proprietà esiste in un oggetto, restringendo i valori tipizzati come oggetti. Prima verifichi che il valore sia un oggetto non nullo, quindi esamini le sue chiavi.

function getName(v: unknown): string {
  if (typeof v === 'object' && v !== null && 'name' in v) {
    return String((v as { name: unknown }).name);
  }
  return 'anonymous';
}
console.log(getName({ name: 'Ada' }), getName(5));

Type guard personalizzate

Una type guard personalizzata è una funzione il cui tipo di ritorno è value is T. Quando restituisce true, TypeScript restringe l'argomento a T nel punto della chiamata.

function isString(v: unknown): v is string {
  return typeof v === 'string';
}

function shout(v: unknown): string {
  return isString(v) ? v.toUpperCase() : '?';
}
console.log(shout('hey'), shout(9));

Type guard per la struttura degli oggetti

Le type guard personalizzate sono particolarmente efficaci per convalidare la struttura degli oggetti. Scriva una funzione che controlli tutti i campi obbligatori, così il resto del codice potrà usare con sicurezza il tipo ristretto.

type User = { id: number; name: string };

function isUser(v: unknown): v is User {
  return typeof v === 'object' && v !== null &&
    'id' in v && 'name' in v;
}
console.log(isUser({ id: 1, name: 'Sam' }), isUser({}));

JSON.parse restituisce dati simili a unknown

JSON.parse è tipizzato per restituire any, aggirando silenziosamente la sicurezza dei tipi. Una buona pratica consiste nel catturare il risultato come unknown e convalidarlo prima di considerare affidabile la sua struttura.

function parseConfig(text: string): unknown {
  return JSON.parse(text);
}
const raw = parseConfig('{"port":8080}');
console.log(typeof raw);

Convalidare il JSON analizzato

Combini JSON.parse con una type guard per trasformare in sicurezza testo non attendibile in un valore tipizzato. Se la convalida non riesce, gestisca l'errore invece di considerare attendibili dati non validi.

type Config = { port: number };

function isConfig(v: unknown): v is Config {
  return typeof v === 'object' && v !== null &&
    'port' in v && typeof (v as any).port === 'number';
}

const data: unknown = JSON.parse('{"port":8080}');
if (isConfig(data)) console.log('Port:', data.port);

Concatenare più type guard

Per gli input complessi, applichi più type guard in sequenza: controlli prima la struttura generale, quindi la perfezioni. Ogni controllo restringe ulteriormente il tipo, producendo passo dopo passo tipi precisi e sicuri.

function process(v: unknown): string {
  if (Array.isArray(v)) {
    if (v.every((x) => typeof x === 'string')) {
      return v.join('-');
    }
  }
  return 'invalid';
}
console.log(process(['a', 'b']), process([1, 2]));

Lanciare un'eccezione per dati non validi

Quando la convalida dei dati obbligatori non riesce, lanci un'eccezione. In combinazione con un helper di errore che restituisce never, questo mantiene chiaro e correttamente tipizzato il percorso previsto.

function asNumber(v: unknown): number {
  if (typeof v === 'number') return v;
  throw new Error('Expected a number');
}
console.log(asNumber(42));
try { asNumber('x'); } catch (e) { console.log('rejected'); }

Mettere tutto insieme

Lo schema completo è: ricevere i dati come unknown, restringerli con le type guard, quindi operare sul tipo preciso. Questo è il confine sicuro tra il mondo esterno non tipizzato e il codice tipizzato.

type Point = { x: number; y: number };
function isPoint(v: unknown): v is Point {
  return typeof v === 'object' && v !== null &&
    'x' in v && 'y' in v;
}
const input: unknown = { x: 1, y: 2 };
if (isPoint(input)) console.log(input.x + input.y);

Verifica rapida

Verifichi la sua comprensione della gestione sicura di unknown.

Rispondi nella lezione interattiva

Riepilogo: gestione di unknown

Ha imparato a restringere unknown con:

typeof per i primitivi e instanceof per le istanze di classe.
L'operatore in per le proprietà degli oggetti.
Type guard personalizzate che restituiscono value is T.
La convalida dei risultati di JSON.parse prima di considerarli attendibili.

Nel prossimo corso: asserzioni di tipo e cast.

function isNonEmpty(v: unknown): v is string {
  return typeof v === 'string' && v.length > 0;
}
console.log(isNonEmpty('hi'), isNonEmpty(''));

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

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Gestire unknown in modo type-safe» è gratuita?

Sì — il testo completo di «Gestire unknown in modo type-safe» è 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 4 lezioni in totale.

Cosa imparerò in «Gestire unknown in modo type-safe»?

Restringa i valori unknown prima di utilizzarli in sicurezza. 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 4 di 4.

Quanto tempo richiede la lezione «Gestire unknown in modo type-safe»?

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

← Torna a TypeScript Academy