メシのタネ

メシのタネになる、AIや技術総合情報のサイト


Repository or Query Service? Start With the Question


  1. English
  2. Repository or Query Service? Start With the Question
A ledger of blue tiles with a dotted route drawn on a separate tracing sheet.

広告

日本語版

I've lost count of the pull request reviews that ended with “That's just personal preference.” Somebody asks whether an operation belongs in a repository. Somebody else says “It's read-only, why make a whole Query Service?” And that's the meeting.

I don't think the disagreement is about taste. I think we've started the sentence with the wrong subject.

What the architecture gives you

Domain-Driven Design (DDD) gives us a vocabulary for modeling the business. An entity has an identity. An aggregate groups state that has to stay consistent. A repository lets us retrieve and persist aggregates in terms the domain understands.

Clean Architecture asks where the dependencies point. A business rule should be able to outlive the UI or framework that calls it. That's a different concern from deciding what an aggregate means. Both ideas help, but quoting either of them in a review still leaves you with the actual decision.

Start with what the question is about

Try saying out loud what the method answers. Are we asking what is true in the domain right now? Or are we asking what someone can do in this particular operation?

A repository might load an account and tell you that it has an outstanding balance. A screen or API might ask whether the person making this request can close that account right now. The second question has a caller and a workflow attached to it.

That's why “it only reads” doesn't settle anything. Reading data is the mechanism. The question being answered is the responsibility.

Can this user close their account?

Suppose we need to determine whether an account can be closed. The answer might depend on unpaid invoices, records we still have to retain, who is making the request, or whether it came through the self-service screen or an admin workflow.

The account status and balance are facts. A rule like “an account with an outstanding balance can't be closed” may be an invariant of the domain. Which actions to show an admin, how to explain a restriction to a customer, and which related records the preview needs are questions about this workflow.

If a repository starts accepting the caller's role or the screen that initiated the request, pay attention. A decision about a workflow is finding its way into an API that other callers expect to describe domain state. That's how you get a method that's supposedly “just a read” and takes half the request as input.

What a Query Service is for

A Query Service can read across aggregates and return the shape a use case needs. The account-closure screen could get a status, a list of reasons, and enough detail to display them. The service can consult domain rules and caller permissions where appropriate.

The command that actually closes the account still has to enforce its rules when it runs. The preview can go stale between the time someone opens the screen and the time they click Confirm.

Next time the debate stalls, ask what has to be true for the answer to change. A change in the state of the account and a change in who's asking tell you different things about where the decision belongs.

Q&A

Does every read need a Query Service?

No. Loading an aggregate by its identity is a natural repository operation. A Query Service earns its place when the caller needs a use-case-specific answer, such as an eligibility summary assembled from several sources.

Where should eligibility rules live?

Put business rules that apply to every caller in the domain. An application service can combine those rules with caller permissions and workflow context. Enforce the relevant rules again when the action is carried out.

Can a Query Service read directly from the database?

It can if that fits your architecture. For a read model, a query that joins several tables can be simpler than rehydrating every aggregate. Its contract should still describe what the caller needs, and the write path should retain its domain checks.

If you want a way to spell out where a decision stops applying, see How far does this design decision apply?.