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; le chiamate dal proprio codice portano una API key del progetto (vedi Integratori):
POST /mock/{slug}/graphql
Authorization: Bearer mck_your_api_keyLo 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 | es. String, Integer, Float, Boolean, Date, JSON, Enum | Tipo negli export; scegli il tipo dei dati collegati |
| Required | Se il campo deve avere un valore | Indicato come obbligatorio nell'export OpenAPI |
| Sortable | Salvato con il modello | Segna colonne di lista ordinabili nell'export del codice; la mock API ordina per qualsiasi attributo mappato (sortField) |
| Searchable | Se il campo partecipa alla ricerca | Incluso nella ricerca searchTerm delle operazioni di lista |
| Filterable | Salvato con il modello | Nessun effetto sulla mock API — il filtro usa i parametri dell'operazione |
| Mapping | Fonte dati: SOURCE o CONSTANT; COMPUTED solo sugli attributi che lo hanno già (non valutato) | 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
Mappare i dati
Nel pannello Mappings della board colleghi prima la tabella a una tabella del pool di dati (Tabella canonica): Suggerisci ne propone una, oppure cerchi Tu stesso in tutte le tabelle. Poi colleghi i suoi attributi alle sue colonne (SOURCE); Adotta … sicure accetta in un colpo tutti i suggerimenti sicuri. Gli attributi che devono restare vuoti si contrassegnano con Nessuna mappatura necessaria. Dettagli: Data Sources & Field Mapping (in inglese).
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(pageSize: 5) {
items {
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 — impostare la dimensione della pagina predefinita (al massimo 100 record per pagina) e l'ordinamento predefinito.
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:
- Usa lo stato attuale del Tuo modello, dei Tuoi mapping e delle Tue operazioni.
- Esegue l'operazione di lista della tabella sui dati importati.
- Mostra i dati, con un suggerimento se manca qualcosa.
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 |
|---|---|---|
| Non mappata su dati importati | La tabella non è collegata a dati importati; l'API non restituisce righe per essa | Collegare la tabella e i suoi attributi nel pannello Mappings |
| Nessun binding API | La vista non è associata a un'operazione di lista; non si caricano dati | Associare un'operazione di lista nelle impostazioni della vista |
| Nessun campo identificativo | La vista non ha un campo identificativo; il clic su una riga non apre la vista dettagliata | Impostare il campo identificativo nelle impostazioni della vista |
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.