mapstruct-patterns

Enforce compile-time safety for Java MapStruct mappings using constructor-based mapping.

1|1|Updated Dec 27, 2025
One-click install
npx skills add https://github.com/emvnuel/SKILL.md --skill mapstruct-patterns
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: mapstruct-patterns
Source: https://github.com/emvnuel/SKILL.md/tree/main/mapstruct-patterns
Command: npx skills add https://github.com/emvnuel/SKILL.md --skill mapstruct-patterns

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill enforces compile-time safety for MapStruct mappings by using constructor-based mapping and a default-constructor annotation pattern, preventing runtime surprises when constructors change.

Core Features & Use Cases

  • Constructor-based mapping discipline: MapStruct binds to a constructor signature, causing compilation errors if signatures change, ensuring stability.
  • Custom @Default pattern: Demonstrates selecting a preferred constructor via a user-defined annotation to drive mapping behavior.
  • CDI and records support: Shows CDI integration and how Java Records map naturally with constructor-based approaches.
  • Compile-time safety benefits: Highlights how updates to constructors require mapper changes to compile, reducing drift between model and DTOs.
  • ** Cookbook reference patterns**: Provides starter patterns for entity mapping, record mapping, and related scenarios.

Quick Start

Create a CDI-based MapStruct mapper for an entity using a Default constructor annotation to guide the selected constructor and ensure 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 make MapStruct mappings fail at compile time when constructors change?

Constructor-based mapping makes MapStruct bind directly to a constructor signature, causing compilation errors instead of runtime failures when DTO or entity constructors change.

What is the best way to select a specific constructor for MapStruct in Jakarta EE?

A custom @Default annotation pattern designates the preferred constructor, guiding mapper selection and ensuring consistent compile-time safe mapping behavior across Jakarta EE components.

Does MapStruct work with CDI and Java Records for entity conversion?

MapStruct integrates with CDI and maps Java Records naturally using constructor-based approaches, ensuring compile-time safety for record and entity conversions in Jakarta EE.

How do I create a CDI-based MapStruct mapper for entity conversion?

Create a CDI-based MapStruct mapper using a Default constructor annotation to guide constructor selection, ensuring compile-time safety for entity and DTO conversions.

Why should I use constructor-based mapping instead of field-based mapping in MapStruct?

Constructor-based mapping enforces compile-time safety by triggering compilation errors when constructors change, preventing runtime surprises and reducing drift between models and DTOs.

Can I get reference patterns for record and entity mapping with MapStruct?

Cookbook reference patterns provide starter templates for entity mapping, record mapping, and related scenarios using constructor-based approaches and CDI integration.