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
// ¿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);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.
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.
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.
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
}LO IDIOMÁTICO EN C# / .NET: En C#, las propiedades init y los inicializadores de objeto (new Busqueda { Texto = ... }) ya evitan el constructor telescópico. El builder fluido (como StringBuilder o WebApplication.CreateBuilder) aporta cuando hay que construir por pasos o validar el conjunto. Por dentro, cada paso crea una copia modificada del record con with.
var busqueda = new BusquedaBuilder()
.Texto(" zapatillas ")
.PrecioEntre(50, 120)
.SoloConStock()
.Build();
Console.WriteLine(busqueda);
Console.WriteLine(Recetas.OfertasDelDia().Orden); // Descuento
// Con todos los datos a mano, basta un inicializador de objeto
Console.WriteLine(new Busqueda { Texto = "auriculares", Orden = Orden.Novedad });
try
{
new BusquedaBuilder().PrecioEntre(200, 100).Build();
}
catch (ArgumentException error)
{
Console.WriteLine(error.Message); // Rango de precio inválido
}
public enum Orden { Relevancia, Precio, Descuento, Novedad }
public record Busqueda
{
public string? Texto { get; init; }
public (decimal Min, decimal Max)? Precio { get; init; }
public bool SoloConStock { get; init; }
public Orden Orden { get; init; } = Orden.Relevancia;
public int Pagina { get; init; } = 1;
}
public class BusquedaBuilder
{
private Busqueda _busqueda = new();
public BusquedaBuilder Texto(string texto) { _busqueda = _busqueda with { Texto = texto.Trim() }; return this; }
public BusquedaBuilder PrecioEntre(decimal min, decimal max) { _busqueda = _busqueda with { Precio = (min, max) }; return this; }
public BusquedaBuilder SoloConStock() { _busqueda = _busqueda with { SoloConStock = true }; return this; }
public BusquedaBuilder OrdenarPor(Orden orden) { _busqueda = _busqueda with { Orden = orden }; return this; }
public Busqueda Build()
{
if (_busqueda.Precio is { Min: var min, Max: var max } && min > max)
throw new ArgumentException("Rango de precio inválido");
return _busqueda;
}
}
// Director: recetas que siempre ejecutan los mismos pasos
public static class Recetas
{
public static Busqueda OfertasDelDia() => new BusquedaBuilder().SoloConStock().OrdenarPor(Orden.Descuento).Build();
}LO IDIOMÁTICO EN JAVA: El Builder clásico de Java (el de "Effective Java"): una clase Builder anidada con métodos encadenados y un build() final. El producto es un record inmutable cuyo constructor compacto valida siempre, se construya como se construya.
void main() {
var busqueda = Busqueda.builder()
.texto(" zapatillas ")
.precioEntre(50, 120)
.soloConStock()
.build();
IO.println(busqueda);
IO.println(Recetas.ofertasDelDia().orden()); // DESCUENTO
try {
Busqueda.builder().precioEntre(200, 100).build();
} catch (IllegalArgumentException error) {
IO.println(error.getMessage()); // Rango de precio inválido
}
}
enum Orden { RELEVANCIA, PRECIO, DESCUENTO, NOVEDAD }
record Busqueda(String texto, Double precioMin, Double precioMax, boolean soloConStock, Orden orden, int pagina) {
Busqueda { // constructor compacto: valida cualquier instancia
Objects.requireNonNull(orden, "orden");
if (precioMin != null && precioMax != null && precioMin > precioMax) {
throw new IllegalArgumentException("Rango de precio inválido");
}
if (pagina < 1) {
throw new IllegalArgumentException("La página empieza en 1");
}
}
static Builder builder() {
return new Builder();
}
static final class Builder {
private String texto;
private Double precioMin;
private Double precioMax;
private boolean soloConStock;
private Orden orden = Orden.RELEVANCIA;
private int pagina = 1;
Builder texto(String texto) { this.texto = texto.strip(); return this; }
Builder precioEntre(double min, double max) { this.precioMin = min; this.precioMax = max; return this; }
Builder soloConStock() { this.soloConStock = true; return this; }
Builder ordenarPor(Orden orden) { this.orden = orden; return this; }
Builder pagina(int pagina) { this.pagina = pagina; return this; }
Busqueda build() {
return new Busqueda(texto, precioMin, precioMax, soloConStock, orden, pagina);
}
}
}
// Director: recetas que siempre ejecutan los mismos pasos
final class Recetas {
static Busqueda ofertasDelDia() {
return Busqueda.builder().soloConStock().ordenarPor(Orden.DESCUENTO).build();
}
}LO IDIOMÁTICO EN JAVASCRIPT: Campos privados # para el estado del builder, métodos que devuelven this para encadenar y un producto congelado con Object.freeze. Sin tipos, la validación de build() es la única defensa: por eso también comprueba que el orden sea uno de los permitidos.
const ORDENES = new Set(['relevancia', 'precio', 'descuento', 'novedad']);
export class BusquedaBuilder {
#texto;
#precio;
#soloConStock = false;
#orden = 'relevancia';
#pagina = 1;
texto(t) { this.#texto = t.trim(); return this; }
precioEntre(min, max) { this.#precio = { min, max }; return this; }
soloConStock() { this.#soloConStock = true; return this; }
ordenarPor(orden) { this.#orden = orden; return this; }
pagina(numero) { this.#pagina = numero; return this; }
build() {
if (this.#precio && this.#precio.min > this.#precio.max) throw new Error('Rango de precio inválido');
if (!ORDENES.has(this.#orden)) throw new Error(`Orden desconocido: ${this.#orden}`);
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) => new BusquedaBuilder().texto(texto).ordenarPor('novedad').build(),
};
// ── Uso ──
const busqueda = new BusquedaBuilder().texto(' zapatillas ').precioEntre(50, 120).soloConStock().build();
console.log(busqueda);
console.log(Object.isFrozen(busqueda)); // true: nadie puede modificarla
console.log(recetas.novedades('auriculares').orden); // novedad
try {
new BusquedaBuilder().ordenarPor('popularidad').build();
} catch (error) {
console.log(error.message); // Orden desconocido: popularidad
}LO IDIOMÁTICO EN PYTHON: En Python, los argumentos con nombre y una dataclass(frozen=True, kw_only=True) ya resuelven el constructor con demasiados parámetros, y __post_init__ valida el resultado. El builder aporta cuando el objeto se arma por pasos (por ejemplo, leyendo filtros de la URL) o con recetas fijas.
from dataclasses import dataclass
from typing import Literal, Self
Orden = Literal["relevancia", "precio", "descuento", "novedad"]
@dataclass(frozen=True, kw_only=True)
class Busqueda:
texto: str | None = None
precio: tuple[float, float] | None = None
solo_con_stock: bool = False
orden: Orden = "relevancia"
pagina: int = 1
def __post_init__(self) -> None:
if self.precio and self.precio[0] > self.precio[1]:
raise ValueError("Rango de precio inválido")
if self.pagina < 1:
raise ValueError("La página empieza en 1")
class BusquedaBuilder:
def __init__(self) -> None:
self._texto: str | None = None
self._precio: tuple[float, float] | None = None
self._solo_con_stock = False
self._orden: Orden = "relevancia"
def texto(self, texto: str) -> Self:
self._texto = texto.strip()
return self
def precio_entre(self, minimo: float, maximo: float) -> Self:
self._precio = (minimo, maximo)
return self
def solo_con_stock(self) -> Self:
self._solo_con_stock = True
return self
def ordenar_por(self, orden: Orden) -> Self:
self._orden = orden
return self
def build(self) -> Busqueda:
return Busqueda(texto=self._texto, precio=self._precio,
solo_con_stock=self._solo_con_stock, orden=self._orden)
# Director: recetas que siempre ejecutan los mismos pasos
def ofertas_del_dia() -> Busqueda:
return BusquedaBuilder().solo_con_stock().ordenar_por("descuento").build()
if __name__ == "__main__":
# Construcción por pasos, por ejemplo a partir de los filtros de una URL
filtros = {"q": " zapatillas ", "min": "50", "max": "120", "stock": "1"}
builder = BusquedaBuilder()
if "q" in filtros:
builder.texto(filtros["q"])
if "min" in filtros and "max" in filtros:
builder.precio_entre(float(filtros["min"]), float(filtros["max"]))
if filtros.get("stock") == "1":
builder.solo_con_stock()
print(builder.build())
print(ofertas_del_dia().orden) # descuento
# Cuando ya tienes todos los datos, basta con argumentos con nombre
print(Busqueda(texto="auriculares", orden="novedad"))
try:
BusquedaBuilder().precio_entre(200, 100).build()
except ValueError as error:
print(error) # Rango de precio inválidoLO IDIOMÁTICO EN GO: Go no tiene sobrecarga ni argumentos con nombre, así que el patrón idiomático es el de las "opciones funcionales": cada opción es una función que modifica la configuración, y el constructor las aplica en orden y devuelve un error si el resultado no es válido.
package main
import (
"errors"
"fmt"
"slices"
"strings"
)
type Busqueda struct {
Texto string
PrecioMin float64
PrecioMax float64
SoloConStock bool
Orden string
Pagina int
}
type Opcion func(*Busqueda)
func ConTexto(texto string) Opcion {
return func(b *Busqueda) { b.Texto = strings.TrimSpace(texto) }
}
func PrecioEntre(minimo, maximo float64) Opcion {
return func(b *Busqueda) { b.PrecioMin, b.PrecioMax = minimo, maximo }
}
func SoloConStock() Opcion {
return func(b *Busqueda) { b.SoloConStock = true }
}
func OrdenarPor(orden string) Opcion {
return func(b *Busqueda) { b.Orden = orden }
}
var ordenesValidos = map[string]bool{"relevancia": true, "precio": true, "descuento": true, "novedad": true}
func NuevaBusqueda(opciones ...Opcion) (Busqueda, error) {
b := Busqueda{Orden: "relevancia", Pagina: 1} // valores por defecto
for _, opcion := range opciones {
opcion(&b)
}
switch {
case b.PrecioMax > 0 && b.PrecioMin > b.PrecioMax:
return Busqueda{}, errors.New("rango de precio inválido")
case !ordenesValidos[b.Orden]:
return Busqueda{}, fmt.Errorf("orden desconocido: %s", b.Orden)
}
return b, nil
}
// Director: las recetas son listas de opciones
var OfertasDelDia = []Opcion{SoloConStock(), OrdenarPor("descuento")}
func main() {
busqueda, err := NuevaBusqueda(ConTexto(" zapatillas "), PrecioEntre(50, 120), SoloConStock())
fmt.Printf("%+v %v\n", busqueda, err)
// Las recetas se combinan con más opciones
ofertasLaptops, _ := NuevaBusqueda(slices.Concat(OfertasDelDia, []Opcion{ConTexto("laptop")})...)
fmt.Println(ofertasLaptops.Texto, ofertasLaptops.Orden) // laptop descuento
_, err = NuevaBusqueda(PrecioEntre(200, 100))
fmt.Println(err) // rango de precio inválido
}LO IDIOMÁTICO EN RUST: El builder idiomático de Rust toma self por valor en cada paso y lo devuelve (fn texto(mut self, ...) -> Self), así se encadena sin referencias. build() devuelve un Result, y #[derive(Default)] aporta los valores iniciales.
#[derive(Debug, Clone, Copy, Default)]
enum Orden {
#[default]
Relevancia,
Descuento,
Novedad,
}
struct Busqueda {
texto: Option<String>,
precio: Option<(f64, f64)>,
solo_con_stock: bool,
orden: Orden,
}
impl Busqueda {
fn resumen(&self) -> String {
let precio = self
.precio
.map_or("sin rango".to_string(), |(min, max)| format!("{min}-{max}"));
format!(
"texto={:?}, precio={precio}, solo_con_stock={}, orden={:?}",
self.texto, self.solo_con_stock, self.orden
)
}
}
#[derive(Default)]
struct BusquedaBuilder {
texto: Option<String>,
precio: Option<(f64, f64)>,
solo_con_stock: bool,
orden: Orden,
}
impl BusquedaBuilder {
fn texto(mut self, texto: &str) -> Self {
self.texto = Some(texto.trim().to_string());
self
}
fn precio_entre(mut self, min: f64, max: f64) -> Self {
self.precio = Some((min, max));
self
}
fn solo_con_stock(mut self) -> Self {
self.solo_con_stock = true;
self
}
fn ordenar_por(mut self, orden: Orden) -> Self {
self.orden = orden;
self
}
fn build(self) -> Result<Busqueda, String> {
if let Some((min, max)) = self.precio
&& min > max
{
return Err("rango de precio inválido".to_string());
}
Ok(Busqueda {
texto: self.texto,
precio: self.precio,
solo_con_stock: self.solo_con_stock,
orden: self.orden,
})
}
}
// Director: recetas que siempre ejecutan los mismos pasos
fn ofertas_del_dia() -> Result<Busqueda, String> {
BusquedaBuilder::default()
.solo_con_stock()
.ordenar_por(Orden::Descuento)
.build()
}
fn novedades(texto: &str) -> Result<Busqueda, String> {
BusquedaBuilder::default()
.texto(texto)
.ordenar_por(Orden::Novedad)
.build()
}
fn main() -> Result<(), String> {
let busqueda = BusquedaBuilder::default()
.texto(" zapatillas ")
.precio_entre(50.0, 120.0)
.solo_con_stock()
.build()?;
println!("{}", busqueda.resumen());
// texto=Some("zapatillas"), precio=50-120, solo_con_stock=true, orden=Relevancia
println!("{:?}", ofertas_del_dia()?.orden); // Descuento
println!("{:?}", novedades("auriculares")?.orden); // Novedad
match BusquedaBuilder::default()
.precio_entre(200.0, 100.0)
.build()
{
Ok(_) => println!("no debería construirse"),
Err(error) => println!("{error}"), // rango de precio inválido
}
Ok(())
}LO IDIOMÁTICO EN PHP: Con los argumentos con nombre de PHP 8, new Busqueda(texto: ..., orden: ...) ya evita el constructor telescópico. El builder aporta cuando el objeto se arma por pasos: aquí es inmutable y cada paso devuelve una copia con clone($this, [...]), la sintaxis "clone with" de PHP 8.5.
<?php
declare(strict_types=1);
enum Orden: string
{
case Relevancia = 'relevancia';
case Descuento = 'descuento';
case Novedad = 'novedad';
}
final readonly class Busqueda
{
public function __construct(
public ?string $texto = null,
public ?float $precioMin = null,
public ?float $precioMax = null,
public bool $soloConStock = false,
public Orden $orden = Orden::Relevancia,
) {
if ($precioMin !== null && $precioMax !== null && $precioMin > $precioMax) {
throw new InvalidArgumentException('Rango de precio inválido');
}
}
}
final readonly class BusquedaBuilder
{
public function __construct(
private ?string $texto = null,
private ?float $precioMin = null,
private ?float $precioMax = null,
private bool $soloConStock = false,
private Orden $orden = Orden::Relevancia,
) {}
public function texto(string $texto): static { return clone($this, ['texto' => trim($texto)]); }
public function precioEntre(float $min, float $max): static { return clone($this, ['precioMin' => $min, 'precioMax' => $max]); }
public function soloConStock(): static { return clone($this, ['soloConStock' => true]); }
public function ordenarPor(Orden $orden): static { return clone($this, ['orden' => $orden]); }
public function build(): Busqueda
{
return new Busqueda($this->texto, $this->precioMin, $this->precioMax, $this->soloConStock, $this->orden);
}
}
// Construcción por pasos, por ejemplo a partir de los parámetros de la URL
$parametros = ['q' => ' zapatillas ', 'min' => '50', 'max' => '120', 'stock' => '1'];
$builder = new BusquedaBuilder();
if (isset($parametros['q'])) $builder = $builder->texto($parametros['q']);
if (isset($parametros['min'], $parametros['max'])) $builder = $builder->precioEntre((float) $parametros['min'], (float) $parametros['max']);
if (($parametros['stock'] ?? '') === '1') $builder = $builder->soloConStock();
var_dump($builder->build());
// Con todos los datos a mano, bastan los argumentos con nombre
echo (new Busqueda(texto: 'auriculares', orden: Orden::Novedad))->orden->value, "\n"; // novedad
try {
(new BusquedaBuilder())->precioEntre(200, 100)->build();
} catch (InvalidArgumentException $error) {
echo $error->getMessage(), "\n"; // Rango de precio inválido
}