mapstruct

MapStruct — Addon Studio 2.0

MapStruct = biblioteca padrao pra conversao DTO <-> entidade. Nunca faca mapper manual — use MapStruct.

"Dominio", nesta skill e nas demais do plugin, e a entidade @JapeEntity. Os metodos toDomain/fromDomain convertem DTO <-> entidade — nao existe um terceiro modelo entre eles. Criar POJO de dominio separado da entidade e decisao explicita do projeto (ver skill controller, "O que atravessa controller -> service"), nunca inferida a partir do nome dos metodos.

Referencia complementar: veja dependency-injection pra como mappers registram no container Guice.

Escopo: arquivo define so regras genericas MapStruct. Regras negocio, filtros plataforma, convencoes dominio especificas ficam em override por projeto (fora desta skill).

---

1. Configuracao Global do Projeto

Projeto ja define flags globais compilacao no build.gradle:

dependencies {
    implementation 'org.mapstruct:mapstruct:1.5.5.Final'
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'

    compileOnly 'org.projectlombok:lombok:1.18.30'
    annotationProcessor 'org.projectlombok:lombok:1.18.30'
    annotationProcessor 'org.projectlombok:lombok-mapstruct-binding:0.2.0'
}

tasks.withType(JavaCompile) {
    options.compilerArgs += [
        "-Amapstruct.defaultComponentModel=jakarta",
        "-Amapstruct.unmappedTargetPolicy=IGNORE"
    ]
}

O que cada flag faz

Flag	Valor	Efeito
defaultComponentModel	jakarta	MapStruct gera implementacoes com @Named pra registro automatico Guice. NAO sobrescrever nos mappers.
unmappedTargetPolicy	IGNORE	Campos target sem mapeamento explicito ignorados sem erro compilacao.
lombok-mapstruct-binding	0.2.0	Garante compatibilidade Lombok (getters/setters gerados) com MapStruct (annotation processor).

ATENCAO — Nao confunda componentModel com injectionStrategy:

Parametro	Configurado globalmente?	Regra
componentModel	SIM — jakarta no build.gradle	NUNCA declare no @Mapper individual. Declarar sobrescreve global.
injectionStrategy	NAO — sem flag global	SEMPRE declare InjectionStrategy.CONSTRUCTOR em mapper abstract class (com @Inject repository) ou que use uses = {...}.
repositories em abstract class	N/A	SEMPRE use field injection (@Inject no campo). Limitacao MapStruct: processador nao gera super(...) com parametros construtor classe abstrata, impossibilita constructor injection pra repositorios.

IMPORTANTE — componentModel: componentModel NUNCA declare no @Mapper individual. Ja global como jakarta em build.gradle. Declarar — mesmo com mesmo valor "jakarta" — sobrescreve global, causa conflitos injecao ou falhas silenciosas no Guice.

IMPORTANTE — injectionStrategy: injectionStrategy NAO global. Declare explicito como InjectionStrategy.CONSTRUCTOR em mapper que:

• abstract class com @Inject (repositorios ou deps), OU
• use uses = {...} com componentes externos.

Omitir = field injection Guice sem garantia ordem inicializacao.