Builder Pattern · Design Patterns

What is the Builder pattern?

Builder means: you build an object step by step, setting only what you need, then call one method to get the finished object.

You do not write one giant constructor with many parameters. You chain small calls, then finish.

To build it you usually:

Create a separate builder that collects values.
Chain calls by returning the builder itself each time.
Add one build() method that checks everything and returns the final object.

The problem it solves

Without a builder, an object with many optional pieces gets a constructor (or function) with a long, easy-to-misuse parameter list.

class Computer:
    def __init__(self, cpu, ram, storage=None, gpu=None, wifi_card=None, extra_fans=0):
        ...

# caller who only wants cpu + ram still has to line up every slot:
c = Computer("i7", "16GB", None, None, None, 0)

public Computer(String cpu, String ram, String storage, String gpu,
                 String wifiCard, int extraFans) { /* ... */ }

// caller who only wants cpu + ram still passes everything, in order:
Computer c = new Computer("i7", "16GB", null, null, null, 0);

func NewComputer(cpu, ram, storage, gpu, wifiCard string, extraFans int) *Computer {
	// ...
}

// caller who only wants cpu + ram still passes empty placeholders:
c := NewComputer("i7", "16GB", "", "", "", 0)

function createComputer(
  cpu: string, ram: string, storage?: string,
  gpu?: string, wifiCard?: string, extraFans = 0,
) { /* ... */ }

// caller who only wants cpu + ram still passes undefined in order:
const c = createComputer('i7', '16GB', undefined, undefined, undefined, 0);

Add one more optional field, and every call site gets another slot to worry about — or you add another overload, and now there are three ways to build the same thing.

You want a way to say, in your own words: this computer has this CPU and this RAM — I don’t care about the rest.

The classic builder

A builder is a small helper object that collects values one at a time, then produces the finished object. Each setter returns the builder itself, so calls can chain onto one line.

class Computer:
    def __init__(self, cpu: str, ram: str, storage: str | None = None, gpu: str | None = None) -> None:
        self.cpu = cpu
        self.ram = ram
        self.storage = storage
        self.gpu = gpu


class ComputerBuilder:
    def __init__(self) -> None:
        self._cpu: str | None = None
        self._ram: str | None = None
        self._storage: str | None = None
        self._gpu: str | None = None

    def cpu(self, cpu: str) -> "ComputerBuilder":
        self._cpu = cpu
        return self

    def ram(self, ram: str) -> "ComputerBuilder":
        self._ram = ram
        return self

    def storage(self, storage: str) -> "ComputerBuilder":
        self._storage = storage
        return self

    def build(self) -> Computer:
        if not self._cpu or not self._ram:
            raise ValueError("CPU and RAM are required")
        return Computer(self._cpu, self._ram, self._storage, self._gpu)


# use
computer = (
    ComputerBuilder()
    .cpu("Intel i7")
    .ram("16GB")
    .storage("512GB SSD")
    .build()
)

public class Computer {
    private final String cpu;
    private final String ram;
    private final String storage;
    private final String gpu;

    private Computer(Builder builder) {
        this.cpu = builder.cpu;
        this.ram = builder.ram;
        this.storage = builder.storage;
        this.gpu = builder.gpu;
    }

    public static class Builder {
        private String cpu;
        private String ram;
        private String storage;
        private String gpu;

        public Builder cpu(String cpu) { this.cpu = cpu; return this; }
        public Builder ram(String ram) { this.ram = ram; return this; }
        public Builder storage(String storage) { this.storage = storage; return this; }
        public Builder gpu(String gpu) { this.gpu = gpu; return this; }

        public Computer build() {
            if (cpu == null || ram == null) {
                throw new IllegalArgumentException("CPU and RAM are required");
            }
            return new Computer(this);
        }
    }
}

// use
Computer computer = new Computer.Builder()
    .cpu("Intel i7")
    .ram("16GB")
    .storage("512GB SSD")
    .build();

package computer

import "errors"

type Computer struct {
	CPU     string
	RAM     string
	Storage string
	GPU     string
}

type Builder struct {
	computer Computer
}

func NewBuilder() *Builder {
	return &Builder{}
}

func (b *Builder) CPU(cpu string) *Builder {
	b.computer.CPU = cpu
	return b
}

func (b *Builder) RAM(ram string) *Builder {
	b.computer.RAM = ram
	return b
}

func (b *Builder) Storage(storage string) *Builder {
	b.computer.Storage = storage
	return b
}

func (b *Builder) Build() (*Computer, error) {
	if b.computer.CPU == "" || b.computer.RAM == "" {
		return nil, errors.New("cpu and ram are required")
	}
	return &b.computer, nil
}

// use
// c, err := computer.NewBuilder().CPU("Intel i7").RAM("16GB").Storage("512GB SSD").Build()

class Computer {
  constructor(
    readonly cpu: string,
    readonly ram: string,
    readonly storage?: string,
    readonly gpu?: string,
  ) {}
}

class ComputerBuilder {
  private cpu?: string;
  private ram?: string;
  private storage?: string;
  private gpu?: string;

  setCpu(cpu: string) { this.cpu = cpu; return this; }
  setRam(ram: string) { this.ram = ram; return this; }
  setStorage(storage: string) { this.storage = storage; return this; }
  setGpu(gpu: string) { this.gpu = gpu; return this; }

  build() {
    if (!this.cpu || !this.ram) {
      throw new Error('CPU and RAM are required');
    }
    return new Computer(this.cpu, this.ram, this.storage, this.gpu);
  }
}

// use
const computer = new ComputerBuilder()
  .setCpu('Intel i7')
  .setRam('16GB')
  .setStorage('512GB SSD')
  .build();

Notice three things. Every setter returns the builder, so calls chain. The finished object’s fields are set once and never touched again. And build() checks the required fields before handing back an object, catching a mistake right away instead of downstream.

Worked example: assembling an order

A more realistic case: an order with a required id, a variable number of items, and an optional note.

class Order:
    def __init__(self, id: str, items: list[str], note: str | None = None) -> None:
        self.id = id
        self.items = list(items)
        self.note = note

    def summary(self) -> str:
        return f"Order #{self.id} items={len(self.items)}"


class OrderBuilder:
    def __init__(self) -> None:
        self._id: str | None = None
        self._items: list[str] = []
        self._note: str | None = None

    def id(self, id: str) -> "OrderBuilder":
        self._id = id
        return self

    def add_item(self, item: str) -> "OrderBuilder":
        self._items.append(item)
        return self

    def note(self, note: str) -> "OrderBuilder":
        self._note = note
        return self

    def build(self) -> Order:
        if not self._id:
            raise ValueError("Order id is required")
        return Order(self._id, self._items, self._note)


# use
order = (
    OrderBuilder()
    .id("4412")
    .add_item("mug")
    .add_item("tea")
    .note("gift wrap")
    .build()
)

public class Order {
    private final String id;
    private final List<String> items;
    private final String note;

    private Order(Builder builder) {
        this.id = builder.id;
        this.items = List.copyOf(builder.items);
        this.note = builder.note;
    }

    public String summary() {
        return "Order #" + id + " items=" + items.size();
    }

    public static class Builder {
        private String id;
        private final List<String> items = new ArrayList<>();
        private String note;

        public Builder id(String id) { this.id = id; return this; }
        public Builder addItem(String item) { items.add(item); return this; }
        public Builder note(String note) { this.note = note; return this; }

        public Order build() {
            if (id == null) {
                throw new IllegalArgumentException("Order id is required");
            }
            return new Order(this);
        }
    }
}

// use
Order order = new Order.Builder()
    .id("4412")
    .addItem("mug")
    .addItem("tea")
    .note("gift wrap")
    .build();

package order

import (
	"errors"
	"fmt"
)

type Order struct {
	ID    string
	Items []string
	Note  string
}

func (o *Order) Summary() string {
	return fmt.Sprintf("Order #%s items=%d", o.ID, len(o.Items))
}

type Builder struct {
	order Order
}

func NewBuilder() *Builder {
	return &Builder{}
}

func (b *Builder) ID(id string) *Builder {
	b.order.ID = id
	return b
}

func (b *Builder) AddItem(item string) *Builder {
	b.order.Items = append(b.order.Items, item)
	return b
}

func (b *Builder) Note(note string) *Builder {
	b.order.Note = note
	return b
}

func (b *Builder) Build() (*Order, error) {
	if b.order.ID == "" {
		return nil, errors.New("order id is required")
	}
	return &b.order, nil
}

// use
// o, err := order.NewBuilder().ID("4412").AddItem("mug").AddItem("tea").Note("gift wrap").Build()

class Order {
  constructor(
    readonly id: string,
    readonly items: string[],
    readonly note?: string,
  ) {}

  summary() {
    return `Order #${this.id} items=${this.items.length}`;
  }
}

class OrderBuilder {
  private id?: string;
  private items: string[] = [];
  private note?: string;

  setId(id: string) { this.id = id; return this; }
  addItem(item: string) { this.items.push(item); return this; }
  setNote(note: string) { this.note = note; return this; }

  build() {
    if (!this.id) {
      throw new Error('Order id is required');
    }
    return new Order(this.id, this.items, this.note);
  }
}

// use
const order = new OrderBuilder()
  .setId('4412')
  .addItem('mug')
  .addItem('tea')
  .setNote('gift wrap')
  .build();

Notice addItem can be called any number of times. A plain constructor cannot express that cleanly — you would have to hand it a whole list up front.

When it helps

Builder earns its place when an object has many fields, especially optional ones, and you want the finished object to be immutable. It also helps when you need to check a combination of fields together — easier once, inside build(), than across many constructor overloads.

The test: does this object have enough optional or many-combination fields that a single constructor call would be hard to read at a glance?

When it hurts

For a class with two or three required fields, a builder is pure overhead. new Point(10, 20) is already clear — wrapping it in a builder just adds lines that say nothing new.

A builder also does not fix a poorly designed object. If a class needs thirty configurable fields, ask whether it is doing too much and should be split up.

Practical tips

Give the builder a private target and a build() that returns the finished object.
Return the builder itself from every setter, for chaining.
Put all validation in build(), not scattered across setters.
Make the finished object immutable — no setters, only getters.
Reach for a builder only once a constructor needs four or more parameters, several optional.

Check your understanding

Builder in one line?
Build the object step by step, then finish with one call.

What problem does it solve?
It avoids long, error-prone parameter lists while keeping the result immutable.

What makes a builder “fluent”?
Every setter returns the builder itself, so calls chain: .cpu(...).ram(...).build().

Where should validation live?
Inside build(), so rules spanning multiple fields are checked together.

When is a builder overkill?
A small class with two or three required fields — a plain constructor is clearer.

What to learn next

Next: Prototype Pattern — instead of assembling an object piece by piece, start from an existing one and clone it.