Let me tell you about one of Go’s quietest but most powerful features. For a long time, I wrote Go code without truly understanding embedding. I’d see it in the standard library and think it was some advanced, niche technique. Then, one day, it clicked. It wasn’t about complexity; it was about simplicity. It was about writing less code while making relationships between types clearer.
Think of embedding like putting one box inside another. The outer box gets everything that’s inside the inner box. You don’t have to unpack and repack the items. In Go, this means a struct or interface can include another type’s fields and methods directly.
Here’s the first practical way I use it every day. It’s perfect for building up objects from smaller, reusable parts. Imagine you’re designing a system with different vehicles. You have a basic engine with its own properties and actions.
package main
import "fmt"
// A simple building block
type Engine struct {
Horsepower int
FuelType string
}
// This method belongs to Engine
func (e Engine) Describe() string {
return fmt.Sprintf("%d HP %s engine", e.Horsepower, e.FuelType)
}
// A Car has an Engine. With embedding, it gets the Engine's fields and methods.
type Car struct {
Engine // This is the embedding. Notice there's no field name.
Model string
Doors int
}
func main() {
myCar := Car{
Engine: Engine{Horsepower: 150, FuelType: "petrol"},
Model: "Focus",
Doors: 4,
}
// I can access Horsepower directly on myCar
fmt.Println("Power:", myCar.Horsepower)
// I can call the Engine's method directly on myCar
fmt.Println("Description:", myCar.Describe())
// And of course, I can use Car's own fields
fmt.Println("Model:", myCar.Model)
}
The magic is that Horsepower and Describe() are promoted. They belong to Car now, as if they were defined there. This is composition, not inheritance. The Car isn’t an Engine; it has an engine. This distinction keeps things clean and predictable in Go.
The second major use is for interfaces. This is how you combine small contracts into larger ones. The Go standard library does this constantly. A ReadCloser is just something that can Read and Close. Let me show you how to build your own.
package main
// Simple, focused interfaces
type Reader interface {
Read([]byte) (int, error)
}
type Closer interface {
Close() error
}
// A larger interface composed of smaller ones
type ReadCloser interface {
Reader
Closer
// You can add more methods here if needed
}
// Now, any type that implements both Read and Close automatically satisfies ReadCloser.
// I don't have to write any new code.
type File struct {
name string
}
func (f File) Read(p []byte) (int, error) {
// Simulate reading...
return len(p), nil
}
func (f File) Close() error {
// Simulate closing...
return nil
}
func processStream(rc ReadCloser) error {
data := make([]byte, 100)
_, err := rc.Read(data)
if err != nil {
return err
}
// I know I can also call Close because of the embedded interfaces.
return rc.Close()
}
func main() {
f := File{"data.txt"}
// File satisfies ReadCloser automatically.
processStream(f)
}
This is incredibly powerful for defining requirements. You can state that a function needs something that can do A, B, and C by embedding three small interfaces. The implementing type doesn’t need to know about your combined interface.
Third, embedding saves me countless hours with configuration. In real applications, you often have a base set of settings common to many services, like timeouts or logging levels.
package main
import "time"
// Common settings for everything in my system
type CommonConfig struct {
Timeout time.Duration
Environment string // "dev", "staging", "prod"
LogLevel string // "debug", "info", "error"
}
// A database-specific config INHERITS the common settings
type DatabaseConfig struct {
CommonConfig // Embed the common fields
Host string
Port int
Username string
Password string
DatabaseName string
}
// An API client config also gets the common settings
type APIConfig struct {
CommonConfig
BaseURL string
APIKey string
RateLimit int // requests per second
}
func initializeDatabase(cfg DatabaseConfig) {
// I can access both CommonConfig and DatabaseConfig fields directly
fmt.Printf("Connecting to %s:%d with timeout %v\n",
cfg.Host, cfg.Port, cfg.Timeout) // Timeout is from CommonConfig
}
func main() {
dbCfg := DatabaseConfig{
CommonConfig: CommonConfig{
Timeout: 30 * time.Second,
Environment: "prod",
LogLevel: "info",
},
Host: "localhost",
Port: 5432,
DatabaseName: "mydb",
}
apiCfg := APIConfig{
CommonConfig: CommonConfig{
Timeout: 5 * time.Second,
Environment: "prod",
},
BaseURL: "https://api.example.com",
RateLimit: 100,
}
initializeDatabase(dbCfg)
// Both configs share the common setup, ensuring consistency.
}
This pattern ensures every service in my system handles timeouts or environment names the same way. If I need to add a new common field, like EnableTracing, I add it in one place.
Fourth, embedding is my go-to tool for middleware and decorators. When you want to wrap an object to add behavior—like counting, logging, or timing—embedding makes it trivial.
package main
import (
"fmt"
"io"
"strings"
)
// A simple reader that just returns its string
type StringReader struct {
content string
pos int
}
func (sr *StringReader) Read(p []byte) (n int, err error) {
if sr.pos >= len(sr.content) {
return 0, io.EOF
}
n = copy(p, sr.content[sr.pos:])
sr.pos += n
return n, nil
}
// A counting reader WRAPS another reader.
// It embeds an io.Reader, so it satisfies the interface.
type CountingReader struct {
io.Reader // Embed the interface we're decorating
BytesRead int
}
// Override the Read method to add counting behavior.
func (cr *CountingReader) Read(p []byte) (int, error) {
n, err := cr.Reader.Read(p) // Delegate to the embedded reader
cr.BytesRead += n // Add our custom logic
return n, err
}
func main() {
original := &StringReader{content: "Hello, World!"}
counter := &CountingReader{Reader: original}
buf := make([]byte, 5)
for {
n, err := counter.Read(buf)
fmt.Printf("Read %d bytes: %s\n", n, buf[:n])
if err == io.EOF {
break
}
}
fmt.Printf("Total bytes read: %d\n", counter.BytesRead)
}
The beauty here is that CountingReader is still an io.Reader. It can be used anywhere an io.Reader is expected. The embedding means I don’t have to manually implement every method of the interface just to wrap one of them. I only override what I need to change.
Fifth, I use struct embedding to create fluent, builder-like APIs for complex objects. This is common when you have objects with sensible defaults but many possible configurations.
package main
import "fmt"
// Default settings for a server
type Defaults struct {
Port int
Host string
Timeout int
}
func (d Defaults) WithPort(port int) Defaults {
d.Port = port
return d
}
func (d Defaults) WithHost(host string) Defaults {
d.Host = host
return d
}
// The main server config embeds the defaults
type ServerConfig struct {
Defaults
MaxConnections int
TLSEnabled bool
}
func main() {
// Start with sensible defaults
defaults := Defaults{Port: 8080, Host: "0.0.0.0", Timeout: 30}
// Build the final config using the fluent methods
config := ServerConfig{
Defaults: defaults.WithPort(9000).WithHost("localhost"),
MaxConnections: 100,
TLSEnabled: true,
}
// Access is seamless
fmt.Printf("Server on %s:%d\n", config.Host, config.Port)
fmt.Printf("Timeout: %d, TLS: %v\n", config.Timeout, config.TLSEnabled)
}
This pattern provides a clean way to layer configuration. The methods on Defaults return a modified copy, allowing for chaining, and the ServerConfig gets all those fields directly.
Sixth, and this is more advanced, embedding helps me manage permissions and roles in a system. You can model different user types by embedding a base user and adding specific capabilities.
package main
import "fmt"
// What every user in the system has
type BaseUser struct {
ID int
Username string
Email string
}
func (u BaseUser) ProfileURL() string {
return fmt.Sprintf("/users/%s", u.Username)
}
// A regular customer
type Customer struct {
BaseUser
ShippingAddress string
LoyaltyPoints int
}
// An admin has user properties plus extra powers
type Admin struct {
BaseUser
Permissions []string
Department string
}
func (a Admin) CanManageUsers() bool {
// Check permissions...
return true
}
func sendWelcomeEmail(u BaseUser) {
fmt.Printf("Sending welcome email to %s at %s\n", u.Username, u.Email)
}
func main() {
cust := Customer{
BaseUser: BaseUser{ID: 1, Username: "john_doe", Email: "[email protected]"},
ShippingAddress: "123 Main St",
}
admin := Admin{
BaseUser: BaseUser{ID: 2, Username: "jane_admin", Email: "[email protected]"},
Department: "Engineering",
}
// Both can be used where a BaseUser is expected
sendWelcomeEmail(cust.BaseUser)
sendWelcomeEmail(admin.BaseUser)
fmt.Println("Customer profile:", cust.ProfileURL()) // Method from BaseUser
fmt.Println("Can admin manage users?", admin.CanManageUsers())
}
This approach models real-world relationships accurately. An admin is a user with extra features. Embedding lets me express that without repeating all the common user fields.
Now, let’s talk about some important details and cautions. Embedding is simple, but you need to understand what’s happening.
When you call a method on an embedded field, the method’s receiver is the embedded type, not the outer type. This matters if the method needs to access fields.
type Animal struct {
Name string
}
func (a Animal) Speak() {
fmt.Println("I am", a.Name)
}
type Dog struct {
Animal
Breed string
}
func main() {
d := Dog{Animal: Animal{Name: "Fido"}, Breed: "Terrier"}
d.Speak() // This prints "I am Fido".
// The Speak method sees only Animal's fields. It cannot access d.Breed.
}
If you need the method to know about the Dog’s fields, you would have to define a new Speak method on Dog that might call d.Animal.Speak().
You can also have naming conflicts. If two embedded types have a method or field with the same name, you must be explicit.
type Writer struct{}
func (Writer) Write() { fmt.Println("Writing document") }
type Printer struct{}
func (Printer) Write() { fmt.Println("Printing document") }
type OfficeDevice struct {
Writer
Printer
}
func main() {
od := OfficeDevice{}
// od.Write() // This is AMBIGUOUS and won't compile!
od.Writer.Write() // You must specify which one.
od.Printer.Write()
}
The compiler forces you to clarify your intent, which prevents subtle bugs.
Finally, remember that embedding is a tool, not a rule. Sometimes, a plain field is clearer. Ask yourself: is this a true “is composed of” relationship, or am I just trying to save a few lines of code? If the inner type is a core component of the outer type, embedding is often right. If it’s just a utility the outer type uses occasionally, a named field might be better.
// Option A: Embedding (Logger is a core part of Service)
type Service struct {
Logger
// ... other fields
}
// service.Log("msg") // Called directly
// Option B: Named field (Logger is a dependency Service uses)
type Service struct {
logger Logger
// ... other fields
}
// service.logger.Log("msg") // Called explicitly
Both are valid. Choose based on the relationship you want to express.
In my own code, embedding has moved from a curiosity to a fundamental part of how I design. It lets me build programs like stacking blocks, where each piece is simple and clear, but together they form something robust and maintainable. It embodies the Go philosophy: practical, straightforward, and designed to help you write clear code that lasts.
