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.