Using one entity for HTTP, domain behavior, and persistence saves conversion code, but makes the API and database depend on the domain’s internal shape. A mapper converts between representations at a boundary so each type can serve its own purpose. More separation means more types and mapping work; fewer types mean more coupling. section 5.4 section 5.4.2
A practical baseline separates the domain entity from the persistence entity. The repository adapter maps between them, while a handler maps domain results to DTOs for consumers. The domain stays free of persistence annotations; the persistence model can satisfy ORM requirements without adding setters or a no-argument constructor to the aggregate. section 5.4.4 section 9.5.1
Mapping an article for persistence
An ArticlePersistenceMapper in the persistence adapter converts an Article to a JpaArticle by extracting primitive values. In the other direction, it builds domain value objects from the stored fields and calls Article.reconstitute. The repository adapter uses the mapper around its Spring Data collaborator, which works with JpaArticle rather than the domain contract’s Article. section 9.5.1
Listing 9.24 ArticlePersistenceMapper: The two-way translator
@Component
class ArticlePersistenceMapper {
JpaArticle toJpaEntity(final Article article) { #A
return new JpaArticle(
article.id().value(),
article.title().value(),
article.content().value(),
article.authorId().value(),
article.status().name());
}
Article toDomainEntity(final JpaArticle jpaArticle) { #B
return Article.reconstitute(
ArticleId.validateThenCreate(jpaArticle.getId())
.get(), #C
Title.validateThenCreate(jpaArticle.getTitle()).get(),
Content.validateThenCreate(jpaArticle.getContent()).get(),
AuthorId.validateThenCreate(jpaArticle.getAuthorId()).get(),
ArticleStatus.valueOf(jpaArticle.getStatus())); #D
}
ArticleDTO toDTO(final JpaArticle jpaArticle) { #E
return new ArticleDTO(
jpaArticle.getId(),
jpaArticle.getTitle(),
jpaArticle.getAuthorId(),
jpaArticle.getStatus());
}
}
The mapper shows both persistence directions and a direct persistence-to-DTO conversion. section 9.5.1
Reconstitution is a trusted persistence path, not the guarded factory for creating new articles. Its public visibility permits the adapter in another module to call it, but also exposes a way to bypass aggregate validation. If persisted values can outlive changing validation rules, plan a migration or an explicit legacy-data strategy. section 9.5.1
A full bridge goes further: request, command or query, domain, persistence, DTO, and response each have distinct types, with explicit mapping at boundaries. This maximizes isolation between models that evolve for different audiences, at the cost of maintaining more types and mappers as fields change. section 5.4.5
A query that uses domain behavior
A publication-readiness query loads the Article aggregate because the answer depends on domain rules. The handler assesses readiness and maps the result to a DTO; the controller maps that DTO to an HTTP response. The operation remains read-only even though it uses the domain model. 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 listing shows the repository lookup, domain behavior, and DTO mapping in sequence. section 5.4.5
