When an API, domain model, and persistence schema share types, a change in one can spread across the application. A full bridge gives each boundary its own representation and uses explicit mappers between them. Each type has one purpose rather than serving multiple layers. section 5.4.5
A full bridge can use six kinds of type:
- Request: external input received by an adapter. section 5.4.5
- Command or query: input accepted by the application layer. section 5.4.5
- Domain entity: the model used for domain behavior. section 5.4.5
- Persistence entity: the representation stored by a repository adapter. section 5.4.5
- DTO: a carrier for query results. section 5.4.5
- Response: external output returned by the input adapter. section 5.4.5
Publication-readiness query
A GET endpoint receives an article identifier and creates a query. The handler validates a domain identifier, loads the article through a repository, and asks the aggregate to assess publication readiness. A mapper turns the result into a DTO; the controller turns that DTO into a response. The operation is read-only, but it needs domain behavior rather than a simple projection of stored fields. section 5.4.5
Listing 5.15 Full Bridge: Inside the query handler
@ApplicationService
@RequiredArgsConstructor
final class PublicationReadinessHandler
implements PublicationReadinessUseCase {
private final ArticleRepository articleRepository;
private final PublicationReadinessMapper mapper; #A
@Override
public Either<Error, PublicationReadinessDTO>
handle(final PublicationReadinessQuery query) {
return ArticleId.validateThenCreate(query.articleId())
.flatMap(this.articleRepository::readById) #B
.map(Article::assessPublicationReadiness) #C
.map(this.mapper::toDTO); #D
}
}
The handler shows the repository lookup, domain assessment, and DTO mapping in sequence. section 5.4.5
The extra isolation costs types and mappers. It is useful when external contracts are public, multiple teams share a codebase, or the system must evolve for years. For most applications, two-way mapping is a pragmatic default: it separates domain and persistence types without adding separate request and response types. section 5.4.5 section 5.4.6
Table 5.2 Mapping strategies: trade-offs across five dimensions
|
Strategy
|
Types at boundary
|
Isolation
|
Mapper effort
|
Change propagation
|
When to use
|
|
No mapping
|
1 (domain entity everywhere)
|
None
|
None
|
Every change cascades everywhere
|
Prototypes, throwaway scripts
|
|
One-way
|
2 (domain + DTO)
|
API decoupled, persistence coupled
|
Low
|
Persistence changes force domain changes
|
Simple persistence, document stores
|
|
Two-way
|
3 (domain + persistence + DTO)
|
API and persistence decoupled
|
Medium
|
Changes contained per boundary
|
Most applications – reasonable default
|
|
Full Bridge
|
6 (request + command + domain + persistence + DTO + response)
|
Complete
|
High
|
Changes always local
|
Large teams, public APIs, long-lived systems
|
Compare isolation, mapper effort, and change propagation across the four mapping strategies. section 5.4.6
