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 i dati importati?
• 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, con una API key del progetto (i progetti ospite usano il proprio token di condivisione; vedi Integratori):

POST /mock/{slug}/graphql
Authorization: Bearer mck_your_api_key

Il campo radice è il nome di un'operazione dell'API design. Una query di elenco seleziona i record dentro items e può aggiungere total, page e pageSize; una query di dettaglio seleziona direttamente i campi. La risposta contiene ogni attributo mappato della tabella e le sue relazioni: la selezione non la restringe.

Query di lista

Recuperare una collezione paginata di record:

query {
  products(page: 1, pageSize: 20) {
    items {
      id
      name
      price
      category {
        id
        name
      }
    }
    total
    page
    pageSize
  }
}

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

Passa i parametri che l'operazione definisce nell'API design — qui minPrice (su price, gte) e maxPrice (su price, lte):

query {
  products(minPrice: 10, maxPrice: 50, pageSize: 10) {
    items {
      id
      name
      price
    }
    total
  }
}

Query con ordinamento

Ordina i risultati con sortField (un nome di attributo) e sortDirection:

query {
  products(sortField: "price", sortDirection: DESC, pageSize: 10) {
    items {
      id
      name
      price
    }
    total
  }
}

Query con relazioni annidate

Le relazioni della tabella tornano annidate, a un livello di profondità:

query {
  customers(pageSize: 5) {
    items {
      id
      firstName
      lastName
      orders {
        id
        totalAmount
        createdAt
      }
    }
    total
  }
}

Filtri nel dettaglio

I filtri appartengono all'operazione: li definisci nell'API design e il runtime li applica a ogni richiesta. I filtri di scope sono condizioni fisse dell'operazione; i parametri sono argomenti inviati dal chiamante — ciascuno legato a un attributo e a un operatore, eventualmente obbligatorio o con un valore predefinito.

Operatori disponibili

Operatore	Descrizione	Funziona con
eq	Uguale	Tutti i tipi
neq	Diverso	Tutti i tipi
gt / gte	Maggiore di / maggiore o uguale	Numeri, Date
lt / lte	Minore di / minore o uguale	Numeri, Date
in	Uno dei valori di un elenco	Tutti i tipi
like	Contiene (senza distinzione tra maiuscole e minuscole)	Stringhe
notIn	Nessuno dei valori di un elenco (solo filtri di scope)	Tutti i tipi
isNull / isNotNull	È null / non è null (solo filtri di scope)	Tutti i tipi

Combinare i filtri

Tutti i filtri di scope e i parametri di un'operazione si combinano con AND: al momento della richiesta non esistono OR né annidamenti. Passa i valori dei parametri inline o come variabili GraphQL:

query ProductsInRange($min: Float, $max: Float) {
  products(minPrice: $min, maxPrice: $max, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
  }
}

Con le variabili { "min": 10, "max": 50 }, questa restituisce i prodotti con un prezzo da 10 a 50.

Validazione dei parametri

Un argomento che l'operazione non definisce viene rifiutato con BAD_USER_INPUT, così come un parametro obbligatorio mancante senza valore predefinito. Le operazioni senza parametri ignorano gli argomenti sconosciuti. Definisci i parametri nell'API design.

Ricerca

searchTerm cerca senza distinzione tra maiuscole e minuscole in tutti gli attributi contrassegnati come ricercabili (fino a 64 caratteri):

query {
  products(searchTerm: "oak", pageSize: 10) {
    items {
      id
      name
    }
    total
  }
}

Paginazione

Mockomat utilizza la paginazione per pagine:

Parametro	Descrizione	Default
page	Numero di pagina, a partire da 1	1
pageSize	Record per pagina, al massimo 100	Dimensione di pagina predefinita dell'operazione (25 se non modificata)

Una tipica richiesta paginata:

query {
  products(page: 3, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
    page
    pageSize
  }
}

Questa restituisce i record dal 41 al 60. total conta tutti i record corrispondenti, quindi l'ultima pagina è total / pageSize, arrotondato per eccesso.

Ordinamento

Ordina con sortField (un nome di attributo) e sortDirection:

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. Senza sortField vale l'ordinamento predefinito dell'operazione; se non ne ha, i risultati arrivano nell'ordine 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 annidate si risolvono a un livello di profondità: un record correlato porta i propri attributi, non le sue relazioni (Customer → Order funziona; le righe dell'ordine non sono incluse). Ogni record padre riceve al massimo 50 record correlati.

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 — page e pageSize 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.)
• Per la ricerca: il campo è contrassegnato come Searchable?
• Per l'ordinamento: sortField è il nome di un attributo collegato a una colonna di dati?
• 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 (Sorgente dati o Costante)?
• Per i mapping Sorgente dati, l'attributo è collegato alla colonna giusta dei dati importati, e quella colonna contiene valori per questi record?
• I valori costanti compaiono su ogni riga, sia nelle righe di dati importati sia nelle righe composte da pool di valori.
• Per i mapping calcolati, il runtime non valuta le espressioni, quindi un campo calcolato non fa parte della risposta.

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	La tabella non è collegata a dati importati (NOT_READY)	Collegare la tabella ai dati importati nel pannello Mappings del board
I campi restituiscono null	Nessun mapping configurato	Collegare l'attributo a una colonna dei dati importati (mapping Sorgente dati)
Relazione annidata vuota	Relazione mal configurata	Verificare direzione, entità di destinazione e colonne di collegamento
Ordinamento non funzionante	sortField non è un attributo mappato	Usare il nome di un attributo mappato
Il filtro restituisce tutto	L'operazione non definisce alcun parametro per quell'argomento	Aggiungere il parametro nell'API design
Tipi di dato errati	Disallineamento del tipo di mapping	Verificare che il mapping produca il tipo atteso
La paginazione salta elementi	pageSize è cambiato tra le richieste	Mantenere pageSize costante e avanzare page di 1

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 sugli attributi con cui ordinano i Tuoi consumer — 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.