Comprehensive guide for dependency injection (DI) in Golang. Covers why DI matters (testability, loose coupling, separation of concerns, lifecycle management), manual constructor injection, and DI library comparison (google/wire, uber-go/dig, uber-go/fx, samber/do). Use this skill when designing ser

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. Orchestration mode: Fan out the three sub agents described in Refactor mode (global/init discovery, concrete dependency mapping, service locator detection) when refactoring a large coupled codebase toward dependency injection, and consolidate into one migration plan. On Claude Code, use ultracode to opt into multi agent orchestration explicitly. 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? Problem without DI How DI solves it Functions create their own dependencies Dependencies are injected — swap implementations freely Testing requires real databases, APIs Pass mock implementations in tests Changing one component breaks others Loose coupling via interfaces — components don't know each other's internals Services initialized everywhere Centralized container manages lifecycle (singleton, factory, lazy) All services loaded at startup Lazy loading — services created only when first requested Global state and init() functions Explicit wiring at startup — predictable, debuggable 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](./references/manual di.md) for a complete application example. 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](./references/google wire.md) — Compile time code generation [uber go/dig + fx examples](./references/uber dig fx.md) — Reflection based framework [samber/do examples](./references/samber do.md) — Generics based, no code generation Decision Table Criteria Manual google/wire uber go/dig + fx samber/do Project size Small (< 10 services) Medium Large Large Any size Type safety Compile time Compile time (codegen) Runtime (reflection) Compile time (generics) Code generation None Required ( wire gen.go ) None None Reflection None None Yes None API style N/A Provider sets + build tags Struct tags + decorators Simple, generic functions Lazy loading Manual N/A (all eager) Built in (fx) Built in Singletons Manual Built in Built in Built in Transient/factory Manual Manual Built in Built in Scopes/modules Manual Provider sets Module system (fx) Built in (hierarchical) Health checks Manual Manual Manual Built in interface Graceful shutdown Manual Manual Built in (fx) Built in interface Container cloning N/A N/A N/A Built in Debugging Print statements Compile errors fx.Visualize() ExplainInjector() , web interface Go version Any Any Any 1.18+ (generics) Learning curve None Medium High Low Quick Comparison: Wiring Style The same graph — Config Database UserStore UserService API — wired by hand and by a container. The contrast is what the wiring code encodes: an ordered call sequence you maintain, versus a set of providers the container orders for you. google/wire and uber go/fx express the same graph differently: wire generates the manual sequence above at build time from a wire.Build provider list (cleanup via func() returned by providers, no lifecycle hooks), while fx registers providers with fx.Provide and resolves them by reflection at runtime with OnStart / OnStop hooks. Full wiring examples for each: [google/wire](./references/google wire.md), [uber go/dig + fx](./references/uber dig fx.md), [samber/do](./references/samber do.md). Testing with DI DI makes testing straightforward — inject mocks instead of real implementations: Testing with samber/do — Clone and Override Container cloning creates an isolated copy where you override only the services you need to mock: 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 Signal Action < 10 services, simple dependencies Stay with manual constructor injection 10 20 services, some cross cutting concerns Consider a DI library 20+ services, lifecycle management needed Strongly recommended Need health checks, graceful shutdown Use a library with built in lifecycle support Team unfamiliar with DI concepts Start manual, migrate incrementally Common Mistakes Mistake Fix Global variables as dependencies Pass through constructors or DI container init() for service setup Explicit initialization in main() or container Depending on concrete types Accept interfaces at consumption boundaries Passing the container everywhere (service locator) Inject specific dependencies, not the container Deep dependency chains (A B C D E) Flatten — most services should depend on repositories and config directly Creating a new container per request One container per application; use scopes for request level isolation 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](https://do.samber.dev) [github.com/samber/do/v2](https://github.com/samber/do) [google/wire user guide](https://github.com/google/wire/blob/main/docs/guide.md) [uber go/fx documentation](https://uber go.github.io/fx/) [uber go/dig](https://github.com/uber go/dig)

golang-dependency-injection