Go Samber Do

samber/do — Dependency Injection Container

Upstream: https://github.com/samber/do · v2: https://github.com/samber/do/tree/v2

When to Reach for DI

Manual NewX(deps...) wiring scales to ~10 services. Past that, the wiring file becomes the second-largest file in the project. samber/do adds: lazy construction, reverse-order shutdown, and Override for testing.

If none of those apply, stay with manual wiring.

Core API (v1)

import "github.com/samber/do"

injector := do.New()

do.Provide(injector, func(i *do.Injector) (*pgxpool.Pool, error) {
    return pgxpool.New(context.Background(), os.Getenv("DATABASE_URL"))
})

do.Provide(injector, func(i *do.Injector) (*UserRepository, error) {
    pool := do.MustInvoke[*pgxpool.Pool](i)
    return NewUserRepository(pool), nil
})

repo, err := do.Invoke[*UserRepository](injector) // (T, error)
svc := do.MustInvoke[*UserService](injector)      // panics; main/init only

defer injector.Shutdown()

Providers are indexed by concrete type. Two providers for the same type is an error.

Named Providers

For multiple instances of the same type (primary vs replica pool):

do.ProvideNamed(injector, "primary", func(i *do.Injector) (*pgxpool.Pool, error) { ... })
do.ProvideNamed(injector, "replica", func(i *do.Injector) (*pgxpool.Pool, error) { ... })

primary := do.MustInvokeNamed[*pgxpool.Pool](injector, "primary")

Use do.ProvideNamedValue(injector, "name", value) for pre-built values.

Scoped Injectors (v2)

Child injectors inherit providers, can override them. Use for request-scoped services or multi-tenant:

root := do.New()
do.Provide(root, newLogger)

reqScope := root.Scope("request-42")
do.ProvideValue(reqScope, &TraceID{ID: "abc123"})

trace := do.MustInvoke[*TraceID](reqScope)  // scope-local
log := do.MustInvoke[*Logger](reqScope)     // inherited
reqScope.Shutdown()                         // root untouched

Don't create a scope per request if there are no scope-local providers — pure overhead.

Shutdown Contract

Services implement Shutdown() error or Shutdown(context.Context) error. injector.Shutdown() calls them in reverse construction order. For signal handling: injector.ShutdownOnSignals(syscall.SIGINT, syscall.SIGTERM).

Construction order is the tiebreaker — if A built before B but A's shutdown needs B alive, provide B first.

Testing with Overrides

injector := do.New()
do.ProvideValue[*UserRepository](injector, &mockRepo{})
do.Provide(injector, NewUserService)
svc := do.MustInvoke[*UserService](injector)

// Mid-flight
do.OverrideValue[*UserRepository](injector, &mockRepo{})
do.OverrideNamedValue[*pgxpool.Pool](injector, "primary", fakePool)

Override replaces providers. Already-held pointers do NOT change — re-Invoke after Override.

Health Checks

type HealthChecker interface { HealthCheck() error }
// Anything implementing it is checked:
if err := injector.HealthCheck(); err != nil { /* /readyz 503 */ }

Migration Example

Before (6 services, manual):

pool, _ := pgxpool.New(ctx, dsn)
defer pool.Close()
redis, _ := newRedis(url)
defer redis.Close()
repo := NewUserRepository(pool)
cache := NewUserCache(redis)
svc := NewUserService(repo, cache)
handler := NewHandler(svc)

After:

injector := do.New()
do.Provide(injector, newPool)
do.Provide(injector, newRedis)
do.Provide(injector, NewUserRepository)
do.Provide(injector, NewUserCache)
do.Provide(injector, NewUserService)
do.Provide(injector, NewHandler)
handler := do.MustInvoke[*Handler](injector)
defer injector.Shutdown()

Only worth it if (a) more services coming, (b) tests swap deps, (c) shutdown ordering is fragile.

Common Pitfalls

Review Checklist

Flag:

• CRITICAL — do.MustInvoke inside request handler or hot path
• CRITICAL — Shutdown() missing from a service owning OS resources
• WARNING — Multiple same-type providers without ProvideNamed
• WARNING — Injector passed down into business logic
• WARNING — No boot-time Invoke smoke test
• SUGGESTION — 3-5 services using do where manual wiring is clearer
• SUGGESTION — Scopes created per-request with no scope-local providers

Alternatives

google/wire — compile-time DI, zero runtime reflection, but codegen step in the build. Pick wire when you want no runtime cost; pick do when you want lifecycle + test ergonomics.