Builder

The Builder pattern separates the construction of a complex object from its final representation, so the same step-by-step process can yield different results. It targets a familiar pain point: constructors with long, error-prone parameter lists (the "telescoping constructor" problem) and objects that require many optional fields or careful assembly ordering.

How It Works

A Builder exposes methods for configuring parts of a product, then a terminal build() method that returns the finished object. The classic GoF form adds a Director that encapsulates a specific construction sequence, calling builder steps in order; the same Director can drive different concrete builders to produce different representations. In modern practice the Director is often omitted, and the builder offers a fluent, chainable API instead.

Because the product is only assembled at build(), the pattern naturally supports immutability: fields are gathered on the builder and passed to the product's constructor all at once, after which the product never changes.

When to Use It

Use Builder when an object has many fields — especially optional ones — when construction must happen in steps, or when you want to produce several representations from one process. It shines for configuration objects, query builders, test-data factories, and immutable domain entities. A fluent builder also dramatically improves call-site readability compared with positional arguments.

Do not use it for objects with two or three simple fields; a constructor or a record is simpler. Builders add boilerplate that only pays off above a certain complexity threshold.

Trade-offs

Builders make complex construction readable and self-documenting, enable immutable objects, and let you validate invariants in build() before the object exists. They isolate assembly logic and allow varying representations.

The cost is duplication: each product needs a parallel builder, and adding a field means touching both. Naive builders can also produce partially configured objects if build() is called early without required fields, so validation matters. Some languages mitigate the boilerplate with code generation (for example, Lombok in Java) or named/default arguments, which can make a hand-written builder unnecessary.

Related Patterns

Builder is a creational sibling of Abstract Factory and Factory Method, but it focuses on one complex object assembled over multiple calls rather than producing products in a single call. It frequently presents a Fluent Interface. A Composite is a common product of a builder, since trees are awkward to build in one constructor.

Example

An HTTP client request is built fluently: Request.builder().url("/users").method(POST).header("Authorization", token).body(json).timeout(30).build(). Only url is required; everything else is optional. The build() method validates the URL and returns an immutable Request. The same builder API could feed a Director that constructs a standardized "retryable request" by always adding retry headers.