Modellare il dominio

Entità

Un'entità è un oggetto definito principalmente dalla sua identità e non solo dai suoi attributi. Anche se gli attributi cambiano nel tempo, l'identità di un'entità rimane la stessa.

Caratteristiche principali:

• Possiede un'identità unica (di solito un Id).
• Ciò che conta è chi è l'entità, non solo cosa contiene.
• I suoi attributi possono cambiare nel tempo.

Creare un'entità con Lino

Per creare una nuova entità usando Lino, esegui:

lino entity new

Il wizard CLI ti chiederà:

• Servizio – Il servizio in cui l'entità sarà creata.
• Modulo – Il modulo in cui sarà creata l'entità (solo per servizi modulari).
• Nome dell'entità – Il nome usato nel dominio e nella tabella del database.

Successivamente, definirai i campi che compongono l'entità configurando ciascuno di essi.

Tipi di campi disponibili

Esempio

Creazione dell'entità Person:

┌────┬────┬───────────────┬────────┬────────┬───────────┬────────────────┐
│ PK │ FK │ Property name │ Type   │ Length │ Required  │ Auto-increment │
├────┼────┼───────────────┼────────┼────────┼───────────┼────────────────┤
│ x  │    │ Id            │ int    │        │     x     │       x        │
├────┼────┼───────────────┼────────┼────────┼───────────┼────────────────┤
│    │    │ Name          │ string │  100   │     x     │                │
└────┴────┴───────────────┴────────┴────────┴───────────┴────────────────┘

Struttura generata da Lino:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Domain/
                ├── <ProjectName>.<ServiceName>.Domain.csproj
                └── Aggregates/
                    └── People/
                        ├── Person.cs
                        ├── Errors/
                        │   └── PersonErrors.cs
                        ├── Repositories/
                        │   └── IPersonRepository.cs
                        └── Resources/
                            └── Person/
                                ├── PersonResources.resx
                                ├── PersonResources.en.resx
                                └── PersonResources.pt-BR.resx

Dopo aver definito le tue entità, usa Lino stesso per gestire le Migrations e mantenere sincronizzato il database. Questo processo sarà trattato in dettaglio nella sezione Layer di Persistenza.

Flusso attuale di evoluzione

Oltre al flusso interattivo con lino entity new, la CLI consente anche di rendere esplicita l'intenzione nel comando quando servizio, modulo e nome sono già noti:

lino entity new --name <EntityName> --service <ServiceName> --module <ModuleName>
lino entity edit --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino entity list --service <ServiceName> --module <ModuleName>

Usare entity list prima di creare nuovi concetti in moduli grandi. Durante le modifiche, verificare identificatore, proprietà, obbligatorietà, lunghezza, relazioni, indici, ownership, tenant e impatto sulle migrations.

Strongly Typed IDs, ownership e invarianti

Quando gli Strongly Typed IDs sono abilitati, l'identificatore diventa un tipo dedicato, come ProductId, riducendo scambi accidentali tra IDs di entità diverse. Le relazioni devono riflettere il reale ownership del dominio: non ogni riferimento deve diventare una navigazione diretta; spesso un identificatore, una shadow entity, un evento di integrazione o una query esplicita protegge meglio i confini tra moduli.

Collocare le invarianti nel dominio, non solo nella UI, nel database o nei validators. Dopo aver modificato le entità, eseguire una build, rivedere il diff e generare o aggiornare le migrations.

Value Objects

Un Value Object rappresenta un concetto di dominio definito solo dai suoi attributi – non possiede un’identità propria. Due Value Objects sono considerati uguali se tutti i loro valori sono uguali.

Caratteristiche principali:

• Immutabili dopo la creazione.
• Non possiedono Id.

Creare un Value Object con Lino

Esegui:

lino value-object new

Il CLI chiederà:

• Servizio – Servizio in cui sarà creato l’oggetto.
• Modulo – Modulo in cui sarà creato l’oggetto (solo nei servizi modulari).
• Posizione – Radice del dominio o specifico aggregato.
• Nome dell’Value Object.

Quindi definisci i campi che compongono l’oggetto.

Tipi di campo disponibili

Esempio

Value Object Address:

┌───────────────┬────────┬────────┬───────────┐
│ Property name │ Type   │ Length │ Required  │
├───────────────┼────────┼────────┼───────────┤
│ Street        │ string │  100   │     x     │
├───────────────┼────────┼────────┼───────────┤
│ Number        │ string │   10   │     x     │
├───────────────┼────────┼────────┼───────────┤
│ Neighborhood  │ string │   50   │           │
├───────────────┼────────┼────────┼───────────┤
│ City          │ string │  100   │     x     │
├───────────────┼────────┼────────┼───────────┤
│ State         │ string │   2    │     x     │
├───────────────┼────────┼────────┼───────────┤
│ PostalCode    │ string │   20   │     x     │
├───────────────┼────────┼────────┼───────────┤
│ Country       │ string │  100   │     x     │
└───────────────┴────────┴────────┴───────────┘

Struttura dei file generata (aggregato Person):

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Domain/
                ├── <ProjectName>.<ServiceName>.Domain.csproj
                └── Aggregates/
                    └── People/
                        ├── Person.cs
                        ├── ValueObjects/
                        │   └── Address.cs
                        ├── Errors/
                        │   ├── AddressErrors.cs
                        │   └── PersonErrors.cs
                        ├── Repositories/
                        │   └── IPersonRepository.cs
                        └── Resources/
                            ├── Address/
                            │   ├── AddressResources.resx
                            │   ├── AddressResources.en.resx
                            │   └── AddressResources.pt-BR.resx
                            └── Person/
                                ├── PersonResources.resx
                                ├── PersonResources.en.resx
                                └── PersonResources.pt-BR.resx

Come per le entità, le Migrations possono essere gestite da Lino per mantenere il modello dati sincronizzato.

Flusso attuale di evoluzione

Oltre al comando interattivo, usare i parametri quando si sa già dove il concetto deve nascere:

lino value-object new --name <ValueObjectName> --service <ServiceName> --module <ModuleName>
lino value-object edit --service <ServiceName> --module <ModuleName> --value-object <ValueObjectName>
lino value-object list --service <ServiceName> --module <ModuleName>

Quando una proprietà di entità è dichiarata come ValueObject, Lino può riutilizzare un Value Object esistente o crearne uno nuovo durante la modellazione dell'entità. Preferire questa opzione quando l'insieme di campi rappresenta un unico concetto, come denaro, indirizzo, dimensioni, periodo o documento.

Persistenza, UI e localizzazione

Lino mappa le proprietà dei Value Objects tramite il layer di persistenza del modulo e porta i metadati di visualizzazione nei resources. Questo abilita labels e messaggi localizzati per valori annidati. Il Value Object appartiene al modulo in cui è stato generato; non diventa un contratto condiviso tra moduli senza un'integrazione esplicita.

Proteggere le invarianti nel tipo stesso: valori negativi, valuta non valida, periodi invertiti o documenti malformati non devono nascere validi.

Enumerazioni

Le enumerazioni nel DDD possono andare oltre i tradizionali enum di C#. Possono essere oggetti ricchi che rappresentano stati fissi, contenenti validazioni, metodi ausiliari e persino comportamenti.

Motivazione:

• I enum di C# sono limitati a un valore intero o stringa.
• Modellare un'Enumeration come classe offre maggiore flessibilità ed espressività.

Caratteristiche principali:

• Sono classi che ereditano da una base comune e incapsulano Id e Nome.
• Permettono di aggiungere validazioni, metodi ausiliari e comportamenti.

Creare un'enumerazione con Lino

Esegui:

lino enumeration new

L'assistente richiederà:

• Servizio.
• Modulo (se applicabile).
• Posizione – radice del dominio o aggregato.
• Nome dell'enumerazione.
• Tipo – enum tradizionale o Smart Enum (class).
• Archiviazione – int o string nel database.

Esempio

Enumerazione PersonStatus:

┌───────┬───────────┬──────────────┐
│ Value │ Name      │ Display Name │
├───────┼───────────┼──────────────┤
│ 1     │ Active    │ Active       │
├───────┼───────────┼──────────────┤
│ 2     │ Inactive  │ Inactive     │
├───────┼───────────┼──────────────┤
│ 3     │ Suspended │ Suspended    │
├───────┼───────────┼──────────────┤
│ 4     │ Deleted   │ Deleted      │
└───────┴───────────┴──────────────┘

Struttura generata:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Domain/
                ├── <ProjectName>.<ServiceName>.Domain.csproj
                └── Aggregates/
                    └── People/
                        ├── Person.cs
                        ├── Enums/
                        │   └── PersonStatus.cs
                        ├── ValueObjects/
                        │   └── Address.cs
                        ├── Errors/
                        │   ├── AddressErrors.cs
                        │   └── PersonErrors.cs
                        ├── Repositories/
                        │   └── IPersonRepository.cs
                        └── Resources/
                            ├── Address/
                            │   ├── AddressResources.resx
                            │   ├── AddressResources.en.resx
                            │   └── AddressResources.pt-BR.resx
                            ├── Person/
                            │   ├── PersonResources.resx
                            │   ├── PersonResources.en.resx
                            │   └── PersonResources.pt-BR.resx
                            └── PersonStatus/
                                ├── PersonStatusResources.resx
                                ├── PersonStatusResources.en.resx
                                └── PersonStatusResources.pt-BR.resx

Archiviare il valore di un'enumerazione come string è valido e può migliorare la leggibilità, ma tende ad essere meno efficiente in termini di prestazioni e spazio di archiviazione. Per questo, consigliamo di archiviare il valore come int e, per mantenere l'integrità referenziale e facilitare la manutenzione, creare un'entità (tabella) ausiliaria dove la chiave primaria corrisponda al valore dell'enumerazione.

Dopo aver definito le enumerazioni, usa Lino per generare e applicare le Migrations, garantendo che il database rifletta il modello di dominio. Vedi i dettagli nella sezione Layer di Persistenza.

Flusso attuale di evoluzione

Oltre al comando interattivo, usare i parametri quando posizione e nome sono già definiti:

lino enumeration new --name <EnumerationName> --service <ServiceName> --module <ModuleName>
lino enumeration edit --service <ServiceName> --module <ModuleName> --enumeration <EnumerationName>
lino enumeration list --service <ServiceName> --module <ModuleName>

Enumeration, entità o configurazione

Se la enumeration espone un nome visualizzato, Lino può generare resources per labels localizzate. Se viene persistita o usata come seed data, rivedere le migrations dopo aver aggiunto, rimosso o rinominato valori. La coerenza tra codice, database e UI fa parte della modifica di dominio.