Builder Pattern and Fluent APIs

The Builder pattern decouples object construction from object representation. Instead of constructors with many parameters, a builder accumulates state through a series of method calls and produces the final object at the end. Combined with fluent return types, the result is readable, type-safe construction.

When Builder earns its place

Three situations:

Many optional parameters

A constructor with 5+ parameters becomes hard to read at the call site. With many optional parameters, the constructor combinatorics explode. Builders solve this:

Order order = Order.builder()
    .id("abc")
    .amount(99.99)
    .priority(Priority.HIGH)
    .deliveryDate(LocalDate.of(2026, 5, 1))
    .giftWrap(true)
    .build();

Each setter is named; the call is self-documenting. Adding a new field doesn't break callers.

Immutable construction with derivation

For immutable objects (records, value classes), the Builder pattern lets you construct incrementally without making the result mutable. The builder is mutable; the built object is not.

Step-by-step validation

Builders can validate at build(), after all fields are set. Constructors validate per-field; complex inter-field validation is awkward in constructors.

Fluent API style

A fluent API has methods that return this, allowing chaining:

public OrderBuilder amount(double amount) {
    this.amount = amount;
    return this;
}

Combined with the Builder pattern, you get the chain shown above. The same idea applies elsewhere: query builders, configuration objects, mock setup.

mockServer.expect(POST, "/api/orders")
    .andRespond(withStatus(201).body(json));

Fluent style works when the methods naturally compose. It's awkward when method order matters or when state transitions need to be explicit.

When Builder is overkill

Records with sensible defaults: Java records can have factory methods for common cases without builders
Few parameters (2-3): a clean constructor is fine
No optional parameters: just use a constructor
Single use site: build the object inline; don't generalize prematurely

Implementation patterns

Lombok @Builder

@Builder
public class Order {
    private final String id;
    private final BigDecimal amount;
    private final Priority priority;
}

Generates the builder at compile time. Less code, less to maintain.

Static method on the class

public class Order {
    public static Builder builder() { return new Builder(); }

    public static class Builder { /* ... */ }
}

Standard Java. More verbose but no annotation processor dependency.

Telescoping constructors (the alternative)

public Order(String id, BigDecimal amount) { ... }
public Order(String id, BigDecimal amount, Priority p) { ... }
public Order(String id, BigDecimal amount, Priority p, LocalDate d) { ... }

Works for 2-3 parameters; doesn't scale.

Common failure patterns

Builder for everything. Two-parameter constructor is fine.
Builder that allows invalid state. build() should validate.
Fluent API where order matters. Methods that must be called in specific sequence break under chaining.
Builder mutating the building object. The built object should be immutable; the builder is mutable.