phant-app/go-defensive

Go Defensive Programming Patterns

Verify Interface Compliance

Source: Uber Go Style Guide

Verify interface compliance at compile time using zero-value assertions.

Bad

type Handler struct{}

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
  // ...
}

Good

type Handler struct{}

var _ http.Handler = (*Handler)(nil)

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
  // ...
}

Use nil for pointer types, slices, maps; empty struct {} for value receivers.

Copy Slices and Maps at Boundaries

Source: Uber Go Style Guide

Slices and maps contain pointers. Copy at API boundaries to prevent unintended modifications.

Receiving

Bad

func (d *Driver) SetTrips(trips []Trip) {
  d.trips = trips  // caller can still modify d.trips
}

Good

func (d *Driver) SetTrips(trips []Trip) {
  d.trips = make([]Trip, len(trips))
  copy(d.trips, trips)
}

Returning

Bad

func (s *Stats) Snapshot() map[string]int {
  s.mu.Lock()
  defer s.mu.Unlock()
  return s.counters  // exposes internal state!
}

Good

func (s *Stats) Snapshot() map[string]int {
  s.mu.Lock()
  defer s.mu.Unlock()
  result := make(map[string]int, len(s.counters))
  for k, v := range s.counters {
    result[k] = v
  }
  return result
}

Defer to Clean Up

Source: Uber Go Style Guide, Effective Go

Use defer to clean up resources (files, locks). Avoids missed cleanup on multiple returns.

Bad

p.Lock()
if p.count < 10 {
  p.Unlock()
  return p.count
}
p.count++
newCount := p.count
p.Unlock()
return newCount  // easy to miss unlocks

Good

p.Lock()
defer p.Unlock()

if p.count < 10 {
  return p.count
}
p.count++
return p.count

Defer overhead is negligible. Only avoid in nanosecond-critical paths.

Defer for File Operations

Place defer f.Close() immediately after opening a file for clarity:

func Contents(filename string) (string, error) {
    f, err := os.Open(filename)
    if err != nil {
        return "", err
    }
    defer f.Close()  // Close sits near Open - much clearer

    var result []byte
    buf := make([]byte, 100)
    for {
        n, err := f.Read(buf[0:])
        result = append(result, buf[0:n]...)
        if err != nil {
            if err == io.EOF {
                break
            }
            return "", err  // f will be closed
        }
    }
    return string(result), nil  // f will be closed
}

Defer Argument Evaluation

Arguments to deferred functions are evaluated when defer executes, not when the deferred function runs:

for i := 0; i < 5; i++ {
    defer fmt.Printf("%d ", i)
}
// Prints: 4 3 2 1 0 (LIFO order, values captured at defer time)

Defer LIFO Order

Multiple defers execute in Last-In-First-Out order:

func trace(s string) string {
    fmt.Println("entering:", s)
    return s
}

func un(s string) {
    fmt.Println("leaving:", s)
}

func a() {
    defer un(trace("a"))  // trace() runs now, un() runs at return
    fmt.Println("in a")
}
// Output: entering: a, in a, leaving: a

Start Enums at One

Source: Uber Go Style Guide

Start enums at non-zero to distinguish uninitialized from valid values.

Bad

const (
  Add Operation = iota  // Add=0, zero value looks valid
  Subtract
  Multiply
)

Good

const (
  Add Operation = iota + 1  // Add=1, zero value = uninitialized
  Subtract
  Multiply
)

Exception: When zero is the sensible default (e.g., LogToStdout = iota).

Use time.Time and time.Duration

Source: Uber Go Style Guide

Always use the time package. Avoid raw int for time values.

Instants

Bad

func isActive(now, start, stop int) bool {
  return start <= now && now < stop
}

Good

func isActive(now, start, stop time.Time) bool {
  return (start.Before(now) || start.Equal(now)) && now.Before(stop)
}

Durations

Bad

func poll(delay int) {
  time.Sleep(time.Duration(delay) * time.Millisecond)
}
poll(10)  // seconds? milliseconds?

Good

func poll(delay time.Duration) {
  time.Sleep(delay)
}
poll(10 * time.Second)

JSON Fields

When time.Duration isn't possible, include unit in field name:

Bad

type Config struct {
  Interval int `json:"interval"`
}

Good

type Config struct {
  IntervalMillis int `json:"intervalMillis"`
}

Avoid Mutable Globals

Source: Uber Go Style Guide

Use dependency injection instead of mutable globals.

Bad

var _timeNow = time.Now

func sign(msg string) string {
  now := _timeNow()
  return signWithTime(msg, now)
}

// Test requires save/restore of global
func TestSign(t *testing.T) {
  oldTimeNow := _timeNow
  _timeNow = func() time.Time { return someFixedTime }
  defer func() { _timeNow = oldTimeNow }()
  assert.Equal(t, want, sign(give))
}

Good

type signer struct {
  now func() time.Time
}

func newSigner() *signer {
  return &signer{now: time.Now}
}

func (s *signer) Sign(msg string) string {
  now := s.now()
  return signWithTime(msg, now)
}

// Test injects dependency cleanly
func TestSigner(t *testing.T) {
  s := newSigner()
  s.now = func() time.Time { return someFixedTime }
  assert.Equal(t, want, s.Sign(give))
}

Avoid Embedding Types in Public Structs

Source: Uber Go Style Guide

Embedded types leak implementation details and inhibit type evolution.

Bad

type ConcreteList struct {
  *AbstractList
}

Good

type ConcreteList struct {
  list *AbstractList
}

func (l *ConcreteList) Add(e Entity) {
  l.list.Add(e)
}

func (l *ConcreteList) Remove(e Entity) {
  l.list.Remove(e)
}

Embedding problems:

• Adding methods to embedded interface is a breaking change
• Removing methods from embedded struct is a breaking change
• Replacing the embedded type is a breaking change

Use Field Tags in Marshaled Structs

Source: Uber Go Style Guide

Always use explicit field tags for JSON, YAML, etc.

Bad

type Stock struct {
  Price int
  Name  string
}

Good

type Stock struct {
  Price int    `json:"price"`
  Name  string `json:"name"`
  // Safe to rename Name to Symbol
}

Tags make the serialization contract explicit and safe to refactor.

---

Crypto Rand

Source: Go Wiki CodeReviewComments (Normative)

Do not use math/rand or math/rand/v2 to generate keys, even throwaway ones. This is a security concern.

Unseeded or time-seeded random generators have predictable output:

• Time.Nanoseconds() provides only a few bits of entropy
• Keys generated this way can be guessed by attackers

Use crypto/rand instead:

import (
	"crypto/rand"
)

func Key() string {
	return rand.Text()
}

For text output:

• Use crypto/rand.Text directly (preferred)
• Or encode random bytes with encoding/hex or encoding/base64

---

Panic and Recover

Source: Effective Go

Use panic only for truly unrecoverable situations. Library functions should avoid panic—if the problem can be worked around, let things continue rather than taking down the whole program.

Use recover to regain control of a panicking goroutine (only works inside deferred functions):

func safelyDo(work *Work) {
    defer func() {
        if err := recover(); err != nil {
            log.Println("work failed:", err)
        }
    }()
    do(work)
}

Key rules:

• Never expose panics across package boundaries—always convert to errors
• Acceptable to panic in init() if a library truly cannot set itself up
• Use recover to isolate panics in server goroutine handlers

For detailed patterns including server protection and package-internal panic/recover, see references/PANIC-RECOVER.md.

---

Quick Reference

| Pattern | Rule | |---------|------| | Interface compliance | var _ Interface = (*Type)(nil) | | Receiving slices/maps | Copy before storing | | Returning slices/maps | Return a copy | | Resource cleanup | Use defer | | Defer argument timing | Evaluated at defer, not call time | | Enums | Start at iota + 1 | | Time instants | Use time.Time | | Time durations | Use time.Duration | | Mutable globals | Use dependency injection | | Type embedding | Use explicit delegation | | Serialization | Always use field tags | | Key generation | Use crypto/rand, never math/rand | | Panic usage | Only for truly unrecoverable situations | | Recover pattern | Use in defer; convert to error at API boundary |

See Also

• go-style-core - Core Go style principles
• go-concurrency - Goroutine and channel patterns
• go-error-handling - Error handling best practices