Spring Data Architecture

It generates a proxy at start-up. Boot's auto-configuration, or @EnableJpaRepositories, scans the base packages for interfaces extending Repository and registers a JpaRepositoryFactoryBean definition for each one. When that factory bean is initialised, it creates a JpaRepositoryFactory with a shared, transaction-aware EntityManager and the repository's metadata: domain type, id type and declared methods. The factory instantiates the base implementation, normally SimpleJpaRepository, discovers custom fragment implementations, and resolves a RepositoryQuery for every query method, validating them early. Finally it builds a JDK dynamic proxy for the interface with interceptors for exception translation, transactions, query execution and dispatch to the base or fragment implementation. The bean you inject is that proxy; you never write an implementation class.

SimpleJpaRepository is Spring Data JPA's default base implementation, the class that actually implements the methods inherited from CrudRepository, ListCrudRepository, PagingAndSortingRepository and JpaRepository, such as save, findById, findAll with paging, deleteById and count. Every repository proxy delegates those calls to an instance of it, created per repository with the entity's metadata and an EntityManager. It is annotated @Transactional(readOnly = true) at class level, with write methods overriding that, which is why repository calls are transactional even without a service transaction. One detail worth knowing: save() calls persist() for new entities and merge() otherwise, deciding newness from the id, a version attribute or the Persistable interface, so always use the returned instance.

The default is CREATE_IF_NOT_FOUND. For each query method, Spring Data first looks for a declared query: an @Query annotation on the method, or a named query matching the convention Entity.methodName, for example in orm.xml or a @NamedQuery. If one exists it is used; otherwise the query is derived from the method name by the PartTree parser. The alternatives are USE_DECLARED_QUERY, which fails start-up if a method has no declared query, and CREATE, which always derives from the name and ignores named queries. The strategy is set with the queryLookupStrategy attribute of @EnableJpaRepositories. The default suits most teams; USE_DECLARED_QUERY suits teams that want every query visible and reviewed.

@NoRepositoryBean tells Spring Data not to create a repository bean for an interface that would otherwise be picked up by scanning. It is meant for intermediate interfaces, such as a generic BaseRepository<T, ID> that adds shared methods for all your repositories. Without it, Spring Data tries to create a repository for the generic interface itself, cannot determine a concrete domain type, and fails at start-up. Spring Data uses the same annotation on its own hierarchy: CrudRepository, ListCrudRepository, PagingAndSortingRepository and JpaRepository are all marked @NoRepositoryBean. Concrete repositories that extend the intermediate interface with real type arguments, such as OrderRepository extends BaseRepository<Order, UUID>, are still detected and created normally.

Use a repository fragment. Declare an interface with the custom methods, for example OrderSearchFragment with search(OrderSearch criteria), and implement it in a class named after the interface with the Impl postfix, OrderSearchFragmentImpl. The implementation is a normal Spring bean, so it can have an EntityManager, JdbcClient or Querydsl factory injected through its constructor and use Criteria, native SQL or batch operations. Then let the repository interface extend the fragment interface as well as its base interface. The proxy routes fragment methods to your implementation, and fragment methods even take precedence over base methods with the same signature, so you can customise save. A misnamed Impl class makes Spring try to derive a query instead.

Normally at start-up, when the repository is created. The lookup strategy resolves every query method: derived methods are parsed by PartTree and their properties checked against the entity model, so findByCustomer on an entity without a customer property fails with a QueryCreationException naming the method. Declared JPQL in @Query is also validated, because Hibernate parses it when the query is created. Two exceptions matter. Native queries are not validated until they execute, so only tests catch SQL errors. And with spring.data.jpa.repositories.bootstrap-mode set to lazy, repositories are initialised on first use, so the error moves to the first request. Deferred mode still initialises them before the application is ready.

Create a custom base repository. Define a generic interface marked @NoRepositoryBean, for example BaseRepository<T, ID> extending ListCrudRepository<T, ID>, with the shared method such as getRequired(ID id). Implement it in a class that extends SimpleJpaRepository<T, ID> and has a constructor taking JpaEntityInformation and EntityManager, which Spring Data calls reflectively. Register it with @EnableJpaRepositories(repositoryBaseClass = BaseRepositoryImpl.class), and let concrete repositories extend BaseRepository. Every repository proxy then uses your class as its target, so the method is available everywhere. Keep base classes generic, such as soft-delete helpers or required lookups. If only some repositories need the behaviour, a reusable generic fragment is the more flexible choice than changing every repository's base.

In ports-and-adapters terms, the repository interface is a port: a domain-owned contract expressed in domain language, such as findOverdueInvoices or save(Order), with aggregate roots as types. Spring Data generates the adapter at runtime from that contract, so the domain never sees EntityManager, SQL or driver APIs. Fragments and custom base classes extend the adapter side when generated queries are not enough, again without changing the port. The architecture holds only if interfaces stay domain-focused: exposing JPA-specific types, Specification or Pageable deep in the domain leaks the adapter. Done well, you can move an aggregate from JPA to JDBC or a document store by changing the adapter module, and test the domain with in-memory implementations.