State in Go

The Problem

Objects with life cycles often accumulate large switch statements over status fields. An order may allow payment only in one state, shipping in another, and cancellation in several. As the workflow grows, those branches become harder to test and easier to break.

The Solution

State moves behavior and transition rules into dedicated state objects. In Go, the context stores an interface for the current state and delegates stateful operations to it. Each concrete state decides whether an action is allowed and what the next state should be.

Structure

flowchart TD
Client["Client"]
Order["Order
context"]
StateIface["OrderState
interface"]
Pending["PendingState"]
Paid["PaidState"]
Shipped["ShippedState"]
Cancelled["CancelledState"]

Client -->|"Pay() / Ship() / Cancel()"| Order
Order -->|"delegates to"| StateIface
Pending -.->|"implements"| StateIface
Paid -.->|"implements"| StateIface
Shipped -.->|"implements"| StateIface
Cancelled -.->|"implements"| StateIface
Pending -->|"Pay()"| Paid
Paid -->|"Ship()"| Shipped
Pending -->|"Cancel()"| Cancelled
Paid -->|"Cancel()"| Cancelled

• Context: Order stores the current state.
• State interface: Declares the operations that vary by state.
• Concrete states: Pending, paid, shipped, and cancelled states enforce different rules.
• Client: Calls operations on the order without branching on status values.

Implementation

This example models a basic order workflow. Each state object owns the legal transitions, and the order delegates Pay, Ship, and Cancel to whichever state is active.

package main

type Order struct {
	ID    string
	state OrderState
}

func NewOrder(id string) *Order {
	return &Order{ID: id, state: PendingState{}}
}

func (o *Order) setState(state OrderState) {
	o.state = state
}

func (o *Order) Status() string {
	return o.state.Name()
}

func (o *Order) Pay() error {
	return o.state.Pay(o)
}

func (o *Order) Ship() error {
	return o.state.Ship(o)
}

func (o *Order) Cancel() error {
	return o.state.Cancel(o)
}

package main

import "fmt"

type OrderState interface {
	Name() string
	Pay(order *Order) error
	Ship(order *Order) error
	Cancel(order *Order) error
}

type PendingState struct{}
type PaidState struct{}
type ShippedState struct{}
type CancelledState struct{}

func (PendingState) Name() string   { return "pending" }
func (PaidState) Name() string      { return "paid" }
func (ShippedState) Name() string   { return "shipped" }
func (CancelledState) Name() string { return "cancelled" }

func (PendingState) Pay(order *Order) error {
	order.setState(PaidState{})
	return nil
}

func (PendingState) Ship(order *Order) error {
	return fmt.Errorf("cannot ship pending order")
}

func (PendingState) Cancel(order *Order) error {
	order.setState(CancelledState{})
	return nil
}

func (PaidState) Pay(order *Order) error {
	return fmt.Errorf("order already paid")
}

func (PaidState) Ship(order *Order) error {
	order.setState(ShippedState{})
	return nil
}

func (PaidState) Cancel(order *Order) error {
	order.setState(CancelledState{})
	return nil
}

func (ShippedState) Pay(order *Order) error {
	return fmt.Errorf("shipped order cannot be paid again")
}

func (ShippedState) Ship(order *Order) error {
	return fmt.Errorf("order already shipped")
}

func (ShippedState) Cancel(order *Order) error {
	return fmt.Errorf("shipped order cannot be cancelled")
}

func (CancelledState) Pay(order *Order) error {
	return fmt.Errorf("cancelled order cannot be paid")
}

func (CancelledState) Ship(order *Order) error {
	return fmt.Errorf("cancelled order cannot be shipped")
}

func (CancelledState) Cancel(order *Order) error {
	return fmt.Errorf("order already cancelled")
}

package main

import "fmt"

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

	order := NewOrder("ORD-1003")
	fmt.Println(order.Status())
	_ = order.Pay()
	fmt.Println(order.Status())
	_ = order.Ship()
	fmt.Println(order.Status())
}

Real-World Analogy

Think of a traffic light. The same control box behaves differently depending on whether the current state is green, yellow, or red, and the legal next transition depends on that current state.

Pros and Cons

Best Practices

• Use State when behavior truly changes by lifecycle stage, not just because a label exists.
• Keep state interfaces focused on the operations that vary.
• Let concrete states own transitions so invalid moves stay localized.
• If state objects need no data, zero-sized structs keep the pattern lightweight in Go.
• Do not introduce State if a small switch is still simpler and unlikely to grow.

When to Use

• An object has a lifecycle with different allowed operations per stage.
• Status-based conditionals are spreading across the codebase.
• You want invalid transitions expressed close to the rules themselves.

When NOT to Use

• There are only a couple of stable branches and they are unlikely to grow.
• The transition logic is simpler as a small explicit switch.
• The extra objects would hide rather than clarify the workflow.