golang-dependency-injection

Hand a service the things it needs instead of letting it go and find them itself — how to wire a Go app together by hand, and when the graph has grown enough to be worth a library.

WHEN TO USE

SCOPE

USE FOR

Wire a small service by hand with plain constructor injection, no library needed.
Pick the right DI library — google/wire, uber-go/dig or fx, or samber/do — for the project's size.
Refactor a codebase's global variables and init() service setup toward explicit injection.
Mock a dependency at an interface boundary in a unit test instead of hitting a real database.
Decide when a growing dependency graph justifies adopting a container over manual wiring.

NOT FOR

Not for a specific library's detailed API once you've picked one — see that library's own skill.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (10)

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

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.

// ✓ Good — explicit dependencies, testable
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}
}

// main.go — manual wiring
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")
}

// ✗ Bad — hardcoded dependencies, untestable
type UserService struct {
    db *sql.DB
}

func NewUserService() *UserService {
    db, _ := sql.Open("postgres", os.Getenv("DATABASE_URL")) // hidden dependency
    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:

google/wire examples — Compile-time code generation
uber-go/dig + fx examples — Reflection-based framework
samber/do examples — 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.

// Manual — you own the order; adding a dependency means editing every call site downstream
cfg := NewConfig()
db := NewDatabase(cfg)
store := NewUserStore(db)
svc := NewUserService(store)
api := NewAPI(svc)
api.Run()
// No shutdown hooks, health checks, or lazy loading — add them yourself

// Container (samber/do) — order is derived from the constructor signatures
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()
defer i.Shutdown() // shutdown and health checks come from the container

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, uber-go/dig + fx, samber/do.

Testing with DI

DI makes testing straightforward — inject mocks instead of real implementations:

// Define a mock
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
}

// Test with manual injection
func TestUserService_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:

func TestUserService_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

References

This skill ships inside the Samber Golang Skills plugin.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add samber/cc-skills-golang --skill "golang-dependency-injection" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Samber Golang Skills plugin package selected for your AI tool.

Add Samuel's marketplace, then install the plugin

Type both lines inside a Claude Code session, not at your shell prompt. The marketplace is a separate repository of Samuel Berthe's, samber/cc, which also lists his other plugins. The second line opens the details of cc-skills-golang, which carries this repository's 46 Go skills; pick one of the install options shown and Claude Code installs it.

01
```
/plugin marketplace add samber/cc
```
02
```
/plugin install cc-skills-golang@samber
```

Run it in your terminal. It copies the whole repository, with its 46 skills, into ~/.openclaw/skills/cc-skills-golang, OpenClaw's skills folder in your home folder. To install it for one OpenClaw workspace instead, Samuel gives ~/.openclaw/workspace/skills/cc-skills-golang as the folder.

git clone https://github.com/samber/cc-skills-golang.git ~/.openclaw/skills/cc-skills-golang

Run it in your terminal, not inside Gemini CLI; installing from GitHub needs git on your computer. It installs the repository, with its 46 skills, as a Gemini CLI extension. To update it later, run gemini extensions update cc-skills-golang.

gemini extensions install https://github.com/samber/cc-skills-golang

Run it in your terminal. It copies the whole repository, with its 46 skills, into ~/.cursor/skills/cc-skills-golang, Cursor's skills folder in your home folder.

git clone https://github.com/samber/cc-skills-golang.git  ~/.cursor/skills/cc-skills-golang

Type it in an interactive GitHub Copilot CLI session, not at your shell prompt. It installs the repository straight from GitHub as a plugin, with its 46 skills and no marketplace to add first.

/plugin install https://github.com/samber/cc-skills-golang

Run it in your terminal. It copies the whole repository, with its 46 skills, into ~/.agents/skills/cc-skills-golang in your home folder.

git clone https://github.com/samber/cc-skills-golang.git ~/.agents/skills/cc-skills-golang

Open plugin page ↗

What's inside

Files included with this skill.

View on GitHub

Same repository

golang-benchmark
Golang benchmarking, profiling, and performance measurement. Use when writing, running, or comparing Go benchmarks, profiling hot paths with pprof, interpreting CPU/memory/trace profiles, analyzing results with benchstat, setting up CI benchmark regression detection, or investigating production performance with Prometheus runtime metrics. Also use when the developer needs deep analysis on a specific performance indicator - this skill provides the measurement methodology, while samber/cc-skills-golang@golang-performance provides the optimization patterns.Read full description
golang-cli
Golang CLI application development. Use when building, modifying, or reviewing a Go CLI tool — especially for command structure, flag handling, configuration layering, version embedding, exit codes, I/O patterns, signal handling, shell completion, argument validation, and CLI unit testing. Also triggers when code uses cobra, viper, or urfave/cli. For cobra-specific APIs → See samber/cc-skills-golang@golang-spf13-cobra skill; for viper configuration layering → See samber/cc-skills-golang@golang-spf13-viper skill.Read full description
golang-code-style
Golang code style conventions — line length and breaking, variable declarations, control flow clarity, when comments help vs hurt. Use when writing or reviewing Go code, asking about style or clarity, or establishing project coding standards. Not for naming conventions (→ See samber/cc-skills-golang@golang-naming skill), linter configuration (→ See samber/cc-skills-golang@golang-lint skill), or doc comments (→ See samber/cc-skills-golang@golang-documentation skill).Read full description
golang-concurrency
Golang concurrency patterns. Use when writing or reviewing concurrent Go code involving goroutines, channels, select, locks, sync primitives, errgroup, singleflight, worker pools, or fan-out/fan-in pipelines. Also triggers when you detect goroutine leaks, race conditions, channel ownership issues, or need to choose between channels and mutexes.Read full description
golang-context
Idiomatic context.Context usage in Golang — propagation through API boundaries, cancellation, timeouts and deadlines, request-scoped values, context.WithoutCancel for background work outliving requests. Apply when designing context propagation across layers, debugging leaked or unexpired contexts, choosing between context.Background/TODO/WithoutCancel, or storing values in context. Not for code that merely accepts ctx as first parameter.Read full description
golang-continuous-integration
CI/CD pipeline configuration using GitHub Actions for Golang projects — testing, linting, SAST, security scanning, code coverage, Dependabot, Renovate, GoReleaser, code review automation, and release pipelines. Use when setting up or improving Go project CI, configuring GitHub Actions workflows, adding linters or security scanners, automating dependency updates, or adding quality gates.Read full description

Dependency Injection in Go

Best Practices Summary

Why Dependency Injection?

Manual Constructor Injection (No Library)

DI Library Comparison

Decision Table

Quick Comparison: Wiring Style

Testing with DI

Testing with samber/do — Clone and Override

When to Adopt a DI Library

Common Mistakes

Cross-References

References

No requirements beyond installing this skill were found.

Install just this skill

Install the whole plugin

Add Samuel's marketplace, then install the plugin

What's inside

More skills

golang-benchmark

golang-cli

golang-code-style

golang-concurrency

golang-context

golang-continuous-integration