Golang Dependency Injection

Persona: You are a Go software architect. You guide teams toward testable, loosely coupled designs — you choose the simplest DI approach that solves the problem, and you never over-engineer.

Modes:

• Design mode (new project, new service, or adding a service to an existing DI setup): assess the existing dependency graph and lifecycle needs; recommend manual injection or a library from the decision table; then generate the wiring code.
• Refactor mode (existing coupled code): use up to 3 parallel sub-agents — Agent 1 identifies global variables and init() service setup, Agent 2 maps concrete type dependencies that should become interfaces, Agent 3 locates service-locator anti-patterns (container passed as argument) — then consolidate findings and propose a migration plan.

Community default. A company skill that explicitly supersedes samber/cc-skills-golang@golang-dependency-injection skill takes precedence.

Dependency Injection in Go

Dependency injection (DI) means passing dependencies to a component rather than having it create or find them. In Go, this is how you build testable, loosely coupled applications — your services declare what they need, and the caller (or container) provides it.

This skill is not exhaustive. When using a DI library (google/wire, uber-go/dig, uber-go/fx, samber/do), refer to the library's official documentation and code examples for current API signatures.

For interface-based design foundations (accept interfaces, return structs), see the samber/cc-skills-golang@golang-structs-interfaces skill.

Best Practices Summary

1. Dependencies MUST be injected via constructors — NEVER use global variables or init() for service setup 2. Small projects (< 10 services) SHOULD use manual constructor injection — no library needed 3. Interfaces MUST be defined where consumed, not where implemented — accept interfaces, return structs 4. NEVER use global registries or package-level service locators 5. The DI container MUST only exist at the composition root (main() or app startup) — NEVER pass the container as a dependency 6. Prefer lazy initialization — only create services when first requested 7. Use singletons for stateful services (DB connections, caches) and transients for stateless ones 8. Mock at the interface boundary — DI makes this trivial 9. Keep the dependency graph shallow — deep chains signal design problems 10. Choose the right DI library for your project size and team — see the decision table below

Why Dependency Injection?

DI shines in applications with many interconnected services — HTTP servers, microservices, CLI tools with plugins. For a small script with 2-3 functions, manual wiring is fine. Don't over-engineer.

Manual Constructor Injection (No Library)

For small projects, pass dependencies through constructors. See Manual DI examples for a complete application example.

// ✓ Good — explicit dependencies, testable
type UserService struct {
    db     UserStore
    mailer Mailer
    logger *slog.Logger
}

func NewUserService(db UserStore, mailer Mailer, logger *slog.Logger) *UserService {
    return &UserService{db: db, mailer: mailer, logger: logger}
}

// main.go — manual wiring
func main() {
    logger := slog.Default()
    db := postgres.NewUserStore(connStr)
    mailer := smtp.NewMailer(smtpAddr)
    userSvc := NewUserService(db, mailer, logger)
    orderSvc := NewOrderService(db, logger)
    api := NewAPI(userSvc, orderSvc, logger)
    api.ListenAndServe(":8080")
}

// ✗ Bad — hardcoded dependencies, untestable
type UserService struct {
    db *sql.DB
}

func NewUserService() *UserService {
    db, _ := sql.Open("postgres", os.Getenv("DATABASE_URL")) // hidden dependency
    return &UserService{db: db}
}

Manual DI breaks down when:

• You have 15+ services with cross-dependencies
• You need lifecycle management (health checks, graceful shutdown)
• You want lazy initialization or scoped containers
• Wiring order becomes fragile and hard to maintain

DI Library Comparison

Go has three main approaches to DI libraries:

• google/wire examples — Compile-time code generation
• uber-go/dig + fx examples — Reflection-based framework
• samber/do examples — Generics-based, no code generation

Decision Table

Quick Comparison: Same App, Four Ways

The dependency graph: Config -> Database -> UserStore -> UserService -> API

Manual:

cfg := NewConfig()
db := NewDatabase(cfg)
store := NewUserStore(db)
svc := NewUserService(store)
api := NewAPI(svc)
api.Run()
// No automatic shutdown, health checks, or lazy loading

google/wire:

// wire.go — then run: wire ./...
func InitializeAPI() (*API, error) {
    wire.Build(NewConfig, NewDatabase, NewUserStore, NewUserService, NewAPI)
    return nil, nil
}
// No lifecycle hooks (OnStart/OnStop) or health checks; cleanup via returned func() from providers

uber-go/fx:

app := fx.New(
    fx.Provide(NewConfig, NewDatabase, NewUserStore, NewUserService),
    fx.Invoke(func(api *API) { api.Run() }),
)
app.Run() // manages lifecycle, but reflection-based

samber/do:

i := do.New()
do.Provide(i, NewConfig)
do.Provide(i, NewDatabase)    // auto shutdown + health check
do.Provide(i, NewUserStore)
do.Provide(i, NewUserService)
api := do.MustInvoke[*API](i)
api.Run()
// defer i.Shutdown() — handles all cleanup automatically

Testing with DI

DI makes testing straightforward — inject mocks instead of real implementations:

// Define a mock
type MockUserStore struct {
    users map[string]*User
}

func (m *MockUserStore) FindByID(ctx context.Context, id string) (*User, error) {
    u, ok := m.users[id]
    if !ok {
        return nil, ErrNotFound
    }
    return u, nil
}

// Test with manual injection
func TestUserService_GetUser(t *testing.T) {
    mock := &MockUserStore{
        users: map[string]*User{"1": {ID: "1", Name: "Alice"}},
    }
    svc := NewUserService(mock, nil, slog.Default())

    user, err := svc.GetUser(context.Background(), "1")
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
    if user.Name != "Alice" {
        t.Errorf("got %q, want %q", user.Name, "Alice")
    }
}

Testing with samber/do — Clone and Override

Container cloning creates an isolated copy where you override only the services you need to mock:

func TestUserService_WithDo(t *testing.T) {
    // Create a test injector with mock implementation
    testInjector := do.New()

    // Provide the mock UserStore interface
    do.OverrideValue[UserStore](testInjector, &MockUserStore{
        users: map[string]*User{"1": {ID: "1", Name: "Alice"}},
    })

    // Provide other real services as needed
    do.Provide[*slog.Logger](testInjector, func(i *do.Injector) (*slog.Logger, error) {
        return slog.Default(), nil
    })

    svc := do.MustInvoke[*UserService](testInjector)
    user, err := svc.GetUser(context.Background(), "1")
    // ... assertions
}

This is particularly useful for integration tests where you want most services to be real but need to mock a specific boundary (database, external API, mailer).

When to Adopt a DI Library

Common Mistakes

Cross-References

• → See samber/cc-skills-golang@golang-samber-do skill for detailed samber/do usage patterns
• → See samber/cc-skills-golang@golang-structs-interfaces skill for interface design and composition
• → See samber/cc-skills-golang@golang-testing skill for testing with dependency injection
• → See samber/cc-skills-golang@golang-project-layout skill for DI initialization placement

References

• samber/do/v2 documentation | github.com/samber/do/v2
• google/wire user guide
• uber-go/fx documentation
• uber-go/dig

google/wire — Compile-Time Code Generation

Wire uses code generation to resolve the dependency graph at compile time. Type-safe, but requires a build step.

• Docs: github.com/google/wire | User Guide

Before writing Wire code, refer to the library's official documentation for up-to-date API signatures and examples.

Provider Definitions

// providers.go
package wire

import "github.com/google/wire"

// ProviderSet groups related providers
var InfraSet = wire.NewSet(
    NewConfig,
    NewDatabase,
    NewCache,
)

var ServiceSet = wire.NewSet(
    NewUserService,
    wire.Bind(new(UserStore), new(*PostgresUserStore)), // bind interface to impl
)

Injector Definition

// wire.go — build constraint ensures this is only used by the wire tool
//go:build wireinject

package main

import "github.com/google/wire"

func InitializeApp() (*App, error) {
    wire.Build(
        InfraSet,
        ServiceSet,
        NewApp,
    )
    return nil, nil // wire replaces this body
}

Generated Code

Run wire ./... to produce wire_gen.go:

// wire_gen.go — DO NOT EDIT (auto-generated by wire)
func InitializeApp() (*App, error) {
    config := NewConfig()
    database, err := NewDatabase(config)
    if err != nil {
        return nil, err
    }
    cache := NewCache(config)
    store := NewPostgresUserStore(database)
    userService := NewUserService(store, cache)
    app := NewApp(userService)
    return app, nil
}

Testing

Wire generates plain constructors, so testing uses manual injection — no container to clone:

func TestUserService(t *testing.T) {
    mock := &MockUserStore{...}
    svc := NewUserService(mock, NewTestCache())
    // ... test
}

Tradeoffs

• Errors caught at compile time (codegen fails if graph is incomplete)
• Requires running wire ./... after every dependency change
• No lazy loading — all dependencies created eagerly
• No built-in lifecycle management (health checks, shutdown)
• No runtime container — wire generates plain Go constructor calls
• Interface bindings require explicit wire.Bind declarations
• Generated files (wire_gen.go) must be committed and kept in sync

Wire injectors MUST use //go:build wireinject build constraint. Generated wire_gen.go MUST NOT be edited manually — always regenerate with wire ./....

Manual Constructor Injection

Manual DI is the simplest approach — pass dependencies through constructors. No library, no magic.

Complete Application Example

func main() {
    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
    defer stop()

    // Layer 1: Configuration
    cfg := LoadConfig()
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

    // Layer 2: Infrastructure
    db, err := postgres.Connect(cfg.DatabaseURL)
    if err != nil {
        logger.Error("database connection failed", "error", err)
        os.Exit(1)
    }
    defer db.Close()

    cache := redis.NewClient(cfg.RedisURL)
    defer cache.Close()

    mailer := smtp.NewMailer(cfg.SMTPAddr)

    // Layer 3: Repositories
    userRepo := postgres.NewUserRepository(db)
    orderRepo := postgres.NewOrderRepository(db)

    // Layer 4: Services
    userSvc := service.NewUserService(userRepo, cache, mailer, logger)
    orderSvc := service.NewOrderService(orderRepo, userSvc, logger)
    paymentSvc := service.NewPaymentService(orderRepo, cfg.StripeKey, logger)

    // Layer 5: Transport
    handler := http.NewHandler(userSvc, orderSvc, paymentSvc, logger)
    server := http.NewServer(cfg.Port, handler)

    // Run
    go server.ListenAndServe()
    <-ctx.Done()
    server.Shutdown(context.Background())
}

When Manual DI Works Well

• Small to medium projects (< 15 services)
• Simple dependency graph with clear layering
• No need for lazy loading or lifecycle management
• Team prefers explicit, visible wiring

When Manual DI Breaks Down

• Adding a new service means editing main() and getting the wiring order right
• Lifecycle management (health checks, graceful shutdown) must be hand-coded with defer
• No lazy initialization — all services are created at startup, even if unused
• Cross-cutting concerns (logging, tracing) must be threaded through every constructor
• With 30+ services, the wiring code becomes fragile and hard to maintain

Manual DI SHOULD be the default for small projects (< 15 services). Dependencies MUST be initialized in order — infrastructure first, then repositories, then services, then transport.

samber/do — Generics-Based DI

For the full samber/do API, patterns, and advanced features, see the `samber/cc-skills-golang@golang-samber-do` skill.

Type-safe dependency injection using Go generics. No reflection, no code generation, simple API.

• Docs: do.samber.dev | github.com/samber/do/v2

Core Pattern

// Register services with providers
injector := do.New()
do.Provide(injector, func(i do.Injector) (*UserService, error) {
    db := do.MustInvoke[*Database](i)
    return NewUserService(db), nil
})

// Invoke services (lazy — created on demand)
svc := do.MustInvoke[*UserService](injector)

// Graceful shutdown — all services implementing Shutdowner are closed
injector.ShutdownOnSignalsWithContext(ctx, os.Interrupt)

Why samber/do

• No code generation — no build step, no generated files to maintain
• No reflection — errors are caught at compile time via generics, not at runtime
• Strongly typed — Go generics provide full type safety without interface{} casts
• Built-in lifecycle — health checks and graceful shutdown detected automatically
• Container cloning — create isolated test containers from production configuration
• Simple API — Provide, Invoke, Shutdown — that's most of what you need
• Package system — organize services by domain without manual wiring order

→ See samber/cc-skills-golang@golang-samber-do for full application setup, package organization, lifecycle management, debugging, testing with clone + override, and complete API reference.

uber-go/dig + uber-go/fx — Reflection-Based DI

dig is the low-level DI container; fx is the full application framework built on top. Powerful but uses reflection — errors appear at startup, not compile time.

• Docs: github.com/uber-go/dig | uber-go.github.io/fx

Before writing dig/fx code, refer to the library's official documentation for up-to-date API signatures and examples.

dig — Basic Container

func main() {
    container := dig.New()

    container.Provide(NewConfig)
    container.Provide(NewDatabase)
    container.Provide(NewUserStore)
    container.Provide(NewUserService)

    // Invoke — dig resolves the full dependency chain
    err := container.Invoke(func(svc *UserService) {
        svc.Run()
    })
    if err != nil {
        log.Fatal(err)
    }
}

Named Dependencies

type DatabaseParams struct {
    dig.In

    Primary *sql.DB `name:"primary"`
    Replica *sql.DB `name:"replica"`
}

container.Provide(NewPrimaryDB, dig.Name("primary"))
container.Provide(NewReplicaDB, dig.Name("replica"))

container.Provide(func(p DatabaseParams) *UserService {
    return &UserService{
        writer: p.Primary,
        reader: p.Replica,
    }
})

dig Tradeoffs

• Uses reflection — type mismatches are runtime errors, not compile errors
• dig.In and dig.Out structs add boilerplate for complex graphs
• No built-in lifecycle management
• Powerful grouping with dig.Group for collecting multiple implementations

fx — Full Application Framework

Basic Application

func main() {
    app := fx.New(
        fx.Provide(
            NewConfig,
            NewDatabase,
            NewUserStore,
            NewUserService,
        ),
        fx.Invoke(RegisterRoutes),
        fx.Invoke(StartServer),
    )

    app.Run() // blocks until signal, then calls shutdown hooks
}

Lifecycle Hooks

func NewDatabase(lc fx.Lifecycle, cfg *Config) (*Database, error) {
    db := &Database{}

    lc.Append(fx.Hook{
        OnStart: func(ctx context.Context) error {
            return db.Connect(cfg.URL)
        },
        OnStop: func(ctx context.Context) error {
            return db.Close()
        },
    })

    return db, nil
}

Modules

var InfraModule = fx.Module("infra",
    fx.Provide(NewConfig),
    fx.Provide(NewDatabase),
    fx.Provide(NewCache),
)

var ServiceModule = fx.Module("service",
    fx.Provide(NewUserService),
    fx.Provide(NewOrderService),
)

app := fx.New(InfraModule, ServiceModule, fx.Invoke(StartServer))

Testing with fx

func TestUserService(t *testing.T) {
    var svc *UserService

    app := fxtest.New(t,
        fx.Provide(NewMockUserStore),
        fx.Provide(NewUserService),
        fx.Populate(&svc),
    )
    app.RequireStart()
    defer app.RequireStop()

    // ... test svc
}

fx Tradeoffs

• Full application framework — manages startup, shutdown, and signal handling
• Reflection-based — errors at startup, not compile time
• Steep learning curve — fx.In, fx.Out, fx.Annotate, fx.Decorate
• Built-in lifecycle (OnStart/OnStop hooks)
• Heavyweight — pulls in the full fx framework
• fxtest package for testing, but requires starting/stopping the app

fx lifecycle hooks MUST be used for start/stop — register OnStart/OnStop via fx.Lifecycle. fx modules SHOULD group related providers — use fx.Module to organize by domain.