Runtime

La validazione a runtime conferma se le decisioni di dominio e API si comportano come previsto sotto un utilizzo reale delle query. È il livello in cui il Tuo modello passa dal design all'esecuzione — e dove individui i problemi prima che lo facciano i Tuoi consumatori.

Scopo del runtime

Il runtime risponde a domande pratiche nelle fasi iniziali del Tuo processo di sviluppo:

• Le strutture dei campi sono prevedibili e coerenti?
• I lookup delle relazioni sono coerenti e correttamente annidati?
• Le assunzioni su paginazione e ordinamento reggono con dati reali?
• Le espressioni di filtro corrispondono al sottoinsieme corretto di record?
• I valori null sono gestiti nel modo in cui i Tuoi consumatori si aspettano?

Validando questi comportamenti durante la modellazione — non dopo l'implementazione — elimini un'intera categoria di bug di integrazione.

rt-01-query-playgroundMissing

Pannello query del runtime per verifiche di comportamento live.

Come funziona il Mock Runtime

Il motore mock runtime è il cuore di Mockomat. Accetta query GraphQL e le traduce in operazioni MongoDB attraverso una pipeline a quattro stadi:

1. GraphQL Request Parser

La stringa della query in arrivo viene analizzata in un abstract syntax tree (AST). Questo stadio valida la sintassi della query ed estrae i campi richiesti, gli argomenti e le selezioni annidate.

2. Query Planner

L'AST viene analizzato insieme ai metadati del Tuo modello (definizioni delle entità, flag degli attributi, configurazioni delle relazioni) per creare un piano di esecuzione. Il planner determina:

• Quali collezioni MongoDB interrogare
• Quali campi proiettare
• Quali operazioni di filtro e ordinamento applicare
• Quali relazioni devono essere risolte

3. MongoDB Query Builder

Il piano di esecuzione viene tradotto in una pipeline di aggregazione MongoDB. Poiché MongoDB memorizza i dati in collezioni piatte (denormalizzate), il query builder simula la struttura relazionale:

• Gli stadi di lookup assemblano i dati correlati tra le collezioni
• Gli stadi di match applicano le espressioni di filtro
• Gli stadi di sort ordinano i risultati in base ai campi richiesti
• Gli stadi di skip e limit gestiscono la paginazione

4. Result Assembler

I risultati grezzi di MongoDB vengono rimodellati per corrispondere alla struttura di risposta GraphQL attesa. Le relazioni annidate vengono assemblate nella corretta gerarchia padre-figlio, e i nomi dei campi vengono mappati ai loro equivalenti GraphQL.

Questa pipeline viene eseguita su ogni query. Ciò che vedi nell'anteprima è esattamente ciò che i consumatori esterni ricevono dallo stesso endpoint.

rt-01b-runtime-pipelineMissing

Pipeline runtime a quattro stadi: parse → plan → build → assemble.

Esempi di query

Tutte le query sono dirette allo stesso endpoint:

POST /mock/{slug}/graphql

Query di lista

Recuperare una collezione paginata di record:

query {
  products(offset: 0, limit: 20) {
    id
    name
    price
    category {
      id
      name
    }
  }
}

Query di dettaglio

Recuperare un singolo record tramite il suo identificatore:

query {
  product(id: "abc-123") {
    id
    name
    price
    description
    category {
      id
      name
    }
  }
}

Query con filtri

Applicare espressioni di filtro per restringere i risultati:

query {
  products(
    filter: {
      filterGroup: {
        operator: AND
        items: [
          { attribute: "price", operator: GE, value: "10" }
          { attribute: "price", operator: LE, value: "50" }
        ]
      }
    }
    limit: 10
  ) {
    id
    name
    price
  }
}

Query con ordinamento

Ordinare i risultati per un campo sortable:

query {
  products(
    sort: { field: "price", direction: DESC }
    limit: 10
  ) {
    id
    name
    price
  }
}

Query con relazioni annidate

Attraversare le relazioni per includere dati correlati:

query {
  customers(limit: 5) {
    id
    firstName
    lastName
    orders {
      id
      totalAmount
      createdAt
      items {
        id
        productName
        quantity
      }
    }
  }
}

Filtri nel dettaglio

Il sistema di filtri supporta espressioni type-safe e componibili che possono essere combinate utilizzando logica booleana.

Operatori disponibili

Operatore	Descrizione	Funziona con
EQ	Uguale	Tutti i tipi
NE	Diverso	Tutti i tipi
LT	Minore di	Numeri, Date
GT	Maggiore di	Numeri, Date
LE	Minore o uguale	Numeri, Date
GE	Maggiore o uguale	Numeri, Date
LIKE	Contiene sottostringa	Stringhe
IS_NULL	Il campo è null	Tutti i tipi
IS_NOT_NULL	Il campo non è null	Tutti i tipi

Combinare i filtri

I filtri utilizzano l'algebra booleana con gli operatori AND e OR. I gruppi di filtri possono essere annidati per espressioni complesse:

filter: {
  filterGroup: {
    operator: OR
    groups: [
      {
        operator: AND
        items: [
          { attribute: "status", operator: EQ, value: "active" }
          { attribute: "price", operator: GT, value: "100" }
        ]
      }
      {
        operator: AND
        items: [
          { attribute: "status", operator: EQ, value: "featured" }
        ]
      }
    ]
  }
}

Questo esempio restituisce i prodotti che sono (attivi E costosi) OPPURE in evidenza.

Campi filtrabili

Solo gli attributi contrassegnati come filterable: true nel modello possono essere utilizzati nelle espressioni di filtro. Tentare di filtrare su un campo non filtrabile non avrà alcun effetto. Configura i flag filterable nell'editor tabella del Workspace.

Paginazione

Mockomat utilizza la paginazione basata su offset:

Parametro	Descrizione	Default
offset	Numero di elementi da saltare	0
limit	Numero di elementi da restituire	20

Una tipica richiesta paginata:

query {
  products(offset: 40, limit: 20) {
    id
    name
    price
  }
}

Questa restituisce gli elementi dal 41 al 60. Per recuperare la pagina successiva, incrementi l'offset del valore del limit.

Ordinamento

I campi contrassegnati come sortable: true nel modello possono essere utilizzati per ordinare i risultati.

Direzione	Significato
ASC	Ascendente (A→Z, 0→9, dal più vecchio al più recente)
DESC	Discendente (Z→A, 9→0, dal più recente al più vecchio)

Si può applicare un solo campo di ordinamento per query. Se non viene specificato alcun ordinamento, i risultati vengono restituiti nell'ordine naturale di archiviazione.

Attraversamento delle relazioni

Una delle funzionalità più potenti del runtime è la capacità di simulare dati relazionali da collezioni MongoDB piatte.

Come funziona

MongoDB memorizza i dati in collezioni denormalizzate — ogni record è un documento piatto senza join tramite foreign key. Il runtime simula la struttura relazionale:

1. Leggendo la definizione della relazione dal Tuo modello (entità sorgente, entità destinazione, cardinalità).
2. Costruendo stadi di lookup nella pipeline di aggregazione MongoDB che uniscono le collezioni correlate.
3. Assemblando risultati annidati che corrispondono alla struttura di risposta GraphQL.

Questo significa che le Tue query GraphQL si comportano come se fossero eseguite su un database completamente relazionale, anche se l'archiviazione sottostante è basata su documenti.

Cosa validare

Quando testi l'attraversamento delle relazioni:

• Le relazioni 1:1 dovrebbero restituire un singolo oggetto annidato (o null se non c'è corrispondenza).
• Le relazioni 1:n dovrebbero restituire un array di oggetti annidati.
• Le relazioni vuote dovrebbero restituire un array vuoto [], non null.
• Le relazioni profondamente annidate (es. Customer → Order → OrderItem) dovrebbero risolversi correttamente a ogni livello.

Checklist del comportamento delle query

Per ogni entità chiave nel Tuo modello, valida:

• Stabilità della query di lista — la stessa query restituisce una struttura coerente tra chiamate ripetute?
• Coerenza del singolo elemento — una query di dettaglio restituisce tutti i campi attesi?
• Comportamento di null e campi mancanti — i campi opzionali sono correttamente rappresentati come null?
• Attraversamento delle relazioni — gli oggetti annidati si risolvono con la cardinalità corretta?
• Accuratezza dei filtri — le espressioni di filtro corrispondono al sottoinsieme atteso?
• Correttezza dell'ordinamento — l'ordinamento produce un ordine prevedibile e stabile?
• Limiti della paginazione — offset e limit producono porzioni di pagina pulite senza duplicati?

rt-02-filter-sort-paginationMissing

Validazione del comportamento di filtri, ordinamento e paginazione.

Ispezione e debug del runtime

Quando il comportamento sembra errato, ispezioni in questo ordine:

1. Verificare le definizioni di tabelle e attributi

La causa più comune di comportamento imprevisto è un attributo mal configurato:

• Il tipo del campo è corretto? (Un prezzo memorizzato come string non ordinerà numericamente.)
• Il campo è contrassegnato come sortable/filterable/searchable?
• Il campo ha un mapping configurato?

2. Verificare i metadati di endpoint e query

Verifica che la query sia configurata correttamente nella vista di design API:

• La query è abilitata?
• Il nome della query e i parametri sono corretti?
• La configurazione della paginazione è appropriata?

3. Verificare lo stato del mapping sorgente

Se i campi restituiscono null o valori imprevisti:

• Il tipo di mapping è corretto (OFF_FIELD, FAKE, CONST)?
• Per i mapping OFF_FIELD, il dataset sorgente contiene i dati attesi?
• Per i mapping FAKE, il generatore Faker è configurato per il tipo di dato corretto?

4. Verificare le policy delle relazioni

Se i dati annidati mancano o sono errati:

• La direzione della relazione è corretta (sorgente → destinazione)?
• La cardinalità è corretta (1:1 vs 1:n)?
• L'entità destinazione esiste e ha dati mappati?
• Le colonne di collegamento sono specificate correttamente?

Problemi comuni e risoluzioni

Sintomo	Causa probabile	Risoluzione
Risposta vuota	Nessun dato importato per questa collezione	Verificare che l'importazione dei dati sia stata completata
I campi restituiscono null	Nessun mapping configurato	Aggiungere un mapping OFF_FIELD, FAKE o CONST
Relazione annidata vuota	Relazione mal configurata	Verificare direzione, entità di destinazione e colonne di collegamento
Ordinamento non funzionante	Campo non contrassegnato come sortable	Abilitare il flag sortable nell'editor tabella
Il filtro restituisce tutto	Campo non contrassegnato come filterable	Abilitare il flag filterable nell'editor tabella
Tipi di dato errati	Disallineamento del tipo di mapping	Verificare che il mapping produca il tipo atteso
La paginazione salta elementi	Errore nel calcolo dell'offset	Verificare che l'offset venga incrementato del valore del limit

rt-03-runtime-inspectionMissing

Flusso di ispezione del runtime e checkpoint di debug.

Validazione prima dell'export

Il runtime dovrebbe confermare la readiness prima di procedere alla generazione del codice backend. Un modello che supera la validazione a runtime ha molte più probabilità di produrre un backend generato pulito e funzionale.

Criteri di readiness

Prima dell'export, conferma che:

• I campi obbligatori sono stabili — tutti gli attributi required hanno valori coerenti e non null.
• La superficie delle operazioni è intenzionale — solo le query che vuoi esporre sono abilitate.
• Il comportamento delle relazioni è spiegabile — ogni query annidata si risolve correttamente e la cardinalità corrisponde alle Tue regole di business.
• Il comportamento di filtri e ordinamento è prevedibile — i consumatori possono fare affidamento su queste operazioni come documentato.
• Nessun suggerimento irrisolto — l'anteprima non mostra avvisi su attributi non mappati o configurazioni mancanti.

Workflow di validazione pre-export

1. Eseguire query di lista per ogni entità — verificare struttura e qualità dei dati.
2. Eseguire query di dettaglio per le entità chiave — verificare la completezza dei campi.
3. Testare tutti i filtri configurati — verificare il corretto sottoinsieme.
4. Testare l'ordinamento su ogni campo sortable — verificare l'ordinamento.
5. Testare i limiti della paginazione — verificare transizioni di pagina pulite.
6. Testare le query con relazioni annidate — verificare l'assemblaggio corretto a ogni livello.

rt-04-runtime-validationMissing

Vista riepilogativa della validazione pre-export del runtime.

Suggerimento per integratori

Developer / Integrator

Utilizza la validazione a runtime come verifica del contratto prima di integrare frontend o consumatori downstream. L'endpoint runtime serve gli stessi dati all'anteprima e ai consumatori esterni, quindi ciò che validi nel workspace è esattamente ciò che la Tua applicazione riceverà. Questo riduce significativamente le problematiche di integrazione.

Aspettative runtime enterprise

Enterprise User

I team enterprise dovrebbero trattare la validazione a runtime come un quality gate formale. Definiscano criteri di validazione per entità (campi obbligatori, profondità delle relazioni, copertura dei filtri) e includano i controlli runtime nel loro processo di revisione prima di promuovere i modelli all'uso in produzione.