When a service mixes business decisions, persistence details, and framework calls, even a small change can cross several boundaries. A handler separates the use-case orchestration from those details. It implements an input port, receives a command or query, coordinates domain objects and output ports, and returns the outcome. section 4.4.1 section 8.4
The handler belongs inside the application core. It depends on port interfaces, not adapter implementations: the core states what it needs in domain language, while adapters decide how to fulfill that need. Business invariants belong in the domain model; persistence mechanics belong in the adapter. Calling an adapter directly bypasses the boundary even if a port interface exists. section 2.3.2 section 2.4.4 section 4.4.2
Publishing an article
A publish handler reads an article through a repository port, asks the article to publish itself, and saves the result. The aggregate checks its own status and ownership rules. Each step returns an Either: success continues the chain, while a typed error stops it and reaches the caller. section 4.4.1 section 4.4.2 section 4.2.2
Listing 4.10 PublishArticleHandler implementing the use case directly
@ApplicationService #A
@RequiredArgsConstructor
final class PublishArticleHandler implements PublishArticleUseCase {
private final ArticleRepository articleRepository; #B
@Override
public Either<Error, Void> handle(final PublishArticleCommand command) {
return this.articleRepository
.readById(command.articleId()) #C
.flatMap(article -> article.publish(command.authorId())) #D
.flatMap(article -> this.articleRepository.save(article)); #E
}
}
The listing shows the complete read–publish–save chain and its dependency on a repository abstraction. section 4.4.1
A command handler returns Either<Error, Void>; a query can return a result. Keeping domain entities out of command return types prevents adapters from depending on internal structure. Transaction boundaries attach to the handler because it knows the scope of the use case. Use a core-owned, technology-agnostic marker and let runtime infrastructure implement it; in the demonstrated setup, rollback for returned Either errors must be configured explicitly. section 4.4.3 section 6.3.4 section 9.4
Keep secondary reactions out of the primary handler. After saving an aggregate, the handler can publish events generated by the domain through an output port. Separate listeners then trigger additional use cases without making the handler responsible for notifications, statistics, or analytics. section 4.7.1 section 4.7.2
Keep the boundary executable:
- Construct the handler directly with mocked ports or small fakes. Assert the Either result, and verify interactions when ordering or short-circuiting is part of the contract. section 8.4
- Use dependency rules to reject imports from adapters and persistence frameworks. Structural checks complement, rather than replace, behavioral tests. section 7.3.3 section 8.0
- During migration, extract orchestration from an existing service, define ports around current needs, and wrap existing infrastructure as adapters. For simple CRUD or prototypes, weigh this extra structure against its cost. section 1.2.6

