Structs, Embedding & Field Promotion

Structs group named fields into a single type.

Embedding lets you compose behavior and fields from other types without inheritance, promoting exported members to the outer type.

Summary

A struct literal sets fields by name or position (if unambiguous).

Embedded fields must be unnamed and their type name becomes a field name for promotion.

Promoted fields and methods are callable on the outer value as if declared there, unless shadowed.

Recipe

Quick-reference recipe card - copy-paste ready.

package main
 
import "fmt"
 
type Logger struct{}
 
func (Logger) Log(msg string) { fmt.Println(msg) }
 
type Server struct {
    Logger
    Addr string
}
 
func main() {
    s := Server{Addr: ":8080"}
    s.Log("listening") // promoted method
    fmt.Println(s.Addr)
}

When to reach for this:

• Model records with named fields (User, Order, Config).
• Compose small capabilities via embedding (io.Reader, sync.Mutex).
• Expose promoted API only when the outer type truly is-a usage of the embedded type.
• Prefer explicit fields when names would collide or confuse readers.

Working Example

package main
 
import "fmt"
 
type Person struct {
    Name string
    Age  int
}
 
type Employee struct {
    Person
    ID     int
    Dept   string
}
 
func (p Person) Greet() string {
    return "hello, " + p.Name
}
 
func describe(e Employee) {
    fmt.Println(e.Name, e.ID, e.Greet())
}
 
func main() {
    e := Employee{
        Person: Person{Name: "Ada", Age: 36},
        ID:     1001,
        Dept:   "research",
    }
    describe(e)
 
    // Explicit outer field wins over promoted if names collide
    type Shadow struct {
        Person
        Name string
    }
    sh := Shadow{Person: Person{Name: "Grace"}, Name: "Override"}
    fmt.Println(sh.Name, sh.Person.Name)
}

What this demonstrates:

• Nested initialization with named struct literals.
• Method promotion from embedded Person to Employee.
• Field promotion: e.Name accesses embedded Person.Name.
• Outer fields shadow promoted names - use qualified access when both exist.

Deep Dive

How It Works

• Struct types are comparable when all fields are comparable.
• Embedding is syntactic sugar: the embedded type's exported fields and methods promote one level.
• Methods attach to the embedded type's method set; outer type gains those methods in its method set.
• Pointer receivers on embedded type still promote for addressable outer values.

Struct Literal Forms

Promotion Rules

Go Notes

// Embed interface to forward behavior
type ReadCloser struct {
    io.Reader
    io.Closer
}
 
// Embed mutex - zero value usable
type SafeMap struct {
    sync.Mutex
    m map[string]int
}

Gotchas

• Embedding only for composition - Promoted APIs leak embedded type's surface unexpectedly. Fix: embed unexported helper structs or delegate explicitly.
• Nil embedded pointer - Embedded *T with nil panics on promoted method call. Fix: ensure initialization or guard calls.
• JSON tags on embedded fields - Anonymous fields flatten in encoding/json by default. Fix: name fields or adjust tags when nesting matters.
• Comparable struct with slice field - Struct becomes non-comparable. Fix: do not use ==; compare fields manually.
• Shadowed field confusion - Readers may not know which Name applies. Fix: avoid duplicate field names across outer and embedded types.
• Embedding concrete type for "inheritance" - Go has no subclass polymorphism via embedding alone. Fix: use interfaces for behavior contracts.

Alternatives

FAQs

Related

• Pointers & the Address-of Operator - Pointer receivers and struct mutation
• Zero Values and Initialization - Struct literals and defaults
• Arrays, Slices & Maps at a Glance - Fields that hold collections
• Go Fundamentals Basics - Embedding quick example

External Related Links

• Effective Go - Official guide to writing clear, idiomatic Go.
• Go Language Specification - The formal language reference.
• Go by Example - Annotated practical code examples.
• The Go Programming Language (Paperback) - Donovan & Kernighan paperback.
• Learning Go (2nd Edition) - Jon Bodner.

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).

636f64656775696465732e696f7c6367696f3439377c323032363037