Da oggetti di dominio a dati serializzabili

Il dominio parla di concetti:

• strumento;
• prestito;
• stato;
• regola;
• errore.

localStorage e JSON parlano di dati serializzabili.

Questa differenza sembra piccola, ma e importante.

Quando salviamo, dobbiamo trasformare oggetti del nostro programma in dati che possono essere scritti come stringa.

Obiettivo

Alla fine devi capire:

• che cosa significa serializzare;
• perche localStorage salva stringhe;
• quali dati del dominio possono essere salvati direttamente;
• quali dati richiedono attenzione;
• perche introdurremo DTO e mapping.

Che cosa significa serializzare

Serializzare significa trasformare un dato in un formato salvabile o trasmissibile.

Nel browser, con JSON:

const testo = JSON.stringify(strumento);

Deserializzare significa fare il percorso inverso:

const strumento = JSON.parse(testo);

Il risultato di JSON.parse e un oggetto semplice.

Non e automaticamente un oggetto di dominio valido.

localStorage salva stringhe

Questo non funziona come molti pensano:

localStorage.setItem("strumento", strumento);

Perche localStorage salva stringhe.

Bisogna scrivere:

localStorage.setItem("strumento", JSON.stringify(strumento));

E leggere:

const strumento = JSON.parse(localStorage.getItem("strumento"));

Questo codice deve stare in Infrastructure.

Oggetto di dominio semplice

Nel nostro corso i modelli sono spesso oggetti semplici:

const strumento = {
  id: "s-001",
  nome: "Arduino Uno",
  categoria: "microcontrollori",
  stato: "disponibile",
};

Questo oggetto si serializza facilmente.

Ma non significa che tutto vada salvato senza controllo.

Il problema dei dati letti

Quando leggo da localStorage potrei trovare:

{
  id: "s-001",
  nome: "",
  categoria: null,
  stato: "rotto"
}

Oppure:

testo non JSON

Oppure dati vecchi:

{
  id: "s-001",
  label: "Arduino Uno",
  type: "microcontrollori"
}

Il fatto che un dato sia salvato non significa che sia valido per il dominio.

Dato salvato e dominio

Per questo distinguiamo:

dato salvato
oggetto di dominio

Il dato salvato e la forma esterna.

L’oggetto di dominio e la forma che il resto dell’applicazione vuole usare.

Tra le due forme puo esserci una trasformazione.

Esempio

Dato salvato:

{
  id: "s-001",
  name: "Arduino Uno",
  category: "microcontrollori",
  status: "available"
}

Dominio:

{
  id: "s-001",
  nome: "Arduino Uno",
  categoria: "microcontrollori",
  stato: "disponibile"
}

Non sono uguali.

Serve mapping.

Quando sono uguali

Nella prima versione possiamo scegliere di salvare dati molto simili al dominio:

{
  id: "s-001",
  nome: "Arduino Uno",
  categoria: "microcontrollori",
  stato: "disponibile"
}

Va bene.

Pero e utile sapere che stiamo facendo una scelta.

Se in futuro cambia il formato salvato, non vogliamo rompere tutto il dominio.

Regola pratica

Quando salvi:

dominio -> dato serializzabile -> JSON string

Quando leggi:

JSON string -> dato serializzabile -> dominio

Infrastructure gestisce questa trasformazione.

Esercizio

Prendi un oggetto Strumento e scrivi:

# Strumento

## Forma dominio

## Forma JSON salvata

## Campi uguali

## Campi che potrebbero cambiare in futuro

## Rischi quando leggo il dato

Poi fai lo stesso con Prestito.

Cosa produrre

Alla fine della lezione devi avere:

• una spiegazione di serializzazione;
• esempi di dominio e dato salvato;
• lista dei rischi nella lettura da localStorage;
• nota sul perche serve mapping;
• scelta provvisoria sul formato JSON.

Spiegazione guidata per studiare

Questa lezione va studiata su due piani. Il primo è il comportamento visibile del Registro del laboratorio: che cosa vede o fa l’utente quando registra uno strumento, cerca un dispositivo, apre un prestito o segnala un guasto. Il secondo è il confine architetturale: dove deve stare il codice che rende possibile quel comportamento.

Per da oggetti di dominio a dati serializzabili, il punto centrale è questo: L’infrastruttura è il bordo tecnico: salva, legge, chiama API, usa localStorage o file JSON. È importante, ma deve restare sostituibile.

Il rischio tipico è far entrare il formato salvato dentro il dominio. Un oggetto comodo per localStorage non è automaticamente il modello con cui ragiona il progetto. Per evitarlo, non partire dal file che hai già aperto nell’editor. Parti dalla domanda: “quale responsabilità sto modificando?”. Se la risposta riguarda una regola del laboratorio, guarda il dominio. Se riguarda una sequenza di operazioni, guarda i casi d’uso. Se riguarda salvataggio, file, localStorage, API o database, guarda l’infrastruttura. Se riguarda input, pulsanti, form e messaggi, guarda la Presentation.

Il tempo è sufficiente per alternare spiegazione, modifica guidata e revisione. Alla fine della lezione lo studente non deve ricordare una definizione a memoria: deve saper indicare un punto del progetto, spiegare perché quel codice sta lì e mostrare una verifica del comportamento.

Passo per passo nel progetto

1. Rileggi il titolo della lezione e riscrivilo come domanda pratica. Per esempio: “dove deve stare questa regola?”, “chi deve salvare questo dato?”, “come verifico questo errore?”.
2. Apri solo i file necessari. Se devi toccare più di tre file, fermati e scrivi prima una mini-mappa.
3. Distingui modello di dominio e formato salvato.
4. Crea una funzione di mapping leggibile.
5. Gestisci dati mancanti o non validi.
6. Verifica che i casi d’uso non cambino quando cambi archivio.
7. Aggiorna una nota breve nel README o negli appunti se hai cambiato un confine del progetto.

Esempio da leggere lentamente

Questo esempio serve a ragionare, non a incollare codice senza capire:

function strumentoToDTO(strumento) {
  return {
    id: strumento.id,
    name: strumento.nome,
    category: strumento.categoria,
    status: strumento.stato
  };
}

Leggilo chiedendoti che cosa cambierebbe se domani sostituissimo la pagina web con una CLI, oppure localStorage con un’API. Se l’esempio continua ad avere senso senza riscrivere tutto, il confine è probabilmente buono. Se invece un dettaglio tecnico si propaga in molti file, il progetto sta tornando fragile.

Prova di comprensione

Prima di chiudere la lezione, rispondi per iscritto a queste domande:

• Qual è la responsabilità principale trattata in questa lezione?
• In quale livello del progetto dovrebbe stare?
• Quale errore faresti se cercassi la soluzione più veloce?
• Quale piccolo test, controllo manuale o esempio dimostra che hai capito?
• Che cosa deve restare facile da cambiare dopo questa lezione?

Una risposta accettabile non deve essere lunga. Deve però usare parole concrete del Registro: strumento, prestito, stato, archivio, caso d’uso, messaggio, test.

Controllo finale

La lezione e completata quando puoi rispondere si:

• so che localStorage salva stringhe;
• so usare JSON.stringify e JSON.parse;
• so che un dato letto non e automaticamente valido;
• so distinguere dato salvato e oggetto di dominio;
• so perche DTO e mapping saranno utili.

Nella prossima lezione salviamo e leggiamo strumenti da localStorage.