golang-uber-dig

$27

fx is built on dig and shares the same container engine — the DI primitives (Provide, Invoke, In/Out structs, named values, value groups) are identical. fx.In/fx.Out are re-exports of dig.In/dig.Out.

What fx adds on top of dig:

Concern

dig

fx

DI container

✅ dig.New()

✅ (embedded)

Lifecycle hooks

❌

✅ fx.Lifecycle OnStart/OnStop

Module system

❌

✅ fx.Module with scoped decorators

Signal-aware run loop

❌

✅ app.Run() blocks on SIGINT/SIGTERM

Structured event logging

❌

✅ fx.WithLogger / fxevent

Startup/shutdown timeout

❌

✅ fx.StartTimeout / fx.StopTimeout

Choose dig when you need the wiring graph only: CLI tools, libraries exposing a container to callers, test harnesses, or embedding DI into an existing app that manages its own lifecycle.

Choose fx for long-running services (HTTP servers, workers, daemons) — lifecycle and signal handling are non-negotiable there. See samber/cc-skills-golang@golang-uber-fx skill.

Container

import "go.uber.org/dig"

c := dig.New()

Useful options: dig.DeferAcyclicVerification() (faster startup), dig.RecoverFromPanics() (turn panics into dig.PanicError), dig.DryRun(true) (validate without invoking).

Provide and Invoke

// Register a constructor — lazy, only runs when its output is needed

err := c.Provide(func(cfg *Config) (*sql.DB, error) {

    return sql.Open("postgres", cfg.DSN)

})

// Pull a service out of the container by asking for it as a function parameter

err = c.Invoke(func(db *sql.DB) error {

    return db.Ping()

})

Constructors are lazy and memoized: each output type is built once and shared (singleton per container). Provide errors at registration if the constructor is malformed; Invoke returns the constructor's error wrapped with the dependency path that triggered it.

A dig constructor is any function. Inputs are dependencies, outputs are provided types. error (last return) signals construction failure. Follow "accept interfaces, return structs".

Parameter Objects with dig.In

Once a constructor has 4+ dependencies, embed dig.In to group them as struct fields and tag fields:

type HandlerParams struct {

    dig.In

    Logger *zap.Logger

    DB     *sql.DB

    Cache  *redis.Client `optional:"true"`           // zero value if not provided

    DBRO   *sql.DB       `name:"readonly"`           // named dependency

    Routes []http.Handler `group:"routes"`           // value group

}

func NewHandler(p HandlerParams) *Handler { /* ... */ }

Tags: name:"...", optional:"true", group:"...".

Result Objects with dig.Out

Return several values from one constructor and attach name/group tags to results:

type ConnResult struct {

    dig.Out

    ReadWrite *sql.DB `name:"primary"`

    ReadOnly  *sql.DB `name:"readonly"`

}

func NewConnections(cfg *Config) (ConnResult, error) { /* ... */ }

Named Values

Two providers of the same type collide. Disambiguate with dig.Name:

c.Provide(NewPrimaryDB,  dig.Name("primary"))

c.Provide(NewReadOnlyDB, dig.Name("readonly"))

Consume by adding name:"primary" / name:"readonly" to a dig.In field.

Value Groups

Many providers, one consumer slice — typical for HTTP handlers, health checks, migrations:

type RouteResult struct {

    dig.Out

    Handler http.Handler `group:"routes"`

}

func NewUserHandler(db *sql.DB) RouteResult { /* ... */ }

func NewPostHandler(db *sql.DB) RouteResult { /* ... */ }

type ServerParams struct {

    dig.In

    Routes []http.Handler `group:"routes"`

}

Flatten — append ,flatten (e.g. group:"routes,flatten") to unwrap a slice instead of nesting it. Group order is not guaranteed; if order matters, provide an explicit ordered slice from a single constructor.

Provide as Interface ( dig.As )

Register a concrete constructor and expose it under one or more interfaces without a separate adapter:

c.Provide(NewPostgresDB, dig.As(new(Database), new(io.Closer)))

// Consumers ask for Database or io.Closer; *PostgresDB stays hidden.

Full Application Example

func main() {

    c := dig.New()

    must(c.Provide(NewConfig))

    must(c.Provide(NewLogger))

    must(c.Provide(NewDatabase))

    must(c.Provide(NewServer))

    err := c.Invoke(func(srv *http.Server) error {

        return srv.ListenAndServe()

    })

    if err != nil {

        log.Fatal(err)

    }

}

func must(err error) { if err != nil { panic(err) } }

dig has no built-in lifecycle. If you need OnStart/OnStop hooks, signal handling, and graceful shutdown, use fx — see samber/cc-skills-golang@golang-uber-fx skill.

For Decorate, Scopes, optional deps, error helpers, and Visualize, see advanced.md.

Best Practices

• Keep the container at the composition root — never pass *dig.Container as a parameter; treat it like a plumbing detail of main(). Service-locator patterns defeat the testability gains of DI.

• Depend on interfaces, not concrete types — lets you swap implementations in tests without touching production code, and lets you use dig.As to expose narrow interfaces from wide structs.

• Prefer parameter objects (dig.In structs) once a constructor has 4+ dependencies — call sites stay readable and adding a new dependency is a one-line change instead of a signature break.

• Group registration by module (one file per module that calls c.Provide for its types) — review and refactoring become a per-module concern, and you can extract a module into a fx.Module later without rewriting wiring.

• Validate the graph eagerly in tests — call c.Invoke against the composition root in CI to surface missing providers at boot time, not at first request. DryRun(true) skips constructor execution.

• Return errors from constructors instead of panicking — dig wraps them with the dependency path, which makes the failure point obvious.

Common Mistakes

Mistake

Fix

Passing the container into services

The container belongs to main(). Inject the typed dependencies a service needs; otherwise tests need to build a real container.

Two providers for the same type without Name

dig errors at Provide time. Either name them, or merge into a single provider that returns a dig.Out result struct.

Ignoring Provide errors

Wrap each Provide with a must helper. A silent registration error becomes a missing-type error far later.

Using groups when ordering matters

Groups are unordered. If order matters (middleware chain, migration sequence), provide an explicit ordered slice with one constructor.

Constructors with side effects on import

Keep init() empty — start work only inside the constructor, after the graph is built.

Testing

dig containers are cheap — build a fresh one per test, override providers with Decorate, and call Invoke to drive the system. For full patterns (per-test wiring, shared helpers, graph validation in CI, asserting wire-time errors, recovering from constructor panics), see testing.md.

Further Reading

• advanced.md — Decorate, Scopes, optional deps, error helpers, Visualize, full Quick Reference

• recipes.md — end-to-end examples: HTTP server with route group, two databases, request scopes, decorators, dry-run validation

• testing.md — testing patterns and graph validation

Cross-References

• → See samber/cc-skills-golang@golang-uber-fx skill for application lifecycle, modules, and signal-aware Run() built on top of dig

• → See samber/cc-skills-golang@golang-dependency-injection skill for DI concepts and library comparison

• → See samber/cc-skills-golang@golang-samber-do skill for a generics-based alternative without reflection

• → See samber/cc-skills-golang@golang-google-wire skill for compile-time DI (no runtime container)

• → See samber/cc-skills-golang@golang-structs-interfaces skill for interface design patterns

• → See samber/cc-skills-golang@golang-testing skill for general testing patterns

If you encounter a bug or unexpected behavior in uber-go/dig, open an issue at https://github.com/uber-go/dig/issues.