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.
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 |
| 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 for a complete application example.
type UserService struct {
db UserStore
mailer Mailer
logger *slog.Logger
}
func NewUserService(db UserStore, mailer Mailer, logger *slog.Logger) *UserService {
return &UserService{db: db, mailer: mailer, logger: logger}
}
func main() {
logger := slog.Default()
db := postgres.NewUserStore(connStr)
mailer := smtp.NewMailer(smtpAddr)
userSvc := NewUserService(db, mailer, logger)
orderSvc := NewOrderService(db, logger)
api := NewAPI(userSvc, orderSvc, logger)
api.ListenAndServe(":8080")
}
type UserService struct {
db *sql.DB
}
func NewUserService() *UserService {
db, _ := sql.Open("postgres", os.Getenv("DATABASE_URL"))
return &UserService{db: db}
}
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:
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: Same App, Four Ways
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()
google/wire:
func InitializeAPI() (*API, error) {
wire.Build(NewConfig, NewDatabase, NewUserStore, NewUserService, NewAPI)
return nil, nil
}
uber-go/fx:
app := fx.New(
fx.Provide(NewConfig, NewDatabase, NewUserStore, NewUserService),
fx.Invoke(func(api *API) { api.Run() }),
)
app.Run()
samber/do:
i := do.New()
do.Provide(i, NewConfig)
do.Provide(i, NewDatabase)
do.Provide(i, NewUserStore)
do.Provide(i, NewUserService)
api := do.MustInvoke[*API](i)
api.Run()
Testing with DI
DI makes testing straightforward — inject mocks instead of real implementations:
type MockUserStore struct {
users map[string]*User
}
func (m *MockUserStore) FindByID(ctx context.Context, id string) (*User, error) {
u, ok := m.users[id]
if !ok {
return nil, ErrNotFound
}
return u, nil
}
func TestUserService_GetUser(t *testing.T) {
mock := &MockUserStore{
users: map[string]*User{"1": {ID: "1", Name:
