Workspace
Il workspace è il luogo in cui le decisioni di dominio, API e runtime restano connesse in un unico flusso operativo. È l'ambiente centrale dove costruisci, configuri, validi e iteri sul Tuo progetto di mock API.
Questa pagina illustra ogni area principale del workspace e spiega cosa fa ciascuna area, come utilizzarla efficacemente e a cosa prestare attenzione.
Aree del workspace
Il workspace è organizzato in aree distinte, ciascuna focalizzata su una parte specifica del flusso di modellazione e design dell'API. Puoi spostarti tra queste aree in qualsiasi momento — le modifiche in un'area si riflettono immediatamente in tutte le altre.
1. Contesto del progetto e navigazione
Il contesto di livello superiore del workspace controlla su quale progetto stai lavorando e come navighi tra le diverse viste.
Cosa puoi fare
- Cambiare progetto attivo — se hai più progetti, il selettore di progetto Ti permette di cambiare contesto senza perdere la Tua posizione.
- Mantenere stabile il contesto di modellazione — il workspace ricorda quale tabella, vista o pannello di configurazione aveva aperto.
- Spostarsi tra le viste — navigare tra la board di modellazione, l'editor delle tabelle, il design dell'API e l'anteprima runtime.
Impostazioni del progetto
Ogni progetto ha uno slug univoco che determina l'URL del suo endpoint API:
POST /mock/{slug}/graphqlLo slug viene generato automaticamente dal nome del Tuo progetto, ma può essere personalizzato. Mantieni gli slug brevi, in minuscolo e separati da trattini (es. customer-portal, ecommerce-demo).
Barra del contesto progetto e cambio vista.
2. Board di modellazione
La board di modellazione è l'area di progettazione strutturale — un canvas visuale dove crei e disponi le Tue entità di dominio e le loro connessioni.
Lavorare con le tabelle
La board visualizza ogni entità come una scheda tabella. Puoi:
- Creare nuove tabelle — aggiungere entità che rappresentano concetti di business (es.
Product,Customer,Order). - Posizionare le tabelle — trascinare e rilasciare le schede tabella per disporle spazialmente. Raggruppare le entità correlate per chiarezza visiva.
- Modificare le proprietà delle tabelle — rinominare le tabelle, configurare le opzioni di visualizzazione e gestire i metadati.
- Eliminare le tabelle — rimuovere le entità non più necessarie.
Linee di relazione visive
Le relazioni tra tabelle sono mostrate come linee visive che collegano le entità correlate. Le linee indicano:
- Direzione — quale entità possiede la relazione (direzione della freccia).
- Cardinalità — il tipo di relazione (1:1, 1:n, m:n) mostrato tramite annotazioni sulle linee.
- Punti di connessione — quali colonne sono coinvolte nella relazione.
Questa rappresentazione visiva rende facile esaminare la struttura del dominio a colpo d'occhio e individuare relazioni mancanti o errate.
Controlli della board
- Zoom e spostamento — navigare board ampie con lo zoom della rotella del mouse e il trascinamento per lo spostamento.
- Aggancio alla griglia — l'allineamento opzionale alla griglia mantiene le tabelle ordinatamente posizionate.
- Layout automatico — disporre automaticamente le tabelle per una leggibilità ottimale.
Board di modellazione con entità di dominio connesse.
3. Configurazione di tabelle e attributi
Quando selezioni una tabella sulla board di modellazione, si apre il pannello dell'editor tabella con opzioni di configurazione dettagliate per l'entità e i suoi attributi.
Proprietà della tabella
Ogni tabella dovrebbe avere:
- Un nome chiaro — utilizza nomi singolari che corrispondano al Tuo linguaggio di business (
Invoice, noninvoices_table). - Una descrizione — opzionale ma utile per la comunicazione di team e la documentazione.
Configurazione degli attributi
Per ogni attributo (colonna), configura:
| Proprietà | Descrizione | Impatto |
|---|---|---|
| Name | L'identificatore del campo | Diventa il nome del campo GraphQL |
| Type | string, number, boolean, date, json | Determina gli operatori di filtro e la validazione |
| Required | Se il campo deve avere un valore | Influenza la nullability di GraphQL |
| Sortable | Se il campo supporta operazioni di ordinamento | Abilita il parametro sort nelle query |
| Searchable | Se il campo partecipa alla ricerca | Incluso nella risoluzione delle query di ricerca |
| Filterable | Se il campo supporta espressioni di filtro | Abilita il parametro filter nelle query |
| Mapping | Fonte dati: OFF_FIELD, FAKE o CONST | Determina quali dati restituisce il campo |
Convenzioni di denominazione
Una denominazione coerente rende il Tuo modello leggibile e il codice generato prevedibile:
- Attributi — utilizza
camelCase(es.firstName,totalAmount,isActive) - Tabelle — utilizza
PascalCasesingolare (es.Customer,OrderItem) - Evita le abbreviazioni —
descriptionè meglio didesc,quantityè meglio diqty
Selezione del data object
Quando mappi un attributo a un campo di dataset reale (OFF_FIELD), si apre un pannello laterale con:
- Ricerca — trovare data object per nome o tag
- Filtri per tag — restringere i risultati per categoria
- Anteprima dei campioni — vedere valori di esempio prima di confermare un mapping
Questo garantisce di selezionare la fonte dati corretta per ogni attributo.
Editor tabella con pannello di configurazione attributi.
Pannello di selezione dei data object con ricerca e anteprima.
4. Definizione delle relazioni
Le relazioni collegano le Tue entità e definiscono come i dati fluiscono tra di esse. Configurare correttamente le relazioni è fondamentale — determinano come le query annidate si risolvono a runtime.
Tipi di relazione
| Tipo | Esempio | Significato |
|---|---|---|
| One-to-One (1:1) | User → Profile | Ogni utente ha esattamente un profilo |
| One-to-Many (1:n) | Customer → Order[] | Ogni cliente ha più ordini |
| Many-to-Many (m:n) | Product ↔ Category | I prodotti appartengono a più categorie e viceversa |
Checklist di qualità
Prima di finalizzare una relazione, si ponga queste domande:
- Ownership o riferimento? — Questa relazione rappresenta un'ownership reale (un cliente possiede i suoi ordini) o un riferimento (un ordine fa riferimento a un metodo di pagamento)?
- Chiarezza della direzione — È chiaro quale entità è il padre e quale è il figlio?
- Comportamento di lookup — Quando interroga il padre, i dati del figlio devono essere inclusi per default? E nella direzione inversa?
- Correttezza della cardinalità — È davvero 1:n, o potrebbe diventare m:n in futuro?
Come le relazioni influenzano il runtime
A runtime, le relazioni determinano come il motore di query assembla i dati annidati. Quando interroga:
query {
customers(limit: 5) {
id
name
orders {
id
totalAmount
}
}
}Il runtime utilizza la definizione della relazione per cercare i record Order correlati per ogni Customer. Se la relazione è mal configurata (direzione errata, riferimento a foreign key mancante), i dati annidati saranno vuoti o errati.
Configurazione delle relazioni e della cardinalità.
5. Integrazione del design API
L'area di design API Ti permette di controllare come il Tuo modello di dominio viene esposto come API GraphQL. Non ogni entità o operazione deve essere pubblica — la vista di design API Ti aiuta a esporre solo ciò che ha senso per la fase corrente.
Denominazione delle query
Mockomat genera automaticamente i nomi delle query dai nomi delle Tue entità, ma puoi personalizzarli:
- Query di lista — per default la forma plurale (es.
products,customers) - Query di dettaglio — per default la forma singolare (es.
product,customer)
Scegli nomi che corrispondano al modo in cui il Tuo team frontend pensa ai dati. Il nome della query diventa il punto di accesso in ogni richiesta GraphQL.
Esposizione delle operazioni
Controlla quali operazioni sono disponibili:
- Abilitare/disabilitare le query di lista — decidere se i consumer possono recuperare collezioni.
- Abilitare/disabilitare le query di dettaglio — decidere se i consumer possono recuperare singoli record.
- Configurare i valori predefiniti di paginazione — impostare la dimensione della pagina predefinita e i limiti massimi.
Principi di design
- Iniziare in modo restrittivo — esponi prima meno operazioni, poi amplia man mano che il modello si stabilizza.
- Denominare intenzionalmente — i nomi delle query fanno parte del Tuo contratto API. Cambiarli in seguito influenza tutti i consumer.
- Validare prima di esporre — utilizza l'anteprima per confermare il comportamento prima di condividere l'endpoint con il Tuo team.
Vista di design API allineata alle tabelle del modello.
6. Flusso di anteprima e suggerimenti
L'anteprima dovrebbe far parte di ogni iterazione di modellazione, non essere un passaggio finale. È il ciclo di feedback che mantiene il Tuo modello coerente.
Come funziona l'anteprima
Quando apri l'anteprima, Mockomat:
- Genera uno schema GraphQL dal Tuo modello corrente.
- Esegue una query di esempio sui Tuoi dati mappati.
- Restituisce i risultati insieme ai suggerimenti di readiness.
L'anteprima mostra sia la risposta dati che eventuali problemi che richiedono attenzione.
Tipi di suggerimenti
I suggerimenti sono segnali azionabili che La aiutano a identificare e risolvere problemi del modello:
| Suggerimento | Significato | Azione |
|---|---|---|
| Attributo non mappato | Un campo non ha una fonte dati configurata | Assegnare un mapping OFF_FIELD, FAKE o CONST |
| Metadati endpoint mancanti | Una query o operazione manca della configurazione richiesta | Aprire la vista di design API e completare la configurazione |
| Disallineamento di configurazione | Un campo è contrassegnato come sortable ma ha un tipo di dato non compatibile | Verificare la combinazione di tipo attributo e flag |
| Avviso relazione | Un'entità o colonna target della relazione manca | Controllare la definizione della relazione nell'editor tabella |
Flusso di iterazione
Il workflow più produttivo segue un ciclo serrato:
- Apportare una modifica al modello — aggiungere una tabella, modificare un attributo, creare una relazione.
- Aprire l'anteprima — eseguire una query e ispezionare i risultati.
- Esaminare i suggerimenti — risolvere eventuali avvisi o errori.
- Aggiornare il design API — regolare i nomi delle query o l'esposizione delle operazioni se necessario.
- Ripetere — continuare fino a quando il modello è stabile e l'anteprima è pulita.
Questo ciclo dovrebbe richiedere secondi, non minuti. Più rapidamente iteri, maggiore sarà la qualità del Tuo modello finale.
Vista anteprima con suggerimenti di readiness azionabili.
7. Viste e navigazione con cross-link
Le viste offrono prospettive diverse sullo stesso modello sottostante. Invece di navigare attraverso menù, puoi spostarti tra contesti correlati utilizzando i cross-link.
Viste disponibili
- Vista board — il canvas di modellazione visuale che mostra tabelle e relazioni.
- Vista dettaglio tabella — vista focalizzata su una singola entità con la configurazione completa degli attributi.
- Vista design API — configurazione delle query e delle operazioni per l'entità selezionata.
- Anteprima runtime — esecuzione di query live e ispezione delle risposte.
Navigazione con cross-link
Quando lavori in una vista, i link ai contesti correlati sono disponibili inline. Ad esempio:
- Dalla vista dettaglio tabella, puoi passare direttamente all'anteprima runtime per testare le query di quella tabella.
- Dall'anteprima runtime, puoi tornare all'editor tabella se noti un problema con un campo.
- Dalla vista design API, puoi passare alla board di modellazione per esaminare la struttura completa del dominio.
Questo modello di navigazione Ti mantiene nel flusso — non devi mai tornare "alla dashboard" per cambiare contesto.
Navigazione con cross-link tra le viste del workspace.