Arquetipo
Patrones creacionalesUso: Muy altaComplejidad: Media

Builder

Constructor paso a paso

Separa la construcción de un objeto complejo de su representación, para construirlo paso a paso y validar el resultado antes de entregarlo.

“Mi constructor tiene demasiados parámetros opcionales y nadie sabe en qué orden van.”

workEl caso real

El buscador de tu marketplace acepta texto, categoría, rango de precios, marcas, "solo con stock", orden y paginación. Casi todo es opcional, pero hay reglas: el precio mínimo no puede superar al máximo y la página empieza en 1. Además, marketing quiere búsquedas predefinidas, como "Ofertas del día" o "Novedades".

warningEl problema sin el patrón

new Busqueda("zapatillas", null, null, 100, null, true, "precio", 2, 20): nadie recuerda qué es cada argumento, se pueden intercambiar valores sin que el compilador lo note y las validaciones quedan repartidas por los controladores.

check_circleCómo lo resuelve el patrón

Un BusquedaBuilder recibe los datos paso a paso, con métodos que tienen nombre. Al final, build() valida todas las reglas y entrega un objeto Busqueda inmutable. Las búsquedas predefinidas se escriben como recetas (el Director) que siempre ejecutan los mismos pasos.

schemaDiagrama de clases

Diagrama interactivo: puedes acercar, mover el lienzo y pasar el cursor sobre cada clase para ver su detalle.

codeEl código, antes y después

cancelSin el patrónANTES
// ¿Qué es cada null? ¿100 es el precio mínimo o el máximo?
const busqueda = new Busqueda('zapatillas', null, null, 100, null, true, 'precio', 2, 20);
check_circleCon el patrónDESPUÉS
class BusquedaBuilder {
  private filtros: Partial<FiltrosBusqueda> = {};

  texto(t: string) { this.filtros.texto = t; return this; }
  precioEntre(min: number, max: number) { this.filtros.precio = { min, max }; return this; }
  soloConStock() { this.filtros.soloConStock = true; return this; }
  ordenarPor(campo: Orden) { this.filtros.orden = campo; return this; }

  build(): Busqueda {
    const { precio } = this.filtros;
    if (precio && precio.min > precio.max) throw new Error('Rango de precio inválido');
    return new Busqueda({ pagina: 1, ...this.filtros }); // objeto inmutable y válido
  }
}

// Director: recetas que siempre siguen los mismos pasos
const ofertasDelDia = (b: BusquedaBuilder) =>
  b.soloConStock().ordenarPor('descuento').build();

Ejemplos en TypeScript, simplificados para mostrar la idea: los tipos auxiliares (Pedido, Cliente…) se omiten.

lightbulb

Matiz importante

Hay dos variantes. El Builder original de GoF separa un Director, que define el orden de los pasos, de varios builders concretos que producen representaciones distintas (por ejemplo, el mismo documento en HTML o en PDF). El builder "fluido", con métodos encadenados, se popularizó después para evitar constructores con demasiados parámetros. El ejemplo combina ambos: un builder fluido y recetas que actúan como Director.

thumb_upCuándo usarlo

  • ✓Un objeto tiene muchos parámetros opcionales o combinaciones que validar.
  • ✓Quieres construir el objeto por etapas (por ejemplo, a medida que se leen los filtros de la URL).
  • ✓El mismo proceso de construcción debe producir representaciones distintas.

do_not_disturb_onCuándo no usarlo

  • ✕El objeto tiene pocos campos: un constructor o un objeto de opciones con nombre (new Busqueda({ texto, orden })) es suficiente.
  • ✕No hay reglas que validar ni pasos que ordenar: el builder solo añade código.

memoryPrincipios en juego

  • •Responsabilidad única: armar y validar el objeto es trabajo del builder, no de los controladores.
  • •Inmutabilidad: el objeto final nace completo y válido.

hubPatrones relacionados

  • •Abstract Factory: entrega objetos terminados en una sola llamada; Builder los arma paso a paso.
  • •Composite: los builders son muy útiles para construir árboles complejos.
  • •Bridge: el Director puede hacer de abstracción y cada builder concreto, de implementación.
  • •Singleton: un Director o un builder compartido puede ser una instancia única.

quizPon a prueba lo que leíste

Dos preguntas al azar sobre este patrón. Cada vez que las cambias salen otras.

Más ejercicios →

code_blocksBuilder en tu lenguaje

El mismo caso, implementado completo y de forma idiomática. Se puede copiar y ejecutar.

LO IDIOMÁTICO EN TYPESCRIPT: Los campos privados # guardan el estado del builder, los métodos devuelven this para encadenar y el producto se entrega congelado (Object.freeze) con propiedades readonly. Los tipos literales (Orden) impiden pasar un criterio de orden que no existe.

builder.ts · 57 líneas
type Orden = 'relevancia' | 'precio' | 'descuento' | 'novedad';

export interface Busqueda {
  readonly texto?: string;
  readonly precio?: Readonly<{ min: number; max: number }>;
  readonly soloConStock: boolean;
  readonly orden: Orden;
  readonly pagina: number;
}

export class BusquedaBuilder {
  #texto?: string;
  #precio?: { min: number; max: number };
  #soloConStock = false;
  #orden: Orden = 'relevancia';
  #pagina = 1;

  texto(t: string) { this.#texto = t.trim(); return this; }
  precioEntre(min: number, max: number) { this.#precio = { min, max }; return this; }
  soloConStock() { this.#soloConStock = true; return this; }
  ordenarPor(orden: Orden) { this.#orden = orden; return this; }
  pagina(numero: number) { this.#pagina = numero; return this; }

  build(): Busqueda {
    if (this.#precio && this.#precio.min > this.#precio.max) throw new Error('Rango de precio inválido');
    if (this.#pagina < 1) throw new Error('La página empieza en 1');
    return Object.freeze({
      texto: this.#texto,
      precio: this.#precio && Object.freeze({ ...this.#precio }),
      soloConStock: this.#soloConStock,
      orden: this.#orden,
      pagina: this.#pagina,
    });
  }
}

// Director: recetas que siempre ejecutan los mismos pasos
export const Recetas = {
  ofertasDelDia: () => new BusquedaBuilder().soloConStock().ordenarPor('descuento').build(),
  novedades: (texto: string) => new BusquedaBuilder().texto(texto).ordenarPor('novedad').build(),
};

// ── Uso ──
const busqueda = new BusquedaBuilder()
  .texto('  zapatillas ')
  .precioEntre(50, 120)
  .soloConStock()
  .build();
console.log(busqueda);

console.log(Recetas.ofertasDelDia());

try {
  new BusquedaBuilder().precioEntre(200, 100).build();
} catch (error) {
  console.log((error as Error).message); // Rango de precio inválido
}
Ver los 23 patrones en TypeScript →