A repository can provide a useful boundary between application logic and persistence. It becomes harmful when it hides important query behavior behind generic methods or imitates an in-memory collection.
Define repositories around aggregates or use cases
Methods should communicate intent, such as finding an active subscription or saving an order. Avoid a large generic repository with dozens of methods that expose every possible query shape.
Keep performance visible
A method named findAll() can be dangerous if it loads an unbounded dataset. Include pagination, filtering, and expected result size in the contract. For reporting or specialized read paths, a dedicated query service may be clearer than forcing everything through an aggregate repository.
Manage transactions deliberately
Repositories should not silently open and commit independent transactions when a use case requires several writes to succeed together. Define transaction ownership at the application-service or unit-of-work boundary.
Avoid leaky abstractions
Do not return raw database cursors or provider-specific query builders from a supposedly abstract repository. At the same time, do not hide necessary database-specific optimization when it is important to correctness or scale.
Checklist
- Model methods around application intent.
- Make pagination and result limits explicit.
- Define transaction ownership clearly.
- Use query services for specialized read models.
- Keep database-specific behavior documented.