golang-manual-di

Manual Dependency Injection for Go Services

This skill walks through the 7-step process for wiring a Go service by hand — no code generation, no reflection containers. Each step maps to patterns observed in production cmd/di/ packages.

---

Naming Convention Taxonomy

Every function in the DI layer follows one of three tiers that communicate risk to the reader:

Pattern	Intent	Risk
Provide…() / provide…()	Returns a value, no possible failure	None — safe to call anywhere
MustProvide…() / mustProvide…()	Builds infra that can panic on misconfiguration	Panics on bad config
Must…() / must…()	Starts a long-running service/process	Panics, process-level

Rules:

• Provide tier — Use for infallible constructors. Functions that do no I/O and cannot fail. Example: provideLogger(cfg LogConfig) zerolog.Logger. Never use Must here.
• MustProvide tier — Use for infrastructure builders that can panic (DB pools, cloud clients, OTEL init). The risk is confined to the init path — if it panics, the service never starts.
• Must tier — Use for entrypoints that spin up goroutines running servers or workers. The risk is process-level — if it panics, the process terminates.

Decision flowchart:

1. Does the function return a value? → If NO → skip to question 2. If YES → Go to question 3.
2. Does it perform side-effectful bootstrap that wires a global? (e.g. OTEL SDK init) → If YES → use init… (the only valid use). If NO → error — every function must return a value or be a true bootstrap.
3. Does the function do I/O or have a failure path? → If NO → Use Provide tier. If YES → Can it panic instead of returning an error? → If YES → Use MustProvide tier (for infra) or Must tier (for entrypoints). If NO → Return (T, error) instead.

Note on init…:

The init… prefix is reserved only for true one-shot side-effectful bootstrap that wires a global and does not return a usable value. Example: mustInitOTEL(ctx, cfg) wires the OTEL SDK as a global and returns nothing. Every other function that constructs and returns a dependency must use Provide… or MustProvide….