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 service architecture, setting up dependency injection, refactoring tightly coupled code, managing singletons or service factories, or when the user asks about inversion of control, service containers, or wiring dependencies in Go. For a specific DI library, → See `samber/cc-skills-golang@golang-google-wire`, `samber/cc-skills-golang@golang-uber-dig`, `samber/cc-skills-golang@golang-uber-fx`, or `samber/cc-skills-golang@golang-samber-do` skills.
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 service architecture, setting up dependency injection, refactoring tightly coupled code, managing singletons or service factories, or when the user asks about inversion of control, service containers, or wiring dependencies in Go. For a specific DI library, → See `samber/cc-skills-golang@golang-google-wire`, `samber/cc-skills-golang@golang-uber-dig`, `samber/cc-skills-golang@golang-uber-fx`, or `samber/cc-skills-golang@golang-samber-do` skills.
user-invocable
true
license
MIT
compatibility
Designed for Claude Code or similar AI coding agents, and for projects using Golang.
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: Use ultracode when refactoring a large coupled codebase toward dependency injection — orchestrate the three sub-agents described in Refactor mode (global/init discovery, concrete-dependency mapping, service-locator detection) and consolidate into one migration plan.
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
Dependencies MUST be injected via constructors — NEVER use global variables or init() for service setup
Small projects (< 10 services) SHOULD use manual constructor injection — no library needed
Interfaces MUST be defined where consumed, not where implemented — accept interfaces, return structs
NEVER use global registries or package-level service locators
The DI container MUST only exist at the composition root (main() or app startup) — NEVER pass the container as a dependency
Prefer lazy initialization — only create services when first requested
Use singletons for stateful services (DB connections, caches) and transients for stateless ones
Mock at the interface boundary — DI makes this trivial
Keep the dependency graph shallow — deep chains signal design problems
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
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 for a complete application example.
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 ./...funcInitializeAPI() (*API, error) {
wire.Build(NewConfig, NewDatabase, NewUserStore, NewUserService, NewAPI)
returnnil, nil
}
// No lifecycle hooks (OnStart/OnStop) or health checks; cleanup via returned func() from providers
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 mocktype MockUserStore struct {
users map[string]*User
}
func(m *MockUserStore) FindByID(ctx context.Context, id string) (*User, error) {
u, ok := m.users[id]
if !ok {
returnnil, ErrNotFound
}
return u, nil
}
// Test with manual injectionfuncTestUserService_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:
funcTestUserService_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
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
