MapStruct
Compile-time code generator for Java bean-to-bean mapping — the standard solution for DTO/entity mapping in Java applications. MapStruct generates type-safe, performant mapping implementations at compile time via annotation processing: define a @Mapper interface with method signatures, MapStruct generates the implementation. Eliminates reflection-based mappers (ModelMapper, Dozer) which have runtime overhead and no compile-time safety. Key features: automatic field mapping by name, custom mapping methods, decorator pattern, Spring/CDI injection, null-safety, and collection mapping.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
No network exposure. Compile-time generated code — no reflection vulnerabilities. Generated code is auditable Java. No security concerns for the library itself.
⚡ Reliability
Best When
You're building a Java application with multiple layers (API, domain, persistence) that require DTO-to-entity mapping — MapStruct's compile-time generation gives both safety and performance.
Avoid When
You need dynamic runtime mapping from database schemas, you're in Kotlin (extra setup needed), or your object structure is too simple to justify annotation-processor setup.
Use Cases
- • Map Java agent entity objects to DTOs using MapStruct — compile-time generated mapper eliminates reflection overhead in high-throughput agent API response serialization
- • Transform agent API request DTOs to domain objects with field validation mapping — @Mapping(source, target) annotations for field name mismatches between DTO and domain
- • Map between agent data models in different layers (persistence → domain → API) with multiple @Mapper interfaces — clean separation of mapping concerns per application layer
- • Handle nullable field mapping for agent optional data — @Mapping(nullValueMappingStrategy) and @Mapping(defaultValue) for null-safe transformations
- • Map agent collection types using MapStruct's automatic list/set mapping — List<AgentDTO> mapToDto(List<Agent> agents) generates mapping loop with reuse
Not For
- • Dynamic mapping at runtime (from database schema, reflection) — MapStruct generates static code at compile time; use ModelMapper or ObjectMapper for dynamic runtime mapping
- • Non-Java JVM applications — use KotlinMapper (Kotlin) or AutoMapper (.NET) for respective ecosystems; MapStruct has Kotlin support but Kotlin-specific gotchas
- • Simple single-object conversion without annotations — a hand-written constructor or static factory method is simpler for 1-2 field mappings; MapStruct overhead not justified
Interface
Authentication
Code generation library — no auth concepts.
Pricing
MapStruct is Apache 2.0 licensed, maintained by Gunnar Morling and contributors. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Unmapped target properties are warnings by default — add @Mapper(unmappedTargetPolicy = ReportingPolicy.ERROR) to fail compile on unmapped fields; prevents silent data loss when adding new entity fields
- ⚠ Annotation processor ordering with Lombok — MapStruct must run AFTER Lombok (Lombok generates getters/setters, MapStruct reads them); in Maven, configure lombok before mapstruct in annotationProcessorPaths; in Gradle, use compileOnly ordering
- ⚠ Spring injection requires componentModel — @Mapper(componentModel = "spring") generates @Component mapper; without it, MapStruct generates plain class requiring Mappers.getMapper() static method; mixing both styles in Spring context causes confusion
- ⚠ Mapping inheritance with @InheritInverseConfiguration — bi-directional mapping (toDto + toEntity) uses @InheritInverseConfiguration to avoid duplication; field name mismatches that need @Mapping in one direction must also be explicitly mapped in the inverse
- ⚠ Custom type converters require @Named methods — when source and target types differ (String to LocalDate), MapStruct uses @Named methods for conversion; registration in @Mapper(uses = ...) required; missing converter causes compile error
- ⚠ Kotlin data class mapping issues — Kotlin data class properties are final by default; MapStruct needs setter access or all-args constructor; use @KotlinBuilder or ensure data class has copy() mapping support
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for MapStruct.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-06.