DTO: formato esterno dei dati salvati

DTO significa:

Data Transfer Object

Nel nostro corso lo usiamo in modo semplice:

un DTO e la forma dei dati quando escono o entrano dal sistema

Per esempio:

• dati salvati in localStorage;
• dati letti da un file JSON;
• dati ricevuti da una API;
• dati inviati a una API.

Obiettivo

Alla fine devi saper distinguere:

• modello di dominio;
• DTO;
• perche non sempre coincidono;
• quando conviene introdurre una conversione.

Dominio

Il dominio usa parole del progetto:

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

Questo oggetto serve ai casi d’uso e alle regole.

DTO

Un DTO puo avere una forma diversa:

const strumentoDto = {
  id: "s-001",
  name: "Arduino Uno",
  category: "microcontrollers",
  status: "available",
};

Questa forma potrebbe arrivare da una API in inglese.

Oppure potremmo usarla in un file JSON gia esistente.

Il DTO non deve invadere tutto il codice.

Perche separare

Se usiamo direttamente il formato esterno ovunque, il dominio si adatta al mondo esterno.

Esempio:

if (strumento.status === "available") {
  // presta
}

Ora il dominio parla il linguaggio dell’API, non del laboratorio.

Nel nostro corso preferiamo:

if (strumento.stato === StatoStrumento.DISPONIBILE) {
  // presta
}

Il mapping si occupa della traduzione.

Quando il DTO e uguale al dominio

Nella prima versione possiamo salvare un DTO uguale al dominio:

const strumentoDto = {
  id: strumento.id,
  nome: strumento.nome,
  categoria: strumento.categoria,
  stato: strumento.stato,
};

Va bene.

Ma il fatto di chiamarlo DTO ci ricorda che e la forma salvata.

Se un domani cambia, sappiamo dove intervenire.

DTO di Strumento

Documento:

# StrumentoDTO

Campi:
- id
- nome
- categoria
- stato

Oppure, se vuoi simulare API:

# StrumentoDTO API

Campi:
- id
- name
- category
- status

Scegli una forma e dichiarala.

DTO di Prestito

const prestitoDto = {
  id: "p-001",
  strumentoId: "s-001",
  assegnatario: "Luca 3A",
  apertoIl: "2026-05-09",
  chiusoIl: null,
  stato: "aperto",
};

Anche qui la forma puo coincidere con il dominio, almeno all’inizio.

DTO non contiene comportamento

Un DTO non deve avere metodi di dominio.

Non scrivere:

const strumentoDto = {
  id: "s-001",
  nome: "Arduino Uno",
  puoEsserePrestato() {
    return this.stato === "disponibile";
  },
};

Il DTO trasporta dati.

Le regole stanno nel dominio.

Esercizio

Per Strumento e Prestito, compila:

# DTO

## Modello di dominio

## DTO salvato

## Campi uguali

## Campi diversi

## Chi trasforma da dominio a DTO

## Chi trasforma da DTO a dominio

Se per ora i campi sono uguali, scrivilo esplicitamente.

Cosa produrre

Alla fine della lezione devi avere:

• definizione di DTO nel README tecnico o negli appunti;
• forma StrumentoDTO;
• forma PrestitoDTO;
• nota su differenza tra dati e comportamento;
• scelta provvisoria sul formato salvato.

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 dTO: formato esterno dei dati salvati, 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 cosa significa DTO;
• so distinguere DTO e dominio;
• so che il DTO non contiene regole;
• so perche una API potrebbe avere nomi diversi;
• so dove serve una conversione.

Nella prossima lezione scriviamo il mapping.