
A struct groups related fields under one name. Structs are the primary way to define domain types in Go - Go has no classes, but structs with methods give you all the encapsulation you need.

<ExamplePair>
<ExampleProse>

Define a struct with `type Name struct { ... }`. Fields have a name and a type. Access fields with `.`. The zero value of a struct is a struct with all fields zeroed - no constructor required.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

type Person struct {
    Name string
    Age  int
}

func main() {
    // Struct literal - positional (fragile, avoid in production)
    p1 := Person{"Alice", 30}

    // Named fields - order-independent, recommended
    p2 := Person{Name: "Bob", Age: 25}

    // Zero value - all fields are zeroed
    var p3 Person

    fmt.Println(p1, p2, p3)
    fmt.Println(p2.Name, p2.Age) // Bob 25

    p2.Age = 26 // field mutation
    fmt.Println(p2.Age) // 26
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

An anonymous struct has no named type. Use them for one-off groupings - test table entries, local temporary aggregations - where defining a named type would be noise.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func main() {
    point := struct {
        X, Y int
    }{X: 3, Y: 7}

    fmt.Println(point.X, point.Y) // 3 7

    // Common in table-driven tests:
    cases := []struct {
        input    int
        expected int
    }{
        {1, 2},
        {5, 10},
    }
    for _, c := range cases {
        fmt.Println(c.input, "->", c.expected)
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Embedding includes one struct type inside another without a field name. The outer struct promotes the embedded type's fields and methods - they are accessible directly. This is composition, not inheritance.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

type Animal struct {
    Name string
}

func (a Animal) Speak() string {
    return a.Name + " makes a sound"
}

type Dog struct {
    Animal        // embedded - Dog promotes Name and Speak
    Breed  string
}

func main() {
    d := Dog{
        Animal: Animal{Name: "Rex"},
        Breed:  "Labrador",
    }

    // Promoted fields and methods - accessed directly on Dog
    fmt.Println(d.Name)   // Rex  (promoted from Animal)
    fmt.Println(d.Speak()) // Rex makes a sound (promoted from Animal)
    fmt.Println(d.Breed)  // Labrador
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Struct embedding promotes methods but the embedded type is still the receiver - the promoted method runs on the embedded value, not on the outer struct. If `Dog` tries to override `Speak` by defining its own `Speak` method, the outer method shadows the promoted one - but there is no polymorphic dispatch the way inheritance provides. Teams that treat embedding as inheritance get surprised when promoted methods bypass overrides, especially when the promoted method holds a reference to the embedded type and calls back into it. The [outbox pattern](/patterns/outbox) is a case where embedded structs appear in event payloads - the field ordering and zero-value behaviour of embedded types must be understood before serialising them.
</InProduction>


Struct definition, field access, struct literals, anonymous structs, embedding, and promoted fields.

Structs


A method is a function with a receiver - a named type that the function is bound to. Any named type (not just structs) can have methods. Methods are how Go expresses behaviour.

<ExamplePair>
<ExampleProse>

Declare a method by placing the receiver before the function name. A value receiver operates on a copy - mutations do not affect the original. A pointer receiver operates on the original - mutations persist.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

type Rectangle struct {
    Width, Height float64
}

// Value receiver - read-only, works on a copy
func (r Rectangle) Area() float64 {
    return r.Width * r.Height
}

// Value receiver - read-only
func (r Rectangle) Perimeter() float64 {
    return 2 * (r.Width + r.Height)
}

// Pointer receiver - mutates the original
func (r *Rectangle) Scale(factor float64) {
    r.Width *= factor
    r.Height *= factor
}

func main() {
    rect := Rectangle{Width: 10, Height: 5}
    fmt.Println(rect.Area())      // 50
    fmt.Println(rect.Perimeter()) // 30

    rect.Scale(2)
    fmt.Println(rect.Area()) // 200 - Width and Height were mutated
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Go interfaces are satisfied implicitly - there is no `implements` keyword. If a type has all the methods an interface requires, it satisfies the interface automatically. This allows adapters to be written without modifying the original type.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "math"
)

type Shape interface {
    Area() float64
}

type Circle struct {
    Radius float64
}

func (c Circle) Area() float64 {
    return math.Pi * c.Radius * c.Radius
}

type Rectangle struct {
    Width, Height float64
}

func (r Rectangle) Area() float64 {
    return r.Width * r.Height
}

func printArea(s Shape) {
    fmt.Printf("%.2f\n", s.Area())
}

func main() {
    // Both satisfy Shape without any explicit declaration
    printArea(Circle{Radius: 5})        // 78.54
    printArea(Rectangle{Width: 4, Height: 6}) // 24.00
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Because interface satisfaction is implicit, a typo in a method signature silently drops the satisfaction - no compile error. Add a compile-time assertion to catch this immediately.

</ExampleProse>
<ExampleCode>

```go
package main

type Writer interface {
    Write(p []byte) (n int, err error)
}

type MyWriter struct{}

func (w *MyWriter) Write(p []byte) (int, error) {
    return len(p), nil
}

// Compile-time check: if *MyWriter stops satisfying Writer,
// this line produces a compile error immediately.
var _ Writer = (*MyWriter)(nil)

func main() {
    var w Writer = &MyWriter{}
    n, _ := w.Write([]byte("hello"))
    _ = n
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Go interfaces are satisfied implicitly - this is powerful (write an adapter for any third-party type without modifying it) and risky (a one-character typo in a method name silently drops interface satisfaction). The `var _ SomeInterface = (*MyType)(nil)` pattern adds a zero-cost compile-time assertion that produces a clear error the moment the interface is broken. Add one of these assertions in the file where the type is declared - not in a test file - so it is always compiled, not just when tests run. This pattern is especially important for interfaces that are checked at runtime (HTTP handlers, database drivers, event consumers) where a missed satisfaction surfaces as a nil-dereference panic at request time rather than a compile error.
</InProduction>


Method declaration, pointer vs value receivers, method sets, and implicit interface satisfaction.

Methods


A pointer holds the memory address of a value. Go has pointers but no pointer arithmetic - you cannot increment a pointer to step through memory the way C allows. This keeps pointers useful (sharing, avoiding copies, mutating through function calls) without most of the footguns.

<ExamplePair>
<ExampleProse>

`&` takes the address of a value and produces a pointer. `*` dereferences a pointer - it reads the value at that address. Assigning through a dereferenced pointer mutates the original.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func increment(n *int) {
    *n++ // dereference and mutate
}

func main() {
    x := 42
    p := &x // p is *int, holds address of x

    fmt.Println(x, *p) // 42 42 - same value, two ways to reach it

    *p = 100
    fmt.Println(x) // 100 - x was mutated through p

    increment(&x)
    fmt.Println(x) // 101
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Struct fields are accessed through a pointer with the same `.` syntax as value access - Go automatically dereferences the pointer. The `new` built-in allocates a zeroed value and returns a pointer to it.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

type Point struct {
    X, Y int
}

func main() {
    // Pointer to struct via & on a literal
    p := &Point{X: 1, Y: 2}

    // Field access through pointer - no explicit dereference needed
    fmt.Println(p.X, p.Y) // 1 2
    p.X = 10
    fmt.Println(p.X) // 10

    // new: allocates a zeroed Point and returns *Point
    q := new(Point)
    fmt.Println(q.X, q.Y) // 0 0
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The zero value of a pointer is `nil`. Dereferencing a nil pointer causes a panic at runtime. Always check before dereferencing a pointer that may be nil.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func describe(p *Point) string {
    if p == nil {
        return "<nil>"
    }
    return fmt.Sprintf("(%d, %d)", p.X, p.Y)
}

type Point struct{ X, Y int }

func main() {
    var p *Point // nil
    fmt.Println(describe(p))            // <nil>
    fmt.Println(describe(&Point{3, 4})) // (3, 4)
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
If any method on a type needs to mutate the receiver, all methods on that type should use pointer receivers - mixing pointer and value receivers on the same named type breaks the method set and can cause a type to fail to satisfy an interface in non-obvious ways. The rule of thumb: use a pointer receiver if the struct is large (avoids copies on every call), if any method needs to mutate state, or if the zero value of the type is not meaningful. Use a value receiver only when the struct is small and all methods are read-only. Consistency within a type is more important than the size heuristic.
</InProduction>


The & and * operators, pointer to struct, nil pointer, and the pointer vs value semantics decision.