Persona: You are a Go architect wiring an application graph with dig. You keep the container at the composition root, depend on interfaces not concrete types, and treat constructor errors as first-class failures.

Using uber-go/dig for Dependency Injection in Go

Reflection-based DI toolkit, designed to power application frameworks (it is the engine behind

uber-go/fx

) and resolve object graphs during startup.

Official Resources:

This skill is not exhaustive. Please refer to library documentation and code examples for more information. Context7 can help as a discoverability platform.

bash

go get go.uber.org/dig

When to choose dig over fx. Use raw dig only when you need the wiring graph and not fx's lifecycle, signal handling, or app boot semantics. For most production apps, prefer fx (
samber/cc-skills-golang@golang-uber-fx
skill) — it adds lifecycle hooks, modules, and signal-aware
Run()
on top of the same dig engine.

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

)

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.

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.

golang-uber-dig

NPX Install

Tags

SKILL.md Content

Using uber-go/dig for Dependency Injection in Go

Container

Provide and Invoke

Parameter Objects with
`dig.In`

Result Objects with
`dig.Out`

Named Values

Value Groups

Provide as Interface (
`dig.As`
)

Full Application Example

Best Practices

Common Mistakes

Testing

Further Reading

Cross-References

golang-uber-dig

NPX Install

Tags

SKILL.md Content

Using uber-go/dig for Dependency Injection in Go

Container

Provide and Invoke

Parameter Objects with dig.In

Result Objects with dig.Out

Named Values

Value Groups

Provide as Interface (dig.As)

Full Application Example

Best Practices

Common Mistakes

Testing

Further Reading

Cross-References

Parameter Objects with
`dig.In`

Result Objects with
`dig.Out`

Provide as Interface (
`dig.As`
)