• Book: The Complete Guide to Go Programming
• Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
• My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
• Me: xgabriel.com | GitHub

You've seen it. A Go service ships with a BaseRepository embedded in twenty other repositories, a BaseService embedded in fifteen others, and a Logger embedded into anything that wants a Log method. The team calls it "the base class". They override methods on it, expect virtual dispatch, expect super, and assume interface satisfaction will follow intent.

None of those things exist in Go. The shape that looks like inheritance is composition with a side door, and that side door is the source of three bug patterns I keep finding in codebases written by engineers who came across from Java or C#.

The Go spec is unambiguous on this. The relevant lines are in Struct types and Selectors. Embedding promotes fields and methods of the embedded type into the outer type's method set. That is the entire mechanism. There is no virtual dispatch table, no super keyword, no notion that the outer type is "a kind of" the embedded one. The compiler is doing name promotion and nothing else.

That gap between expectation and reality is where the bugs live.

Trap 1: there is no virtual dispatch

A team I know shipped a BaseHandler with a RespondJSON method that called the handler's own Validate method before serialising. They wrote a UserHandler that embedded BaseHandler and defined a stricter Validate. They expected RespondJSON to call UserHandler.Validate. It does not.

package handler

import "errors"

type BaseHandler struct{}

func (b BaseHandler) Validate(req any) error {
    return nil
}

func (b BaseHandler) RespondJSON(req any) error {
    if err := b.Validate(req); err != nil {
        return err
    }
    return nil
}

type UserHandler struct {
    BaseHandler
}

func (u UserHandler) Validate(req any) error {
    return errors.New("user payload rejected")
}

In a language with virtual dispatch, calling userHandler.RespondJSON(req) would route the inner Validate call to UserHandler.Validate. In Go it does not. RespondJSON is defined on BaseHandler, and inside its body the receiver b is a BaseHandler. The b.Validate call resolves to BaseHandler.Validate at compile time. The stricter validation never runs.

The bug shipped to production. It passed tests because the tests called userHandler.Validate(req) directly, which does dispatch correctly because the method set of UserHandler shadows the embedded Validate. The flow that actually runs in the request path takes the inherited path and the inherited path is blind.

The fix is to stop using embedding for behaviour that needs to vary per outer type. Pass a function. Use an interface. Make the validator an explicit dependency.

package handler

type Validator interface {
    Validate(req any) error
}

type Responder struct {
    v Validator
}

func (r Responder) RespondJSON(req any) error {
    if err := r.v.Validate(req); err != nil {
        return err
    }
    return nil
}

Now Responder calls through an interface. The dispatch is dynamic because interface method calls are dispatched dynamically. The shape is composition, the contract is explicit, and the bug cannot recur.

Trap 2: shadowing without super

The second pattern is the call-the-base-version trap. You shadow a method on the outer type because you want to add behaviour, but you still want to call the embedded one. In Java you write super.foo(). In Go you write o.Embedded.Foo() and you say it out loud, because there is no shorthand and the compiler will not warn you if you forget.

A pattern that shows up in payments codebases: a Repository embeds a Tracer. The tracer has a Save method that emits a span. The repository defines its own Save to add a database call. The author meant for the repository's Save to also emit the span, and assumed the embedded Save would run automatically because that is what super does in Java when you call the method on yourself. That is not what Go does.

type Tracer struct{}

func (t Tracer) Save(ctx context.Context, name string) {
}

type UserRepo struct {
    Tracer
    db *sql.DB
}

func (r UserRepo) Save(ctx context.Context, u User) error {
    _, err := r.db.ExecContext(ctx, "INSERT ...")
    return err
}

r.Save(ctx, u) resolves to UserRepo.Save. The embedded Tracer.Save is never called. There is no chain. Shadowing in Go replaces; it does not extend.

If you want the embedded behaviour, you call it by name on the embedded field:

func (r UserRepo) Save(ctx context.Context, u User) error {
    r.Tracer.Save(ctx, "user.save")
    _, err := r.db.ExecContext(ctx, "INSERT ...")
    return err
}

This is fine when you know it. The harm is when you assume Go will do it for you. Reviewers from the Java side skim past func (r UserRepo) Save and check the box because the embedded Tracer is right there. The span is never emitted. The trace looks healthy because the spans that do exist are clean. Observability rots quietly.

Trap 3: surprise interface satisfaction

This one is the most insidious because it changes the API surface of your type without you writing any code.

A common pattern is "I want my service to have a Log method, so I'll embed *Logger". It works:

type Logger struct{}

func (l *Logger) Log(msg string) {}

type PaymentService struct {
    *Logger
    repo Repo
}

PaymentService now has a Log(string) method. So far so good. The trap is that PaymentService also satisfies any interface in your codebase that requires a Log(string) method, including ones the author of PaymentService never intended to satisfy.

type AuditTarget interface {
    Log(msg string)
}

func PublishToAuditTrail(t AuditTarget) { /* ... */ }

Six months later somebody wires PublishToAuditTrail(payment) and the compiler accepts it. The Log call inside PublishToAuditTrail was supposed to write to a tamper-evident audit store. It now writes to stdout. The Log method on PaymentService is the embedded Logger.Log, and that one writes to stdout. Compliance ticket. Same shape, different intent.

Embedding does not let you opt out of which interfaces your type satisfies. The promoted method set is part of the public API of the outer type whether you wanted it or not. If you want a method to exist for internal use only, you do not embed. You take the dependency as a private field and call it by name:

type PaymentService struct {
    log *Logger
    repo Repo
}

func (s *PaymentService) charge(ctx context.Context) error {
    s.log.Log("charging")
    return s.repo.Save(ctx)
}

PaymentService no longer has a public Log. It does not satisfy AuditTarget. The compiler will reject PublishToAuditTrail(payment) and you find out at build time instead of in a postmortem.

When embedding is the right answer

Embedding is the right answer when the outer type genuinely is, for the purposes of its API, a thin wrapper that adds fields or methods on top of the embedded one. bufio.ReadWriter embedding *bufio.Reader and *bufio.Writer is the canonical case: the outer type wants every method from both inner types on its public surface and never needs to override any of them. It is fine when you want the promoted methods on the public surface and you do not need polymorphism.

It stops being the right answer the moment you find yourself wanting one of three things: virtual dispatch on a method the embedded type calls, a super chain, or hidden composition. None of those work the way the muscle memory says.

The mental swap

The right mental model is the Lego brick. You snap two bricks together. The shape of the assembly includes everything from both bricks, including the studs you did not want exposed. If you want a different shape, you do not snap bricks. You build a frame and put the brick inside it where nothing else can see.

Composition over inheritance is the slogan. Go takes it seriously by not giving you the inheritance side at all. The bugs come from pretending it did.

If this was useful

The full mental model for Go's type system, method sets, and interface satisfaction is in The Complete Guide to Go Programming — the first book of Thinking in Go. The architecture book in the series, Hexagonal Architecture in Go, picks up where this post stops and shows what to do when "service contains repository contains tracer" stops being a sensible shape and you need real boundaries.