02 - Entités, Value Objects et identité

Ce que tu vas apprendre

• Ce qu'est une entité et pourquoi l'identité est centrale
• Ce qu'est un Value Object et quand l'utiliser
• La différence entre un DTO et une entité
• Comment choisir entre entité et Value Object

Prerequisites

• 01 - Le domaine métier

L'entité : un objet avec une identité persistante

Une entité est un objet métier qui possede une identité unique et persistante. Cette identité (généralement un id) ne change jamais, meme si tous les autres attributs changent.

Exemple concret : une Place dans le domaine "Cycle de vie Place". Cette Place a un id (disons place_42). Meme si tu changes son nom, sa description, ses images, ses categories -- c'est toujours la meme Place. L'identité survit aux modifications.

typescript// C'est la meme entite, meme si tout a change
const placeAvant = { id: "place_42", name: "Cafe de Flore", status: "DRAFT" };
const placeApres = { id: "place_42", name: "Cafe de Flore - Paris", status: "ENRICHED" };
// placeAvant et placeApres representent la MEME entite

Comment savoir si c'est une entité ?

Pose-toi cette question : "est-ce que deux objets avec les memes attributs mais des id différents sont la meme chose ?"

• Deux Place avec le meme nom mais des id différents = deux Places différentes. --> C'est une entité.
• Deux adresses "12 rue de Rivoli, Paris" = la meme adresse. --> Ce n'est PAS une entité (c'est un Value Object, on y vient).

Le Value Object : défini par ses attributs

Un Value Object (objet-valeur) est un objet défini entièrement par ses attributs. Il n'a pas d'identité propre. Deux Value Objects avec les memes attributs sont identiques et interchangeables.

Exemples classiques :

• Une adresse : "12 rue de Rivoli, 75001 Paris". Si deux objets ont exactement ces valeurs, c'est la meme adresse.
• Une couleur : { r: 255, g: 0, b: 0 }. Deux rouges identiques sont le meme rouge.
• Un montant : { value: 19.99, currency: "EUR" }. Deux montants identiques sont le meme montant.
• Des coordonnees GPS : { lat: 48.8566, lng: 2.3522 }.

typescript// Value Object : pas d'id, defini par ses attributs
type Address = {
  street: string;
  city: string;
  zipCode: string;
  country: string;
};

// Ces deux adresses sont identiques (meme valeur)
const a1: Address = { street: "12 rue de Rivoli", city: "Paris", zipCode: "75001", country: "FR" };
const a2: Address = { street: "12 rue de Rivoli", city: "Paris", zipCode: "75001", country: "FR" };
// a1 et a2 representent la MEME chose

Propriétés d'un Value Object

• Immutable : on ne le modifie pas, on en créé un nouveau
• Pas d'identité : pas de champ id
• Egalite par valeur : deux objets avec les memes champs sont egaux
• Remplacable : on peut substituer un Value Object par un autre identique sans consequence

Et le DTO dans tout ca ?

Un DTO (Data Transfer Object) est un objet qui sert uniquement a transporter des donnees entre deux couches du système (par exemple entre une API et le frontend, ou entre un service et un controller).

Un DTO n'est PAS une entité. Il n'a pas de comportement métier, pas de cycle de vie, pas d'invariants. C'est un "sac de donnees".

typescript// C'est un DTO : il transporte des donnees, il n'a pas de logique metier
type CreatePlaceDTO = {
  name: string;
  latitude: number;
  longitude: number;
  googlePlaceId: string;
};

// C'est une entite : elle a une identite, un etat, des regles
type PlaceEntity = {
  id: string;
  name: string;
  status: "DRAFT" | "ENRICHED" | "PUBLISHED";
  images: ImageAsset[];
  categories: Category[];
  createdAt: Date;
};

La confusion classique : utiliser un DTO comme entité. On recoit des donnees d'une API, on les stocke telles quelles, et on essaie de raisonner dessus comme si c'etait une entité métier. Ca ne marche pas, parce que le DTO ne porte ni identité persistante, ni regles de transition.

Quand utiliser quoi ?

Dans le domaine Place :

• Place est une entité (elle a un id, un cycle de vie, des transitions d'état)
• Address est un Value Object (définie par ses champs, pas d'identité propre)
• CreatePlaceDTO est un DTO (il transporte les donnees du formulaire vers le backend)

Résumé

• Une entité a une identité persistante (un id). Meme si ses attributs changent, c'est le meme objet.
• Un Value Object est défini par ses attributs. Pas d'identité, immutable, remplacable.
• Un DTO est un sac de donnees pour le transport. Ce n'est ni une entité, ni un Value Object métier.
• Bien distinguer ces trois concepts évité de melanger logique métier et logique technique.

Article précédent : 01 - Le domaine métier Article suivant : 03 - Le cycle de vie d'une entité

Sources

• Martin Fowler - Value Object
• Eric Evans - Domain-Driven Design Référence
• Khalil Stemmler - Understanding Domain Entities