Builder in Go

The Problem

Some values are assembled through a sequence of steps, not one constructor call. When those steps live inline in handlers, the workflow becomes repetitive and the output format becomes hard to change. The same order summary may need to produce a customer-facing confirmation, an ops checklist, or an internal export.

The Solution

Builder pulls the construction steps into a dedicated object while a director coordinates the sequence. In Go, the pattern often appears as a focused interface with methods that add sections, totals, or metadata. The builder accumulates state, and the caller decides which concrete builder to use.

Structure

flowchart TD
Client["Client"]
Director["Director"]
Builder["SummaryBuilder
interface"]
Concrete["MarkdownSummaryBuilder"]
Product["CheckoutSummary"]

Client -->|"selects builder"| Director
Director -->|"AddHeader, AddLineItems, AddTotal"| Builder
Concrete -.->|"implements"| Builder
Concrete -->|"Build()"| Product

• Product: CheckoutSummary is the value being assembled.
• Builder interface: Declares the steps needed to produce the summary.
• Concrete builder: MarkdownSummaryBuilder stores output in a markdown-friendly form.
• Director: CheckoutSummaryDirector runs the construction steps in a fixed order.
• Client: Chooses the builder and asks the director to assemble the result.

Implementation

This example turns an order into a formatted checkout summary. The director always performs the same steps, while the builder owns how the final representation is assembled and rendered.

package main

import (
	"fmt"
	"strings"
)

type LineItem struct {
	Name      string
	Qty       int
	UnitPrice int
}

type Order struct {
	ID       string
	Customer string
	Items    []LineItem
}

func (o Order) Total() int {
	total := 0
	for _, item := range o.Items {
		total += item.Qty * item.UnitPrice
	}
	return total
}

type CheckoutSummary struct {
	Title  string
	Body   []string
	Footer string
}

func (s CheckoutSummary) Render() string {
	parts := []string{s.Title}
	parts = append(parts, s.Body...)
	parts = append(parts, s.Footer)
	return strings.Join(parts, "\n")
}

func formatMoney(cents int) string {
	return fmt.Sprintf("$%.2f", float64(cents)/100)
}

package main

import "fmt"

type CheckoutSummaryBuilder interface {
	Reset()
	SetTitle(order Order)
	AddItems(order Order)
	SetFooter(order Order)
	Build() CheckoutSummary
}

type MarkdownSummaryBuilder struct {
	summary CheckoutSummary
}

func (b *MarkdownSummaryBuilder) Reset() {
	b.summary = CheckoutSummary{}
}

func (b *MarkdownSummaryBuilder) SetTitle(order Order) {
	b.summary.Title = fmt.Sprintf("# Order %s for %s", order.ID, order.Customer)
}

func (b *MarkdownSummaryBuilder) AddItems(order Order) {
	for _, item := range order.Items {
		line := fmt.Sprintf("- %dx %s (%s)", item.Qty, item.Name, formatMoney(item.UnitPrice))
		b.summary.Body = append(b.summary.Body, line)
	}
}

func (b *MarkdownSummaryBuilder) SetFooter(order Order) {
	b.summary.Footer = "Total: " + formatMoney(order.Total())
}

func (b *MarkdownSummaryBuilder) Build() CheckoutSummary {
	return b.summary
}

package main

type CheckoutSummaryDirector struct {
	builder CheckoutSummaryBuilder
}

func NewCheckoutSummaryDirector(builder CheckoutSummaryBuilder) CheckoutSummaryDirector {
	return CheckoutSummaryDirector{builder: builder}
}

func (d CheckoutSummaryDirector) Build(order Order) CheckoutSummary {
	d.builder.Reset()
	d.builder.SetTitle(order)
	d.builder.AddItems(order)
	d.builder.SetFooter(order)
	return d.builder.Build()
}

package main

import "fmt"

func main() {
	fmt.Println("=== Builder in Go ===")

	order := Order{
		ID:       "ORD-1001",
		Customer: "Nika",
		Items: []LineItem{
			{Name: "Mechanical Keyboard", Qty: 1, UnitPrice: 12900},
			{Name: "Desk Mat", Qty: 1, UnitPrice: 2500},
		},
	}

	builder := &MarkdownSummaryBuilder{}
	director := NewCheckoutSummaryDirector(builder)
	summary := director.Build(order)

	fmt.Println(summary.Render())
}

Real-World Analogy

Think of a kitchen assembling the same order into different outputs. One workflow collects the same ingredients and steps, but one builder plates a dine-in meal while another packs a delivery box with labels and receipts.

Pros and Cons

Best Practices

• Use Builder when construction has meaningful steps or optional sections, not just many fields.
• Keep the director optional. In Go, direct builder calls are fine when the sequence is already obvious.
• Prefer explicit step names over generic SetField methods so the workflow stays readable.
• Return a final immutable value from Build rather than exposing the builder internals.
• Do not force Builder where functional options or a plain constructor already solve the problem more simply.

When to Use

• Construction involves multiple ordered steps or reusable recipes.
• The same input flow may produce different final representations.
• You want to keep assembly logic out of transport handlers and services.

When NOT to Use

• A constructor or struct literal is already clear enough.
• The build steps add ceremony without capturing real workflow.
• Only field assignment changes and there is no reusable assembly process.