Repository Pattern

Repository Pattern

Purpose

Provide a collection-like boundary between domain objects and data mapping. Fowler's Repository includes queries over domain objects; it does not universally require one DDD aggregate root or prohibit read projections. This skill emphasizes DDD write repositories: independent child writes must not bypass the root's invariants. Separate read gateways when their query shape, cost or ownership warrants it, and remove abstractions only when their contract and dependency boundary add no value.

The two failures are the layered nothing (Service → Repository → BaseRepository → GenericDao → ORM, with no layer adding behaviour) and the leaky everything (a repository leaking uncontrolled managed-state lifetimes or exposing Pageable, Specification and EntityManager, so the persistence technology is present everywhere it was supposed to be absent).

What a repository is, and is not

IS:     a collection-like interface over domain objects
        typically one aggregate root for DDD write access
            add / remove / find by identity / find by domain criteria
        expressed in domain types
        for a domain-facing port: domain/application owned, adapter implemented
        a participant in the use case's transaction, possibly with local defaults

IS NOT: a per-table data access object
        a home for business operations
        a requirement that every reporting/screen query hydrate an aggregate
        a portability layer over the database

Workflow

Inspect Java/toolchain, Spring Data/JPA/provider versions, transaction/proxy configuration and the existing mapping model before recommending APIs. The examples are partial Java 17 source shapes with application types omitted, not a complete Spring project. Spring metadata guidance was checked against Spring Data JPA 4.1.1 documentation. Adapt to the project baseline without adding libraries or upgrading Java for the example. Return the chosen write/read contract, object lifetime, transaction boundary and checks needed to prove it.

1. Identify aggregate consistency boundaries. A repository is normally per aggregate root. Dedicated child/query gateways may exist for bulk operations or read models without granting independent domain mutation (domain-logic-organization).
2. Write the interface in the domain's language, in domain types: Orders.byId, Orders.overdueFor(customer), Orders.save. Not OrderJpaRepository with findAllByStatusIn.
3. Choose the read path deliberately. Screens and reports can use projections or query gateways when aggregate loading is unsuitable. Spring Data projection methods or a small shared interface can also be appropriate; separation is a design choice, not the definition of Repository (query-objects-and-specifications).
4. Decide what crosses the boundary. Domain aggregates out; identifiers and domain values in. Choose managed aggregates confined to the transactional use case or mapped independent domain objects; controllers/serialization should receive an explicit read DTO.
5. Inspect business verbs for hidden policy. cancelExpired() must not hide eligibility, transitions or event rules in persistence code. A domain-defined bulk operation may be delegated only when its invariant, concurrency and effect semantics are preserved.
6. Ask whether the boundary earns its cost in this module. For a CRUD module with no aggregate and no invariant, direct Spring Data is a candidate if no distinct boundary contract is needed.

Decision rules

An aggregate root with invariants and an explicit persistence contract
        → one repository, domain-typed interface, implementation in the
          adapter. This is the pattern doing its job.

A child entity inside an aggregate
        → mutations go through the root's consistency rules. Internal persistence
          gateways and read projections are valid; independently callable writes
          bypassing the root require redesign (orm-structural-mapping).

Reads for a screen, a report, an export
        → consider a query object/projection without aggregate hydration;
          the interface name alone does not decide correctness.

A CRUD module: no invariants, entity ≈ table, no aggregate
        → direct Spring Data (or a gateway) is a candidate when no distinct
          domain/application port, capability limit or policy boundary is needed.

A domain-owned interface with a single adapter implementation whose
methods are identical to Spring Data's
        → the wrapper is indirection unless it is doing something: type
          translation, hiding framework types, or narrowing the surface.
          Narrowing IS a real justification; identical signatures are not.

A "generic repository" with type parameters serving every entity
        → reject a mandatory broad CRUD surface for unrelated aggregates.
          A narrow internal base for shared mechanics can coexist with
          domain-specific interfaces; judge the exposed capabilities.

Bulk or set-based work over the aggregate's table
        → a gateway with SQL, named as such, with its interaction with
          versioning and the persistence context handled explicitly
          (offline-concurrency-control).

Rules

• Prefer one domain repository per aggregate root. Per-table gateways are valid infrastructure for set-based/query work; the defect is exposing independent child mutation that bypasses aggregate invariants while calling it a domain repository.
• For a domain-facing port, the interface belongs to the domain/application abstraction and the implementation to the adapter. That is the inversion that makes the domain testable and the persistence replaceable, and it is a strong structural reason to hand-write the interface, alongside narrowing capabilities, domain-specific error semantics, testing seams and multiple adapters (layering-and-boundaries).
• Keep business policy in the domain/use case. orders.cancelExpired() deserves inspection for hidden eligibility, transition and event rules; the verb alone is not proof. A bulk adapter may execute a domain-defined operation only with equivalent invariant/concurrency and effect semantics explicitly established.
• Do not leak persistence types through the interface. Pageable, Specification, Sort, EntityManager, Page in a domain-owned interface mean the domain now depends on persistence frameworks, undermining the intended dependency boundary.
• Managed domain entities within a transactional use case are a valid JPA choice. Document dirty checking versus explicit save, detached results and lazy-access boundaries; transaction completion alone does not always end an extended persistence context. Map outward-facing DTOs before required lazy state becomes unavailable (orm-behavioral-patterns).
• Reads and writes have different requirements and may legitimately use different paths. Measure query counts, fetched rows/bytes and hydration before attributing slow screens to the repository structure (architecture-and-performance).
• existsBy(...) followed by save(...) is a race, not a check. Uniqueness is enforced by a constraint; the repository call only produces a better error message (enterprise-transactions).
• Repositories may provide local transaction defaults, but an outer application transaction usually joins/overrides them under REQUIRED. Without an outer boundary, two sequential repository calls can commit independently. Test the actual propagation and proxy path (service-layer-design).
• Spring Data supplies common repository mechanics, not the whole design. What remains a decision is the interface's shape, its ownership, and whether an aggregate boundary exists at all. extends JpaRepository<Order, Long> publishes a broad surface including deleteAll() — that is a surface decision, not a default.
• For Spring Data query/CRUD methods, configure @Lock/@QueryHints where its metadata machinery reads them. A custom fragment or direct EntityManager implementation must apply lock modes/hints explicitly or through a verified integration; an annotation alone does not change arbitrary Java code. Verify actual SQL and transaction scope.
• Remove forwarding layers only after checking capability narrowing, dependency ownership, transaction/authorization policy, error translation and test seams. An intentionally stable domain port can be valuable with one adapter and forwarding bodies (enterprise-architecture-smells).

References

• Repository boundaries — the domain-owned interface with its adapter implementation in Java, what the aggregate boundary means for the methods, reconstitution and detachment, read models beside the repository, and the narrowing that justifies a hand-written interface over Spring Data. Read when designing or reviewing a repository.
• Repository misuse — the layered nothing, the generic repository, business verbs, child-entity repositories, leaked framework and managed types, and the check-then-act race; each with detection and the concrete fix, plus when a thin wrapper is nevertheless correct. Read when auditing an existing data layer.