Creación de conversores personalizados en MapStruct para enums y strings

Contenido del curso

Introducción a Spring Boot

Persistencia con Spring Data y modelado de datos

Buenas prácticas en diseño de APIs

Calidad documentación y producción

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:0010:01

Creación de conversores personalizados en MapStruct para enums y strings

Curso de Java Spring Boot

Clase 13 de 23

Clase 13 / 23

Recursos

MapStruct potencia la conversión entre objetos en Java, pero en muchos casos los tipos de datos no coinciden exactamente. Dominar la creación de conversores personalizados es clave para asegurar que aplicaciones de backend gestionen correctamente enums, strings y valores booleanos, garantizando así robustez y claridad en el código de mapeo.

¿Cómo manejar conversiones personalizadas en MapStruct para enums y strings?

En situaciones donde los tipos de datos del modelo de dominio y del DTO (Data Transfer Object) difieren, como un string en la base de datos que debe convertirse a un enum en la lógica de dominio, MapStruct requiere métodos de conversión personalizados.

Se crea un enum (por ejemplo, Genre) que defina posibles valores: action, comedy, drama, animated, horror, science fiction.
El DTO ahora utiliza este enum en vez de un string para mayor control y coherencia.

Esto obliga a adaptar el mapeo, pues los valores guardados en el almacenamiento pueden diferir (por ejemplo, “animada” en la base de datos versus “animated” en el enum). El conversor personalizado soluciona esta diferencia.

¿Cómo implementar un conversor personalizado para string y enum en Java?

El conversor personalizado consta de dos métodos estáticos. Uno convierte de string a enum, y el otro, de enum a string.

El método stringToGenre recibe el string de la base de datos y retorna el enum correspondiente tomando en cuenta las diferencias de nombres y mayúsculas/minúsculas.
Utiliza una estructura switch y verifica primero si el string recibido es nulo, en cuyo caso devuelve null.
Cada valor de string se asigna al valor correcto del enum (por ejemplo, "acción" a action, "animada" a animated).

El método inverso, genreToString, sigue la misma lógica:

Recibe un valor enum y devuelve el string que almacena la base de datos.
También verifica si el valor es nulo y asigna los textos correctos según el caso.

Ambos métodos deben anotarse con @Named de org.mapstruct para que el framework los reconozca y los aplique automáticamente al mapear campos específicos.

¿Cómo integrar el conversor personalizado en el mapper principal de MapStruct?

Para emplear los conversores dentro de MapStruct, se sigue este proceso:

Se indica en la anotación @Mapper del MovieMapper que utilizará la clase GenreMapper en su atributo uses.
En el método de mapeo que convierte de entity a DTO, se especifica el uso del método personalizado mediante la propiedad qualifiedByName, usando el nombre del método anotado.

De este modo, los campos de género se traducirán correctamente entre string y enum sin necesidad de lógica adicional fuera del mapper. El resultado es un código más limpio, claro y alineado con buenas prácticas.

¿Cómo crear un conversor para otros tipos no compatibles, como string a boolean?

Se plantea el reto de extender este enfoque a otros campos, como un estado representado por una letra (“D” para disponible, “N” para no disponible) que debe convertirse en un valor booleano para el DTO y viceversa.

El método personalizado recibiría el string y retornaría true si es “D” y false en otro caso.
Este método también sería añadido con anotaciones @Named e integrado en el mapper principal usando qualifiedByName.

Este patrón garantiza que cualquier diferencia entre los modelos se pueda resolver de forma centralizada y mantenible, haciendo el mejor uso de MapStruct para tipos de datos heterogéneos.

¿Te animas a escribir tu propio conversor para el campo de estado o a comentar cómo resolverías un caso parecido en tu proyecto?

Andres Botero

Hace 5 meses•editado

Creo que el profesor quiso explicar de forma sencilla como usar el MapStruct en otro escenario. Sin embargo, no recomiendo hacer esta practica para sus proyectos. Me explico: Si el mapeo se basa estrictamente en valores fijos (como un String que representa una categoría), usar una clase externa (GenreMapper) con un switch-case es redundante y agrega acoplamiento innecesario. Pueden usar solamente el enum para el mismo propósito:

package com.tupaquete.tuapp.domain;

import java.util.Arrays;

public enum Genre {
    ACTION("ACCION", "Películas llenas de persecuciones, peleas y adrenalina."),
    COMEDY("COMEDIA", "Películas enfocadas en el humor y situaciones divertidas."),
    DRAMA("DRAMA", "Relatos centrados en el desarrollo de personajes y conflictos emocionales."),
    ANIMATED("ANIMADA", "Contenido creado mediante técnicas de animación."),
    HORROR("TERROR", "Películas diseñadas para generar miedo, suspenso o inquietud."),
    SCI_FI("CIENCIA FICCION", "Historias basadas en conceptos científicos, futuristas o tecnológicos.");

    private final String dbValue;
    private final String description;

    Genre(String dbValue, String description) {
        this.dbValue = dbValue;
        this.description = description;
    }

    public static Genre fromDbValue(String value) {
        return Arrays.stream(Genre.values())
                .filter(g -> g.dbValue.equalsIgnoreCase(value))
                .findFirst()
                .orElse(null);
    }

    public String getDbValue() {
        return dbValue;
    }

    public String getDescription() {
        return description;
    }
}

Para implementar el enum en el MoveMapper.java deben agregar esto:

package com.tupaquete.tuapp.persistence.mapper;

import com.tupaquete.tuapp.domain.Genre;
import com.tupaquete.tuapp.domain.dto.MovieDto;
import com.tupaquete.tuapp.persistence.entity.MovieEntity;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import java.util.List;

@Mapper(componentModel = "spring")
public interface MovieMapper {

    @Mapping(source = "clasificacion", target = "rating")
    MovieDto toDto(MovieEntity entity);
    List<MovieDto> toDto(List<MovieEntity> entities);

    //Este bloque es el que se agrega.
    default Genre map(String genreString) {
        return Genre.fromDbValue(genreString);
    }
}

¿Por qué esta practica es mejor?

Encapsulamiento: Si mañana agregas un nuevo género, solo modificas el archivo Genre.java. No tienes que ir a buscar una clase Mapper adicional.
Menos "Boilerplate": Eliminas una clase entera (GenreMapper) de tu proyecto, reduciendo la complejidad innecesaria.
Mantenibilidad: Si usas MapStruct, puedes llamar directamente a Genre.fromDbValue() mediante un expression o un default method en el mapper, sin necesidad de un switch-case manual en una clase externa.

¿Cuándo tendría sentido usar el Mapper?

El único escenario donde este enfoque se justifica es si:

Separación de responsabilidades estricta: Quieres que tu Enum no tenga ni idea de cómo se llama el dato en la base de datos (por ejemplo, si los valores en la DB cambian según el idioma o el sistema externo).
Complejidad: El mapeo no es un simple String, sino una lógica compleja que involucra múltiples campos o validaciones externas.

Comentarios (13)13 comentarios

David Mauricio Gorraiz Moreno

Hace un año

Yo cree esta clase para la conversion:

package com.platzi.play.persistence.mapper;

import org.mapstruct.Named;

public class StateMapper {
    @Named("stringToBoolean")
    public static Boolean stringToBoolean(String estado) {
        if (estado == null){
            return null;
        }

        return switch (estado){
            case "D" -> true;
            case "N" -> false;
            default -> null;
        };
    }

    @Named("booleanToString")
    public static String booleanToString(Boolean state) {
        return state == null ? null : (state ? "D" : "N");
    }
}
```Luego lo agregue al MovieMapper:

```java
package com.platzi.play.persistence.mapper;

import com.platzi.play.domain.dto.MovieDto;
import com.platzi.play.persistence.entity.MovieEntity;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;

import java.util.List;

@Mapper(componentModel = "spring", uses = {GenreMapper.class, StateMapper.class})
public interface MovieMapper {

    @Mapping(source = "titulo", target = "title")
    @Mapping(source = "duracion", target = "duration")
    @Mapping(source = "genero", target = "genre", qualifiedByName = "stringToGenre")
    @Mapping(source = "fechaEstreno", target = "releaseDate")
    @Mapping(source = "clasificacion", target = "rating")
    @Mapping(source = "estado", target = "state", qualifiedByName = "stringToBoolean")
    MovieDto toDtio(MovieEntity entity);
    List<MovieDto> toDtio(Iterable<MovieEntity> entities);

}

Brayan Diaz

Colega me ha encantado tú aporte, sin embargo me gustaría añadir una corrección, como se ve a continuación:

Nuestra columna estado en la base de datos no puede ser null, por ello te sugiero el siguiente código:

Si recibes un null, conviertelo a "N", para que la base de datos no reciba un null y no tengas una excepción en tiempo de ejecución, espero sea de ayuda, un saludo!

Sebastian Felipe Fonseca Hurtado

Hace 9 meses•editado

Me parece interesante el tema de los Mapper, sin embargo, quisiera hacer una propuesta a lo hecho por el instructor en el video y es que en vez de realizar código repetitivo y extenso, podemos aprovechar las facilidades que nos dan los Enum y podemos agregarle un atributo que tenga el nombre del genero en String y así realizar la conversión más facil. Aquí está mi propuesta.

Para el Enum de Gender (como yo lo llamé) le agregamos el atributo de genderName el cuál llega por parámetro al constructor y así tenemos cada genero del Enum con su respectiva cadena en español.

package com.platzi.play.domain;

public enum Gender {
    ACTION("ACCION"),
    COMEDY("COMEDIA"),
    DRAMA("DRAMA"),
    ANIMATED("ANIMADA"),
    HORROR("TERROR"),
    SCI_FI("CIENCIA_FICCION");

    private String genderName;

    Gender(String genderName){
        this.genderName = genderName;
    }

    public String getGenderName() {
        return this.genderName;
    }
}

Por otro lado, para la conversión en el GenderMapper, nos apoyamos con el método values de los Enum y con un ciclo validamos cuál es el equivalente el genero en String que llega por parámetro (porque si existen 10.000 generos, ¿Tenemos que ponernos a hacer 10.000 cases?). Además para convertir del Enum al String, solo es llamar al método get que implementamos en la clase enum y no repetimos el código del método anterior.

package com.platzi.play.persistence.mapper;

import com.platzi.play.domain.Gender;
import org.mapstruct.Named;

public class GenderMapper {

    @Named("stringToGender")
    public static Gender stringToGender(String genderName){
        Gender genderEnum = null;
        if(genderName != null){
            for (Gender gender : Gender.values()) {
                if (gender.getGenderName().equals(genderName)) {
                    genderEnum = gender;
                    break;
                }
            }
        }
        return genderEnum;
    }

    @Named("genderToString")
    public static String genderToString(Gender genderEnum){
        return genderEnum!= null? genderEnum.getGenderName():null;
    }
}

Así mismo haría para el tributo de disponibilidad, sin realzar código extenso validando un caso o el otro. Aprovechen los Enum :)

Gerson Augusto Rosales Jauregui

Aqui hice un ejemplo

public class StateMapper {
    @Named("stateToBoolean")
    public static Boolean stateToBoolean(String state) {
        if (state == null) {
            return null;
        } else {
            return state.equals("D");
        }
    }

    @Named("booleanToState")
    public static String booleanToState(Boolean state) {
        if (state == null) {
            return null;
        } else {
            return state ? "D" : "N";
        }
    }
}

@Mapper(componentModel = "spring", uses = {GenreMapper.class, StateMapper.class})
public interface MovieMapper {
    @Mapping(source = "titulo", target = "title")
    @Mapping(source = "duracion", target = "duration")
    @Mapping(source = "genero", target = "genre", qualifiedByName = "stringToGenre")
    @Mapping(source = "fechaEstreno", target = "releaseDate")
    @Mapping(source = "clasificacion", target = "rating")
    @Mapping(source = "estado", target = "state", qualifiedByName = "stateToBoolean")
    MovieDto toDto(MovieEntity entity);
    List<MovieDto> toDto(Iterable<MovieEntity> entities);
}

JUAN SEBASTIAN ORTIZ

Así quedó la clase StatusMapper:

package com.movies.movies_play.persistence.mapper;import org.mapstruct.Named;public class StatusMapper {    @Named("stringToBoolean")    public static Boolean stringToBoolean(String status) {        if (status == null) return null;        return switch (status.toUpperCase()) {            case "D" -> true;            case "N" -> false;            default -> null;        };    }    @Named("booleanToString")    public static String booleanToString(Boolean status) {        if (status == null) return null;        return status ? "D" : "N";    }}

JHONATAN AGUILERA GARCIA

Hace 15 días

Mi solución al reto

package com.platzi.play.persistence.mapper;

import org.mapstruct.Named;

public class StatusMapper {
    @Named("stringToStatus")
    public static Boolean stringToStatus(String isAvailable) {
        if (isAvailable  == null) return false;

        return isAvailable .equalsIgnoreCase("D");
    }

    @Named("statusToString")
    public static String statusToString(Boolean isAvailable) {
        return isAvailable  ? "D" : "N";
    }
}

@Mapper(componentModel = "spring", uses = { GenderMapper.class, StatusMapper.class })
public interface MovieMapper {
    @Mapping(source = "titulo", target = "title")
    @Mapping(source = "duracion", target = "duration")
    @Mapping(source = "genero", target = "gender", qualifiedByName = "stringToGender")
    @Mapping(source = "fechaEstreno", target = "releaseDate")
    @Mapping(source = "clasificacion", target = "rating")
    @Mapping(source = "estado", target = "isAvailable", qualifiedByName = "stringToStatus")
    MovieDto toDto(MovieEntity entity);
    List<MovieDto> toDto(Iterable<MovieEntity> entities);
}

Juan Cadavid

Hace 4 meses•editado

package com.platzi.platzi_play.persistence.mapper;

import org.mapstruct.Named;

public class StatusMapper {

    @Named("stringToBoolean")
    public static Boolean stringToBoolean(String status) {
        return status != null && status.equalsIgnoreCase("D");
    }

    @Named("booleanToString")
    public static String booleanToString(Boolean isAvailable) {
        return isAvailable ? "D" : "N";
    }
}

Daniel Leonardo Gomez Mora

Hace 4 meses

no se si es lo correcto, me quedo super minimalista, no use un enum, no lo considere pertinente para solo true y false.

Diego Frank Lipa Choque

Hace 6 meses

🐝{;)}

Juan Anaya

Hace 9 meses

Así deje mi mapper para el estado:

public class IsAvailableMapper {

    @Named("stringToAvailable")
    public static Boolean stringToAvailable (String string){
        return "D".equalsIgnoreCase(string);
    }

    @Named("stateToString")
    public static String availableToString (Boolean available){
        return available ? "D" : "N";
    }
}

Milton Hernan Camacho Quitian

Comparto mi aporte:

package com.platzi.play.persistence.mapper;

import org.mapstruct.Named;

public class StatusMapper {
    @Named("stringToStatus")
    public static boolean stringToStatus(String estado){
        if(estado.isBlank()) return false;

        if(estado.equalsIgnoreCase("D")) return true;
        else return false;
    }
    @Named("statusToString")
    public static String statusToString(boolean status){
        if(status) return "D";
        else return "N";
    }
}

MovieMapper:

package com.platzi.play.persistence.mapper;

import com.platzi.play.domain.dto.MovieDto;
import com.platzi.play.persistence.entity.MovieEntity;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;

import java.util.List;

@Mapper(componentModel = "spring", uses = {GenreMapper.class, StatusMapper.class})
public interface MovieMapper {

    @Mapping(source = "titulo", target = "title")
    @Mapping(source = "duracion", target = "duration")
    @Mapping(source = "genero", target = "genre", qualifiedByName = "stringToGenre")
    @Mapping(source = "fechaEstreno", target = "releaseDate")
    @Mapping(source = "clasificacion", target = "rating")
    @Mapping(source = "estado", target = "status", qualifiedByName = "stringToStatus")
    MovieDto toDTO(MovieEntity entity);
    List<MovieDto> toDto(Iterable<MovieEntity> entities);
}

ANDRES ALFONSO MIRA MEJIA

Hace 10 meses

✅

Jesus Beltran

Hola, tengo una pregunta. Entiendo que se esta enseñando el uso de MapStruct para convertir Entity a DTO y de paso hacerlo en inglés, asi como convertir el género de String a un valor de enum. Pero por que razón o en que situaciones conviene hacer esto, en lugar de modificar directamente el código? De hacer el cambio de String a Genre directamente en el MovieEntity, y de renombrar los atributos de español a inglés?

Camila Escobedo Fica

Misma duda tengo, yo siempre he usado todo tal cual se maneja en la BD para evitar confusiones, espero alguien pueda explicarlo

Introducción a Spring Boot

¿Qué es Spring y por qué es tan popular?

Configuración inicial de proyecto Spring Boot con Java 21

Crear un endpoint REST con Spring Boot e integrarlo con IA usando LangChain4j

Configuración de application.properties y perfiles en Spring Boot

Estructura de paquetes en Spring Boot por capas

Persistencia con Spring Data y modelado de datos

Conectar Spring Boot a PostgreSQL con Docker

Crear entidad con anotaciones JPA para tabla de base de datos

Repositorios CRUD con Spring Data sin escribir SQL

Primer endpoint GET con Spring Boot

Buenas prácticas en diseño de APIs

Inyección de dependencias con Spring IoC

Separación de dominio y persistencia con DTOs en Java

Configuración de MapStruct con Spring para convertir entidades a DTO

Creación de conversores personalizados en MapStruct para enums y strings

Captura de parámetros con @PathVariable en Spring Boot

Códigos HTTP y Response Entity en APIs REST

Calidad documentación y producción

Crear endpoint POST en Spring Boot

Endpoint PUT con MapStruct en Spring Boot

Sistema de recomendaciones con LangChain4j y Spring

Manejo de errores con @RestControllerAdvice

Validación automática de datos en APIs con Spring Boot

Documenta tu API REST con OpenAPI

Compilación de aplicación Java para producción con PostgreSQL

Desplegar tu API Spring Boot en Render

Creación de conversores personalizados en MapStruct para enums y strings

Progreso del curso

Introducción a Spring Boot

Persistencia con Spring Data y modelado de datos

Buenas prácticas en diseño de APIs

Calidad documentación y producción

Recursos

Recursos