liveBook · Manning

Entity

As explained in Clean Applications with Hexagonal Architecture

A domain object with an identity whose state and invariants are governed by domain rules.

When validation lives in controllers or message consumers, each adapter can develop a different version of the same rule. A domain entity keeps that behavior in the core: it has a distinct identity that persists across valid state changes, and it enforces the invariants governing those changes. section 2.4.7 section 3.1

Entities belong in the innermost domain layer, independent of frameworks and delivery mechanisms. Unlike an entity, a value object is defined by its attributes rather than identity. An aggregate groups entities and value objects as a unit for state changes; a domain service handles logic spanning multiple entities. section 3.1 section 3.10

An always-valid entity cannot be constructed in an invalid state. Keep the constructor private and use a factory method to validate invariants before creation; return errors rather than an invalid object. For complex construction involving identity generation or external lookups, use a separate factory class. Vavr's Validation can collect multiple errors at once. section 3.3 section 3.10

Article identity and validation

An Article keeps its ArticleId as its attributes change. Its aggregate includes Title, Content, and a reference to Author. Title validation belongs in the domain, not separately in REST, Kafka, and GraphQL adapters, so every entry point applies the same rule. section 3.1 section 2.4.7

Keep the boundary enforceable:

  • Extract business rules from framework-annotated classes, not just fields and getters. An entity that cannot enforce its invariants is an anemic data bag. section 2.4.1
  • Use commands, queries, and DTOs to mediate external interactions. Returning and persisting the domain entity directly couples its API and persistence representation to its behavior. section 3.1 section 5.4.2
  • Test with real domain entities rather than mocks, so validation and state transitions execute. Test handler orchestration separately from domain construction. section 8.7

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Defines identity and invariants, then details factory-based validation, boundary mapping risks, and testing responsibilities.
Examples
Uses Article and ArticleId to illustrate persistent identity, Title validation, and an aggregate referencing Author.
What you can do after
Build domain entities from scratch with factory-enforced invariants and keep their rules independent of adapters.
How it connects
Connects entities to value objects, aggregates, domain services, factory methods, and hexagonal architecture.

Also explained in

Compare how 14 books explain entity →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.