Artículo

Patrón Builder en Java: qué es, cuándo usarlo y ejemplo

Cómo implementar el patrón Builder en Java para objetos con muchos parámetros opcionales: validación, inmutabilidad, Lombok y records.

En resumen: el patrón Builder separa la construcción de un objeto de su representación. Sirve cuando un objeto tiene muchos parámetros, varios opcionales: en lugar de constructores con ocho argumentos (new Pizza("grande", "gruesa", true, false, ...)), encadenas llamadas legibles y terminas con build(), que valida y devuelve un objeto inmutable. Probado con Java 25, compatible desde Java 17.

Vídeo explicativo

El problema

new Pizza("grande", "gruesa", true, false, List.of("jamón"));   // ¿qué era true? ¿y false?

Con muchos parámetros, los constructores se vuelven ilegibles y es fácil intercambiar dos del mismo tipo sin que el compilador avise. Crear varios constructores (telescópicos) multiplica el código, y usar setters deja el objeto mutable y a medio construir.

Implementación

import java.util.ArrayList;
import java.util.List;

final class Pizza {
    private final String tamano;          // obligatorio
    private final String masa;            // opcional, con valor por defecto
    private final List<String> ingredientes;
    private final boolean extraQueso;

    private Pizza(Builder b) {
        this.tamano = b.tamano;
        this.masa = b.masa;
        this.ingredientes = List.copyOf(b.ingredientes);
        this.extraQueso = b.extraQueso;
    }

    static Builder builder(String tamano) {
        return new Builder(tamano);
    }

    @Override
    public String toString() {
        return "Pizza " + tamano + ", masa " + masa + ", " + ingredientes
                + (extraQueso ? ", extra de queso" : "");
    }

    static final class Builder {
        private final String tamano;
        private String masa = "fina";
        private final List<String> ingredientes = new ArrayList<>();
        private boolean extraQueso;

        private Builder(String tamano) {
            this.tamano = tamano;
        }

        Builder masa(String masa) {
            this.masa = masa;
            return this;
        }

        Builder ingrediente(String ingrediente) {
            ingredientes.add(ingrediente);
            return this;
        }

        Builder extraQueso() {
            this.extraQueso = true;
            return this;
        }

        Pizza build() {
            if (ingredientes.isEmpty()) {
                throw new IllegalStateException("Una pizza necesita al menos un ingrediente");
            }
            return new Pizza(this);
        }
    }
}

public class Main {
    public static void main(String[] args) {
        Pizza margarita = Pizza.builder("mediana")
                .ingrediente("tomate")
                .ingrediente("mozzarella")
                .build();
        System.out.println(margarita);

        Pizza completa = Pizza.builder("grande")
                .masa("gruesa")
                .ingrediente("tomate")
                .ingrediente("jamón")
                .ingrediente("champiñones")
                .extraQueso()
                .build();
        System.out.println(completa);

        try {
            Pizza.builder("pequeña").build();
        } catch (IllegalStateException e) {
            System.out.println("Error: " + e.getMessage());
        }
    }
}

Salida:

Pizza mediana, masa fina, [tomate, mozzarella]
Pizza grande, masa gruesa, [tomate, jamón, champiñones], extra de queso
Error: Una pizza necesita al menos un ingrediente

Las decisiones que importan

  • Constructor privado de Pizza. Solo el builder puede crearla, así que build() es el único punto de entrada y siempre valida.
  • Obligatorios en builder(...), opcionales en métodos. El tamaño no se puede olvidar porque sin él no obtienes un builder.
  • List.copyOf al construir. La pizza no comparte la lista mutable del builder: si sigues usando el builder, la pizza no cambia.
  • Métodos que devuelven this. Es lo que permite encadenar llamadas; lo explicamos en this en Java.
  • Validación en build(). Las reglas que afectan a varios campos a la vez se comprueban al final, no en cada método.

Builder con Lombok y con records

En proyectos Spring es habitual generar el builder con Lombok:

@Builder
@Value
class Pedido {
    String cliente;
    @Builder.Default String moneda = "EUR";
    @Singular List<String> lineas;
}
// Pedido.builder().cliente("Ana").linea("Curso Java").build();

Lombok ahorra código, pero no valida nada: si necesitas reglas, escríbelas en un constructor o en un método build() propio. Con un record de pocos campos, normalmente no hace falta builder: el constructor canónico con validación es suficiente.

Cuándo usarlo y cuándo no

Situación¿Builder?
Cuatro o más parámetros, varios opcionalesSí
Objeto inmutable que necesita validación entre camposSí
Datos de prueba en tests con muchos valores por defectoSí, muy útil
Dos o tres campos obligatoriosNo: un constructor o un record
El objeto cambia durante su vidaReplantéalo: quizá necesitas métodos con significado, no un builder

Preguntas frecuentes

¿Qué diferencia hay entre Builder y Factory?

Factory decide qué clase crear (por ejemplo, un Notificador de email o de SMS). Builder decide cómo se monta un objeto paso a paso.

¿Dónde se ve en el JDK?

StringBuilder, HttpRequest.newBuilder(), Stream.builder() y Locale.Builder son builders del propio JDK.

¿El builder debe ser una clase anidada?

Es lo habitual (static class Builder), porque accede al constructor privado y queda junto a la clase que construye. Más en clases internas en Java.

Sigue aprendiendo

Tienes el resto de patrones creacionales en Singleton, Factory y Prototype. El diseño de clases con patrones se trabaja en el curso de Java intermedio, y su aplicación en arquitecturas reales en el máster de arquitecto Java.

patrón builder patrones de diseño java builder lombok

Newsletter Semanal de Java

Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.

Sin spam. Cancela cuando quieras.

Compartir artículo