Concetti fondamentali

Mockomat è costruito attorno a un principio centrale: l'intento di dominio deve restare visibile dal modello al runtime.

Ogni decisione che prendi — denominare un'entità, definire un tipo di campo, stabilire una relazione — attraversa una pipeline connessa: dal Tuo modello di dominio, attraverso la definizione dell'API, fino al comportamento a runtime, e infine in un backend generato di Tua proprietà. Questa pagina spiega i livelli concettuali che rendono tutto ciò possibile.

1. Livello di dominio: il significato del sistema

Il livello di dominio è il fondamento semantico del Tuo progetto. Definisce la struttura e il significato dei Tuoi dati prima che qualsiasi dettaglio API o implementativo venga deciso.

Entità e tabelle

Un'entità (o tabella) rappresenta un concetto di business reale: Customer, Order, Invoice, Subscription. Ogni entità ha un nome, un insieme di attributi (colonne) e, opzionalmente, una o più relazioni con altre entità.

La denominazione è importante. Mockomat Ti incoraggia a utilizzare il linguaggio di business reale del Tuo team piuttosto che nomi di esempio generici. Un modello costruito con Customer e Subscription comunica l'intento molto meglio di Table1 e Table2.

Attributi

Ogni attributo possiede:

• Name — un identificatore descrittivo (es. firstName, totalAmount, isActive)
• Type — il tipo di dato, es. String, Integer, Float, Boolean, Date, JSON, Enum
• Flag Required — se il campo deve sempre avere un valore
• Flag Searchable — se il campo partecipa alla ricerca searchTerm delle operazioni di lista
• Flag Sortable e Filterable — salvati con il modello; Sortable segna inoltre colonne di lista ordinabili nell'export del codice

Di questi flag, solo Searchable modifica la mock API. L'ordinamento funziona su qualsiasi attributo collegato a una colonna di dati (sortField), e il filtro usa i parametri che definisci su un'operazione (vedi API Design (in inglese)).

Relazioni

Le relazioni collegano le entità ed esprimono pattern di ownership o riferimento nel business:

• One-to-One (1:1) — es. User → Profile
• One-to-Many (1:n) — es. Customer → Order[]
• Many-to-Many (m:n) — es. Product ↔ Category

Ogni relazione ha una direzione e una cardinalità. La definizione della relazione determina come il runtime risolve i lookup: quando interroga un Order, i dati del Customer correlato vengono assemblati dalla fonte dati sottostante sulla base di queste definizioni.

Perché questo livello è importante

• Riduce la deriva dei nomi — tutti nel team utilizzano lo stesso vocabolario.
• Migliora l'allineamento tra team — sviluppatori frontend e backend condividono un unico modello di verità.
• Rende l'architettura verificabile — l'intento di dominio è esplicito, non nascosto nel codice.
• Abilita l'automazione — generazione del codice, esposizione API e comportamento a runtime derivano tutti da questo livello.

cc-01-domain-layerMissing

Modello del livello di dominio con entità e relazioni.

2. Livello di definizione API: come il sistema viene esposto

Il livello API traduce l'intento di dominio in una superficie di query e operazioni. Mockomat utilizza un approccio GraphQL code-first: le definizioni del Tuo modello vengono tradotte automaticamente in uno schema GraphQL completamente tipizzato.

Generazione dinamica dello schema

Quando un progetto viene attivato, Mockomat genera uno schema GraphQL al volo:

1. Caricamento delle definizioni del modello — lettura di tutte le entità, attributi, relazioni e configurazioni dal progetto.
2. Costruzione dei tipi GraphQL — ogni entità diventa un object type GraphQL; ogni attributo diventa un campo tipizzato.
3. Costruzione dei punti di accesso alle query — vengono generate query di lista e di dettaglio per ogni entità.
4. Registrazione dei resolver — i resolver a livello di campo gestiscono il recupero dati, il mapping e i lookup delle relazioni.
5. Accettazione delle richieste — lo schema è pronto per servire le query immediatamente.

Questo significa che non dovrai mai scrivere file di schema manualmente. Lo schema è sempre sincronizzato con il Tuo modello.

Struttura delle query

Ogni entità genera automaticamente due tipi di query:

• Query di lista — restituisce una collezione paginata con filtro e ordinamento opzionali.
• Query di dettaglio — restituisce un singolo elemento tramite il suo identificatore.

Ad esempio, se modella un'entità Product, le query generate potrebbero apparire così:

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

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

Filtri

I filtri si definiscono per operazione nell'API design — filtri di scope fissi e parametri del chiamante, ciascuno con un operatore:

Operatore	Descrizione	Tipi applicabili
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

Tutti i filtri di un'operazione si combinano con AND; al momento della richiesta non esistono OR né annidamenti.

Ordinamento

Si ordina con sortField (un nome di attributo) e sortDirection — ascendente (ASC) o discendente (DESC).

Paginazione

Mockomat utilizza la paginazione per pagine:

• page — numero di pagina, a partire da 1 (default: 1)
• pageSize — record per pagina, al massimo 100 (default: la dimensione di pagina predefinita dell'operazione, 25 se non modificata)

La risposta racchiude i record in items, accanto a total, page e pageSize.

cc-02-endpoint-configMissing

Definizione API e vista di configurazione degli endpoint.

3. Livello Runtime: come il comportamento viene validato

Il livello runtime è dove le decisioni relative al modello e all'API vengono testate rispetto all'esecuzione reale delle query. Risponde alla domanda: il sistema si comporta come previsto?

Come funziona il Mock Runtime

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

1. GraphQL Request Parser — analizza la stringa della query in arrivo in un abstract syntax tree (AST).
2. Query Planner — analizza l'AST insieme ai metadati del modello per creare un piano di esecuzione.
3. MongoDB Query Builder — traduce il piano di esecuzione in una pipeline di aggregazione MongoDB.
4. Result Assembler — rimodella i risultati MongoDB per corrispondere alla struttura di risposta GraphQL attesa.

Questa pipeline viene eseguita su ogni query. Poiché MongoDB memorizza i dati in collezioni piatte (denormalizzate), il runtime simula la struttura relazionale — unendo i dati correlati, risolvendo i campi annidati e assemblando la risposta finale come se provenisse da un backend completamente relazionale.

Anteprima vs consumo esterno

Lo stesso endpoint runtime serve due tipologie di utenti:

• Anteprima — la pagina Runtime nell'applicazione dove testi le query, ispeziona le strutture di risposta e valida il comportamento durante la modellazione.
• Consumatori esterni — la Tua applicazione frontend, la suite di test o la pipeline CI che chiamano lo stesso endpoint mock API.

Entrambi utilizzano lo stesso endpoint REST: POST /mock/{slug}/graphql. Ciò significa che quello che validi nell'anteprima è esattamente ciò che i consumatori esterni riceveranno.

Cosa significa la validazione nella pratica

La validazione a runtime non è solo "la query restituisce dati". Conferma:

• Struttura dei campi — i tipi e le strutture restituiti sono quelli attesi?
• Lookup delle relazioni — gli oggetti annidati si risolvono correttamente?
• Comportamento della paginazione — page e pageSize producono porzioni consistenti?
• Stabilità dell'ordinamento — l'ordinamento su un campo produce un ordine prevedibile?
• Accuratezza dei filtri — le espressioni di filtro corrispondono al sottoinsieme corretto di dati?
• Gestione dei null — i campi opzionali sono correttamente rappresentati come null quando non esistono dati?

cc-03-runtime-flowMissing

Flusso dal modello al runtime con checkpoint di validazione.

4. Fonti dati e mapping dei campi

Ogni attributo nel Tuo modello necessita di una fonte dati. Mockomat supporta tre tipi di mapping che determinano da dove provengono i valori dei campi (l'editor degli attributi offre Sorgente dati e Costante, e mostra Calcolato solo sugli attributi che hanno già un mapping calcolato):

SOURCE — Colonne di dataset importati

Mappa un attributo a una colonna del pool di dati condiviso — dataset importati: dati aperti dove esiste una fonte verificata, dati di esempio generati per i blueprint. Il runtime restituisce le righe importate e non inventa mai valori.

Usalo quando vuoi:

• Nomi, indirizzi, dati di prodotto, categorie o misurazioni realistiche
• Grandi volumi di dati variegati
• Dati che appaiano autentici in demo e testing

CONSTANT — Valori costanti

Fissa un unico valore sull'attributo. Il runtime lo restituisce su ogni riga, sia nelle righe di dati importati sia nelle righe composte da pool di valori.

Usalo quando vuoi:

• Valori di stato predefiniti (es. "active")
• Valori di configurazione fissi

COMPUTED — Valori derivati (non valutati)

Memorizza un'espressione su altri campi dello stesso record (es. un nome completo da nome e cognome). Il runtime non valuta le espressioni, quindi un campo calcolato non fa parte della risposta. L'editor degli attributi non offre più Calcolato; un attributo che ha già un mapping calcolato lo mantiene ed è contrassegnato come non valutato.

cc-04-data-sourcesMissing

Configurazione del mapping dei campi con i diversi tipi di fonte dati.

Disponibilità delle fonti dati

Free User

Tutti i piani, sessioni ospite comprese, hanno gli stessi tipi di mapping e lo stesso pool di dati condiviso.

5. Isolamento dei progetti e multi-tenancy

Ogni progetto Mockomat opera nel proprio contesto isolato:

• Pool di dati condiviso e in sola lettura — i dati mock provengono da un pool condiviso di dataset importati; un progetto legge solo le tabelle a cui è collegato e non modifica mai i dati del pool.
• Schema indipendente — lo schema GraphQL viene generato per progetto sulla base del suo modello specifico.
• Endpoint basati su slug — ogni progetto ottiene un percorso URL univoco (/mock/{slug}/graphql).
• Scoping per tenant — modelli, membri e API key appartengono a un tenant, e ogni richiesta viene verificata rispetto a esso, garantendo un isolamento rigoroso tra le organizzazioni.

Questo significa che più team possono lavorare su progetti diversi contemporaneamente senza alcun rischio di perdita di dati o conflitti di schema.

Limiti enterprise

Enterprise User

L'isolamento è lo stesso su ogni piano. Enterprise si concorda con il nostro team commerciale: limiti come progetti, richieste e dimensione del team vengono adattati per contratto.

6. AI + architettura insieme

L'AI accelera la creazione. Mockomat preserva la qualità strutturale e la spiegabilità mentre i requisiti evolvono.

La piattaforma è progettata per lavorare insieme agli strumenti AI, non per sostituirli. Mentre l'AI può generare frammenti di codice rapidamente, Mockomat fornisce il contesto strutturale che al codice generato dall'AI spesso manca:

• Coerenza dello schema — il Tuo modello di dominio è l'unica fonte di verità, sia che lo costruisca manualmente sia con l'assistenza dell'AI.
• Verifica a runtime — ogni modifica può essere validata attraverso la pipeline di anteprima prima di raggiungere la produzione.
• Decisioni tracciabili — le modifiche al modello sono esplicite e verificabili, non nascoste nel codice generato dall'AI.

Prospettiva per integratori

Developer / Integrator

Tratta gli artefatti generati come punti di partenza, non come verità definitiva. Mantieni il modello come fonte dell'intento e lascia che il comportamento a runtime confermi la qualità. Quando integri workflow assistiti dall'AI, utilizza il modello Mockomat come contratto a cui i consumer generati dall'AI devono conformarsi.

Prospettiva enterprise

Enterprise User

Il valore a lungo termine deriva da un'architettura ripetibile, non solo da un output iniziale rapido. La continuità del dominio è il punto di controllo per l'evoluzione multi-team. Utilizza i modelli Mockomat come artefatti di governance che sopravvivono ai singoli cicli di sprint.