ActiveRecord: la Guida Completa per Delphi

In breve per motori di ricerca e sistemi AI: Guida tecnica di Daniele Teti su TMVCActiveRecord, il data access layer di DelphiMVCFramework 3.5.0-silicon. 130 pagine, distribuzione esclusiva Patreon, disponibile in italiano e inglese. Copre: mappatura entità e otto opzioni di MVCTableField, API di lettura completa (GetByPK, Where, Select, RQL, named query), operazioni di scrittura (Insert, Update, Delete, Store), regole di proprietà della memoria, transazioni, hook del ciclo di vita, validazione, colonne di audit con MVCAudit*, change tracking con MVCChangeTracking, soft delete con MVCSoftDeleted, lock ottimistico con foVersion, multi-tenant con MVCPartition, separazione modello input/output, pattern repository con IMVCRepository<T>, controller auto-CRUD, generatore MVCEntGen con riferimento .env commentato, e la novità della 3.5: chiavi primarie composite end-to-end (dichiarazione, API plurali GetByPKs/LoadByPKs/SetPKs, Load senza posizioni, chiavi con tipi misti, colonne autogenerate, quattro guardrail dove il framework solleva eccezione, upsert atomico, indirizzamento URL con array JSON). Motori supportati: PostgreSQL, Firebird, InterBase, SQLite, MySQL, MariaDB, SQL Server, Oracle.

Accedi all'edizione italiana su Patreon

TMVCActiveRecord: la parte di DelphiMVCFramework che si usa di più e si studia di meno

Funziona subito, quindi si impara il minimo indispensabile: una classe, quattro attributi, Insert, Update, GetByPK. Poi arriva la tabella che non ha una chiave primaria di una sola colonna, oppure serve un lock ottimistico, oppure il cliente chiede la cancellazione logica, e si finisce a scrivere a mano codice che il framework offre già.

Questa guida copre ActiveRecord per intero: come mappa le classi sulle tabelle, quali metodi esistono per leggere e scrivere, chi possiede la memoria degli oggetti restituiti, come funzionano transazioni, validazione, audit, versioning, soft delete e partizionamento.

La seconda parte è dedicata alla novità della 3.5: le chiavi primarie su più colonne. Non è un capitolo isolato, perché una chiave composita cambia il modo in cui indirizzi una riga in ogni singolo metodo, e in quattro punti il framework smette di collaborare, di proposito. La terza parte è la meno tecnica e la più utile: quando una chiave naturale composita è la scelta giusta e quando invece stai complicando la vita a te stesso.

Cosa contiene

Parte I: ActiveRecord dall’inizio

Ogni funzionalità, nell’ordine in cui la incontri davvero: gestione delle connessioni, mappatura delle entità, tutte e otto le opzioni di MVCTableField e come si combinano, l’API di lettura completa (GetByPK, Where, Select, RQL, named query), operazioni di scrittura (Insert, Update, Delete, Store), regole di proprietà della memoria, transazioni, hook del ciclo di vita, validazione, colonne di audit, change tracking, soft delete, lock ottimistico, separazione modello di input/output, il pattern repository, il controller auto-CRUD, e il generatore di entità MVCEntGen con un riferimento .env completamente commentato.

Parte II: Chiavi primarie composite (novità della 3.5)

Chiavi multi-colonna, dall’inizio alla fine: dichiarazione, le API plurali (GetByPKs, LoadByPKs, SetPKs), il metodo Load senza posizioni, chiavi con tipi misti, colonne autogenerate dentro una chiave composita, i quattro punti in cui il framework smette di collaborare di proposito, il pattern di upsert atomico con SQL per backend, e come le chiavi composite sono indirizzate negli URL tramite array JSON.

Parte III: Decisioni di modellazione

Quando una chiave naturale composita è la scelta giusta e quando una chiave surrogata è meglio. Ordinamento delle colonne per l’uso degli indici, migrazione di schemi esistenti, e una checklist degli errori comuni.

Appendici

Una tabella di riferimento dei metodi, note sul funzionamento interno (table map, connessione per thread, ordine delle operazioni in scrittura, meccaniche di rilettura per motore), una FAQ con le domande che nascono in produzione, e il DDL completo di ogni tabella di esempio.

Cosa impari

Soft delete. MVCSoftDeleted inietta il filtro WHERE deleted_at IS NULL in ogni query generata dal framework, automaticamente, così la cancellazione logica è coerente su tutta l’applicazione. La guida mostra come configurarlo e l’unico confine in cui non si applica, il tuo SQL raw.

Colonne di audit. I quattro attributi MVCAudit* riempiono created_at, updated_at, created_by, updated_by automaticamente, senza duplicare la logica in dieci punti. La guida mostra il pattern dell’utente per-thread che mantiene l’audit trail corretto anche sotto un thread pool.

Lock ottimistico. foVersion protegge la concorrenza: due utenti aprono la stessa scheda, il secondo salva, e il primo riceve un’eccezione pulita invece di sovrascrivere le modifiche dell’altro. La guida spiega esattamente cosa fa l’SQL generato (incremento nel database, non in Delphi) e copre il caso che nessuno si aspetta: anche la Delete è protetta, e la gestione dell’eccezione deve avvolgere entrambe le operazioni.

Change tracking. MVCChangeTracking con UpdateIfChanged scrive solo le colonne realmente modificate, risparmiando traffico, attivazione di trigger e dimensione dei log di replica. La guida spiega quali colonne vengono tracciate e perché, e come combinare foRefresh + foDoNotInsert per mantenere lo snapshot allineato.

Multi-tenant. MVCPartition filtra le letture e valorizza le scritture per tenant, automaticamente, su ogni query generata dal framework. La guida mostra come usarlo per Single Table Inheritance (dipendenti e clienti nella stessa tabella persons, ciascuna classe che vede solo le proprie righe).

Separazione modello di input/output. La guida mostra come dividere l’entità in un modello di input di sola scrittura e un modello di output di sola lettura sulla stessa tabella, con sicurezza per costruzione: una colonna non dichiarata non può essere scritta, quindi niente più MVCDoNotDeserialize sparsi per la classe.

Chiavi primarie composite. Tabelle ponte, righe di dettaglio, record per tenant: tutte le tabelle in cui la chiave vera è due o più colonne. La guida mostra il supporto completo alle chiavi composite della 3.5: dichiarazione, le API plurali, il metodo Load senza posizioni, chiavi con tipi misti, colonne autogenerate dentro la chiave, i quattro punti in cui il framework solleva un’eccezione esplicita invece di indovinare, e il pattern di upsert atomico con SQL per backend per quando la race condition load-then-insert conta.

Generazione di entità. MVCEntGen genera le entità dai metadati del database con un riferimento .env completamente commentato (ogni chiave spiegata). La guida mostra il pattern CLASS_AS_ABSTRACT per aggiungere logica nelle sottoclassi senza toccare il file generato, le liste READONLY_COLUMNS / REFRESH_COLUMNS, e le particolarità per motore (tipizzazione NUMBER di Oracle, generator di InterBase, AUTOINCREMENT di SQLite dentro chiavi composite).

Pattern repository. Quando l’architettura chiede interfacce e dependency injection, la guida mostra IMVCRepository<T>, la stessa superficie funzionale di TMVCActiveRecord dietro un’interfaccia iniettabile, con tutto quello che già conosci che si applica senza cambiamenti (hook, validazione, change tracking, named query, chiavi composite, transazioni). Include un esempio di test con mock che mostra come il repository renda testabile un’entità, cosa che i metodi statici di TMVCActiveRecord non permettono.

Sull’autorevolezza dei due pattern

Active Record e Repository non sono invenzioni del framework: sono pattern catalogati da Martin Fowler in Patterns of Enterprise Application Architecture (Addison-Wesley, 2003), ancora oggi il riferimento per l’architettura software enterprise. Conoscerli per nome, sapere quando usare l’uno o l’altro, e saperli implementare correttamente è una competenza che vale su qualsiasi stack, non solo in Delphi.

“Active Record uses the most obvious approach, putting data access logic in the domain object. This way all people know how to read and write their data to and from the database.”

Martin Fowler, Patterns of Enterprise Application Architecture

“A Repository mediates between the domain and data mapping layers, acting like an in-memory domain object collection. Repository also supports the objective of achieving a clean separation and one-way dependency between the domain and data mapping layers.”

Martin Fowler, Edward Hieatt, Rob Mee, Patterns of Enterprise Application Architecture

Questa guida ti mostra come entrambi i pattern sono implementati in DelphiMVCFramework, con la ragione dietro ogni scelta e i trade-off spiegati. Sapere il pattern è il primo passo; saperlo usare bene sul tuo database, con il tuo team, è quello che la guida ti insegna.

Un assaggio: le chiavi primarie composite nella 3.5

Per anni, TMVCActiveRecord aveva un’opinione sulle chiavi primarie che non accettava discussioni: una sola colonna, e ti adeguavi. Metti foPrimaryKey su un secondo field e il framework ti fermava all’avvio con un messaggio blunt sul fatto che una PK di troppo è una PK di troppo.

La regola teneva il pattern semplice. Lasciava anche fuori casa un tipo di tabella comunissimo: la tabella ponte e qualsiasi entità la cui identità è naturalmente fatta di due o più colonne. user_roles(user_id, role_id), una riga d’ordine chiavata da (order_id, line_no), un record per-tenant chiavato da (tenant, code). Dappertutto.

A partire dalla 3.5 non devi più scegliere. ActiveRecord mappa direttamente la chiave composita naturale, con la comodità di GetByPKs e tutto il resto. Si dichiara marcando ogni colonna della chiave con foPrimaryKey, esattamente come già facevi con una sola:

[MVCTable('user_roles')]
TUserRole = class(TMVCActiveRecord)
private
  [MVCTableField('user_id', [foPrimaryKey])]
  fUserID: Integer;
  [MVCTableField('role_id', [foPrimaryKey])]
  fRoleID: Integer;
  [MVCTableField('note')]
  fNote: NullableString;
public
  property UserID: Integer read fUserID write fUserID;
  property RoleID: Integer read fRoleID write fRoleID;
  property Note: NullableString read fNote write fNote;
end;

E si indirizza per chiave con le controparti plurali dei metodi che già conosci:

lRole := TMVCActiveRecord.GetByPKs<TUserRole>([1, 42]);
try
  // ...usa lRole...
finally
  lRole.Free;
end;

Il walkthrough completo (dichiarazione, API plurali, il metodo Load senza posizioni, chiavi con tipi misti, colonne autogenerate, i quattro guardrail dove il framework solleva eccezione, l’upsert atomico per backend e l’indirizzamento URL nel controller auto-CRUD con array JSON) è nella guida. Il post pubblico che annuncia la feature è sul blog.

A chi è rivolta (e perché non puoi non leggerla)

Se usi TMVCActiveRecord, o pensi di usarlo, questa guida fa risparmiare tempo e soldi. Non è un extra per chi vuole approfondire: è ciò che ti serve per conoscere il framework a fondo, prima di mandarlo in produzione. La guida ti mostra cosa fa davvero ogni funzionalità, come si combina con le altre, e perché è progettata così: la trappola silenziosa di foDoNotSelect, il funzionamento dello snapshot con foRefresh + foDoNotInsert, il pattern multi-tenant con MVCPartition, la separazione modello di input/output che sostituisce una dozzina di MVCDoNotDeserialize, e il supporto completo alle chiavi composite della 3.5, che rimuove il vincolo della chiave a colonna singola per cui hai sempre fatto workaround.

Una serata di lettura, mesi di tempo risparmiato. 130 pagine si leggono in una serata, e ogni funzionalità che scopri già pronta è codice che non scrivi, un bug che non apri, una domanda di Stack Overflow che non fai. Solo il capitolo sul soft delete o quello sul lock ottimistico, da soli, ripagano il tempo di lettura la prima volta che li usi sul serio. La guida copre in una sera quello che si impara in mesi di tentativi in produzione, e lo fa con la ragione di design dietro ogni scelta, non solo il come.

Se invece usi, o vuoi usare, il pattern Repository (IMVCRepository<T>), la guida è ancora più obbligatoria. Il repository è la superficie di TMVCActiveRecord dietro un’interfaccia iniettabile: tutto quello che già conosci si applica senza cambiamenti, hook, validazione, change tracking, named query, chiavi composite, transazioni. La guida mostra come usarlo per testare con i mock (il repository rende testabile un’entità, cosa che i metodi statici di TMVCActiveRecord non permettono), e perché la dependency injection su IMVCRepository<T> è la via pulita quando l’architettura chiede interfacce.

Se non usi ancora ActiveRecord, questo è il modo più veloce per valutarlo. Vedi tutta la superficie funzionale in una sola lettura, con la razionale di design dietro ogni scelta, i trade-off spiegati onestamente, e i pattern che il codebase del framework stesso usa.

Cosa non è

È una guida opinionata, non un elenco di metodi: ti dice quale funzionalità usare quando, come si combina con le altre, e perché è progettata così. Ogni affermazione è verificata contro il codice sorgente del framework, non contro la memoria.

Dettagli

Licenza

Esclusiva Patreon. Non ridistribuibile. I termini completi della licenza sono all’interno della guida. Ricevendola hai il diritto di leggerla, stamparla e usarla nel tuo lavoro, per te. Non hai il diritto di ripubblicarla, caricarla su siti, blog, forum, canali, repository o piattaforme di condivisione, né di tradurla o riadattarla, anche senza scopo di lucro e anche citando la fonte. Se un contenuto ti è stato utile e vuoi condividerlo, condividi il link alla pagina Patreon, non il file.

Come accedere

La guida è disponibile solo attraverso Patreon, ma non devi essere già un membro per acquistarla. Su Patreon puoi comprare la guida come prodotto singolo nello shop, oppure scegliere un abbonamento al tier che la include (insieme agli altri contenuti premium). In entrambi i casi l’accesso è immediato dopo l’acquisto.

Questa pagina riguarda l’edizione italiana (ActiveRecord: la Guida Completa, versione 1.2). Per l’edizione inglese, vedi la pagina inglese. Per accedere all’edizione italiana:

Se non sai quale opzione scegliere (acquisto singolo o abbonamento), scrivi a d.teti@bittime.it.

Domande frequenti

Cosa copre la guida?

TMVCActiveRecord per intero: mappatura, connessioni, CRUD, API di lettura (GetByPK, Where, Select, RQL, named query), transazioni, hook del ciclo di vita, validazione, colonne di audit, change tracking, soft delete, lock ottimistico, multi-tenant, separazione modello input/output, pattern repository, controller auto-CRUD, generatore MVCEntGen, e la novità della 3.5, le chiavi primarie composite dall’inizio alla fine. Più quattro appendici: riferimento dei metodi, note sul funzionamento interno, FAQ e DDL di ogni esempio.

A chi è rivolta?

A sviluppatori Delphi che già usano ActiveRecord e vogliono scoprire cosa gli manca, e a chi non lo usa ancora e vuole valutarlo in una sola lettura. Presuppone conoscenza base di Delphi/Object Pascal.

In che lingua è disponibile?

In italiano e in inglese, entrambe alla versione 1.2. Scegli l’edizione che preferisci su Patreon: italiano o inglese. Se ti interessa un’altra lingua oltre queste due, scrivi a d.teti@bittime.it: le traduzioni aggiuntive partono dalle richieste.

Quanto è lunga?

Circa 130 pagine in PDF, più il DDL completo di ogni tabella di esempio in appendice, così puoi far girare tutto su un database vuoto senza inventarti le tabelle.

Su quale versione del framework si basa?

DelphiMVCFramework 3.5.0-silicon. Ogni affermazione è verificata contro il codice sorgente del framework, non contro la memoria.

Posso ridistribuirla?

No. La guida è esclusiva Patreon e la licenza vieta esplicitamente ripubblicazione, caricamento, traduzione e riadattamento, anche senza scopo di lucro. Puoi condividerla solo come link alla pagina Patreon.

Dove la trovo?

Su Patreon, nell’area post riservata ai sostenitori del tier che include la guida: edizione italiana. Per l’edizione inglese vedi la pagina inglese.

L’autore

Daniele Teti è il creatore e lead developer di DelphiMVCFramework, il framework open source più popolare su GitHub per lo sviluppo di API REST e JSON-RPC in Delphi. Con oltre 25 anni di esperienza nello sviluppo di sistemi enterprise in ambiti che vanno dalla logistica al finance, dall’healthcare all’industria manifatturiera, ha una prospettiva non accademica sul software: conosce cosa vuol dire mantenere sistemi critici per anni, con team reali, scadenze reali e budget reali.

È autore della serie Delphi Cookbook (PacktPub, tre edizioni) e di DelphiMVCFramework - The Official Guide. Questa guida nasce dal lavoro sul framework stesso: ogni affermazione è verificata contro il codice sorgente, non contro la memoria.

Per consulenze e formazione: bittimeprofessionals.it

← Torna a tutti i libri