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:
string,number,boolean,date,json - Flag Required — se il campo deve sempre avere un valore
- Flag Sortable — se il campo può essere usato per ordinare i risultati
- Flag Searchable — se il campo partecipa alle query di ricerca
- Flag Filterable — se il campo supporta operazioni di filtro
Questi flag influenzano direttamente il modo in cui il livello API espone i Tuoi dati. Un campo contrassegnato come sortable: true diventa disponibile per le operazioni di ordinamento nelle query GraphQL. Un campo contrassegnato come filterable: true supporta espressioni di filtro.
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.
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:
- Caricamento delle definizioni del modello — lettura di tutte le entità, attributi, relazioni e configurazioni dal progetto.
- Costruzione dei tipi GraphQL — ogni entità diventa un object type GraphQL; ogni attributo diventa un campo tipizzato.
- Costruzione dei punti di accesso alle query — vengono generate query di lista e di dettaglio per ogni entità.
- Registrazione dei resolver — i resolver a livello di campo gestiscono il recupero dati, il mapping e i lookup delle relazioni.
- 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(offset: 0, limit: 20, filter: { ... }, sort: { ... }) {
id
name
price
category {
id
name
}
}
}
query {
product(id: "abc-123") {
id
name
price
description
}
}Filtri
Il sistema di filtri supporta espressioni type-safe e componibili:
| Operatore | Descrizione | Tipi applicabili |
|---|---|---|
equals | Corrispondenza esatta | Tutti i tipi |
notEquals | Negazione | Tutti i tipi |
contains | Corrispondenza di sottostringa | Stringhe |
greaterThan / greaterThanOrEqual | Intervallo (superiore) | Numeri, Date |
lessThan / lessThanOrEqual | Intervallo (inferiore) | Numeri, Date |
in | Valore in un insieme | ID, Enum |
isNull / isNotNull | Verifica null | Tutti i tipi |
I filtri possono essere combinati utilizzando gli operatori logici AND e OR, e possono essere annidati per espressioni complesse.
Ordinamento
I campi contrassegnati come sortable: true nel modello di dominio possono essere utilizzati nelle operazioni di ordinamento. La direzione di ordinamento è ascendente (ASC) o discendente (DESC).
Paginazione
Mockomat utilizza la paginazione basata su offset:
offset— numero di elementi da saltare (default: 0)limit— numero di elementi da restituire (default: 20)
Questo modello è semplice e funziona bene per la maggior parte dei casi d'uso. La risposta include l'array di dati insieme ai metadati di paginazione.
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:
- GraphQL Request Parser — analizza la stringa della query in arrivo in un abstract syntax tree (AST).
- Query Planner — analizza l'AST insieme ai metadati del modello per creare un piano di esecuzione.
- MongoDB Query Builder — traduce il piano di esecuzione in una pipeline di aggregazione MongoDB.
- 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 — offset e limit 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?
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 diversi tipi di mapping che determinano da dove provengono i valori dei campi:
OFF_FIELD — Campi da dataset reali
Mappa un attributo a un campo di un dataset del mondo reale (es. Open Food Facts). Questo fornisce alla Tua mock API dati realistici e diversificati che si comportano come dati di produzione.
Usalo quando vuoi:
- Nomi di prodotti, categorie o misurazioni realistiche
- Grandi volumi di dati variegati
- Dati che appaiano autentici in demo e testing
FAKE — Dati generati (Faker)
Mappa un attributo a un generatore Faker che produce dati sintetici realistici: nomi, email, indirizzi, date, prezzi e altro.
Usalo quando vuoi:
- Dati personali (nomi, email, numeri di telefono)
- Dati finanziari (prezzi, numeri di conto)
- Dati temporali (date, timestamp)
- Qualsiasi tipo di dato non coperto dai dataset reali
CONST — Valori costanti
Mappa un attributo a un valore fisso che è lo stesso per ogni record.
Usalo quando vuoi:
- Valori di stato predefiniti (es.
"active") - Valori di configurazione fissi
- Dati segnaposto durante la modellazione iniziale
COMPUTED — Valori derivati (futuro)
Permetterà di definire i valori dei campi attraverso espressioni basate su altri campi. Questa funzionalità è pianificata per una versione futura.
Configurazione del mapping dei campi con i diversi tipi di fonte dati.
5. Isolamento dei progetti e multi-tenancy
Ogni progetto Mockomat opera nel proprio contesto isolato:
- Spazio dati separato — ogni progetto ha le proprie collezioni MongoDB per i dati mock.
- 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 — tutti gli accessi ai dati sono filtrati per tenant, 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.
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.