mapstruct-patterns

Enforce constructor-based MapStruct DTO mappings with compile-time validation.

Updated Feb 27, 2026
One-click install
npx skills add https://github.com/cooker/wx-apartment-ledger --skill mapstruct-patterns-cooker
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mapstruct-patterns
Source: https://github.com/cooker/wx-apartment-ledger/tree/main/.agents/skills/mapstruct-patterns
Command: npx skills add https://github.com/cooker/wx-apartment-ledger --skill mapstruct-patterns-cooker

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Constructor-based mapping enforces compile-time safety in MapStruct-powered DTO and entity mappings, catching constructor changes during build rather than at runtime.

Core Features & Use Cases

  • Enforces constructor-based mapping so changes to constructors cause compile-time errors, ensuring mapper correctness.
  • Supports CDI-based MapStruct integration and the custom @Default annotation to resolve multiple constructors safely.
  • Ideal for Jakarta EE projects where DTOs, entities, and records must map deterministically with strong type safety.

Quick Start

Configure your mapper with CDI and annotate the selected constructor with a Default-like annotation to enable compile-time safety.

Frequently Asked Questions about mapstruct-patterns

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enforce compile-time safety for MapStruct DTO mappings?▼

Enforce compile-time safety for MapStruct DTO mappings by using constructor-based mapping, which catches constructor changes during the build process rather than at runtime. This approach relies on MapStruct compile-time validation and a Default-annotation strategy.

Does MapStruct work with CDI componentModel in Jakarta EE projects?▼

Yes, MapStruct works with CDI componentModel in Jakarta EE projects to enable compile-time validation for DTO and entity mappings. This configuration supports deterministic mapping between DTOs, entities, and records with strong type safety.

How do I resolve multiple constructors when mapping immutable entities with MapStruct?▼

Resolve multiple constructors when mapping immutable entities by annotating the selected constructor with a custom @Default annotation. This strategy enables MapStruct compile-time validation to select the proper constructor without runtime checks.

What is the best way to map records to entities in Jakarta EE without runtime checks?▼

The best way to map records to entities without runtime checks is enforcing constructor-based mapping with MapStruct compile-time validation. Using a Default-annotation strategy and CDI componentModel ensures deterministic, type-safe mapping with no runtime overhead.

Why does my MapStruct mapper break when I change an entity constructor?▼

MapStruct mappers break when you change an entity constructor because constructor-based mapping enforces compile-time safety, catching constructor changes during the build rather than at runtime. This ensures mapper correctness by failing fast during compilation.

Can I use constructor-based mapping for both DTO to entity and entity to DTO conversions?▼

Yes, constructor-based mapping applies to both DTO to entity and entity to DTO conversions. By relying on MapStruct compile-time validation and a Default-annotation strategy, both mapping directions achieve deterministic type safety with no runtime checks.