reagin Uber Dig dependency graphs
Keep Dig at the application's composition boundary rather than passing the container into domain code.
Inspect before editing
Check go.mod, container construction options, registration helpers, Provide and Invoke roots, dig.In/dig.Out types, names, value groups, decorators, scopes, and graph tests. Use APIs supported by the selected module version and preserve any local wrapper that centralizes registration or error handling.
Graph invariants
- Check every registration error.
Providevalidates the constructor shape, while missing dependencies and constructor failures may surface only when a root is invoked. - Constructors are called lazily when their outputs are needed and their results are reused according to container/scope semantics. Do not add side effects assuming registration executes them.
- Use parameter or result objects when they clarify optional, named, or grouped dependencies; do not impose a numeric parameter threshold on otherwise clear constructors.
- Names and groups are part of the graph contract. Group ordering is not guaranteed, so an ordered middleware or migration chain should be assembled explicitly.
- Optional dependencies can hide incomplete wiring. Use them only when absence is valid domain behavior and test both states.
- Keep decorators and scopes within their intended boundary. Verify whether a scoped object owns or borrows dependencies before adding cleanup around it.
Read references/api-and-testing.md for concrete Provide/Invoke, parameter and result objects, names, groups, interface exposure, and graph-test patterns.
Change the graph coherently
For a provider change:
- identify every composition root and scope that registers it;
- trace consumers by type, name, and group;
- update provider/result annotations and consumers together;
- invoke every affected root in a fresh validation test;
- exercise constructor failure when resource acquisition or external setup changed.
Preserve the original Dig error as a cause when adding context so its dependency path remains inspectable.
Dig constructs an object graph; it does not own process lifecycle. Keep resource start/stop behavior in the application's established lifecycle rather than hiding unmanaged goroutines or shutdown hooks in registration code.
Failure handling
Return constructor errors when initialization can fail. Panic recovery options are not a substitute for normal error handling. Preserve useful dependency paths when wrapping container errors.
Container options such as panic recovery, dry run, or deferred cycle checks change when failures surface; document and test the behavior actually selected by the composition root.
For graph-only validation, use the selected version's supported dry-run or validation approach and understand whether it skips constructor execution. When behavior or side effects matter, invoke the real composition root in a controlled test instead.
Testing and verification
Build a fresh container per test unless scope sharing is under test. Replace external dependencies through constructors or supported decorators, invoke the same roots as production, and exercise missing providers, duplicate names, group contents, constructor errors, and scope behavior affected by the change.
Run formatting, compilation, and relevant tests. Validate every changed composition root; a registered constructor that is never requested can remain broken without ordinary execution exposing it.