liveBook · Manning

Invariant

As explained in Clean Applications with Hexagonal Architecture

A condition that must remain true for a domain object or business state to be valid.

When business checks are scattered across handlers, persistence code, and controllers, a new path can bypass them. An invariant is a condition that must hold for a domain object or business state to be valid. Rules that remain true regardless of deployment or framework belong in the domain core, not in infrastructure adapters. section 3.1 section 2.3.2

An always-valid domain model enforces creation invariants before an object exists. Give the entity a private constructor and expose a factory such as validateThenCreate. The factory returns an error when validation fails rather than returning an invalid entity. Creating first and validating afterward leaves a window in which an invalid object exists; putting the rule in a handler leaves the entity dependent on callers remembering the check. section 3.3 section 3.3.1

Creating an article

A creation handler looks up the author through an output port, passes the result to Article.validateThenCreate, and saves the article only if creation succeeds. The handler coordinates the steps; the domain owns the rules that make an article valid. The port keeps the author lookup independent of its external implementation. section 1.3 section 2.3.2

Listing 1.3 Orchestration to implement the use case
@Override
public Either<Error, Void> handle(final CreateArticleCommand command) {
  return this.authorOutputPort
➥.lookupAuthor(command.authorId()) // #A
    .flatMap(author -> 
➥ Article.validateThenCreate( // #B
      command.id(), command.title(), command.content(), author).toEither())
    .flatMap(this.articleRepository::save); // #C
}

Follow the lookup, validation, and save chain in the creation handler. section 1.3

Construction is only one boundary. An Article remains the same entity across valid state changes, and Article.publish() enforces the draft-status rule rather than asking the handler to decide it. For an aggregate with child entities, route child changes through aggregate-root operations so they can preserve invariants across the whole consistency boundary. section 3.1 section 4.4.2 section 9.2.5

Keep the domain framework-free: adapters translate framework-shaped data into commands or value objects, while the domain exposes its valid creation path. An entity with only fields and getters cannot enforce its own invariants; it is a data bag rather than a behavior-rich domain entity. section 3.3.1 section 2.4.1

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains construction-time validation, domain state transitions, and aggregate-wide consistency, including the risks of validating after construction.
Examples
Uses article creation, author lookup, title validation, and draft-status enforcement to illustrate invariant ownership.
What you can do after
Build domain entities with validating factories and place state-change rules in domain operations.
How it connects
Connects invariants to entities, value objects, aggregates, factory methods, and the always-valid domain model.

Also explained in

Compare how 18 books explain invariant →

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.