AI assistant prompts for dig live in prompts. Entry point: system_prompt_dig_en.md — covers core API & CLI, troubleshooting, version migration, and a dig/Wire/Fx comparison.
A complete standardized production coding convention skill for business microservice based on dig: Industrial Modular Coding Skill
中文文档 | English | Documentation site
Current version: v1.0.24 — full release notes in CHANGELOG_en.md.
Go DI tools fall into two camps:
- Uber Fx: elegant API (
Provide/Invoke/Supply/Module) but runtime reflection – slower startup, runtime panics on dependency errors, larger binaries. - Google Wire: compile‑time safety and zero overhead, but API is verbose and counter‑intuitive – repetitive
wire.NewSet, manual interface binding,wire.Valueforbids function calls and channel receives, and the infamouswire.Builddummyreturn nil, nilmarker.
dig combines the best of both: Fx‑style minimal API + Wire‑style code generation (no reflection, zero runtime dependency), plus strict closure‑capture safety, generic support, built‑in Invoke, sensible policies for unused providers, and native support for multiple instances of the same type via parameter names.
Note on the name: This project (
github.com/shanjunmei/dig) is a compile‑time, code‑generation DI library and is unrelated to Uber's runtime reflection containergo.uber.org/dig(the engine behinduber‑go/fx). Don't confuse the two.
- Compile‑time resolution – graph resolved during
go generate; errors are caught at generation time. - Zero runtime reflection & zero runtime dependency – generated code is plain Go with no third-party runtime dependency (only the standard library, e.g.
context). - Minimal API – just
Build,Provide,Supply,Invoke,Module. - Closure capture safety – inline closures cannot capture locals from
InitApp; enforced by generator. - Identity-closure collapse (always on) – closures of the form
func(p T) T { return p },func(p *T) T { return *p },func(p T) *T { return &p }, direct type-conversionfunc(p T) U { return U(p) }, and type assertionfunc(p any) T { return p.(T) }collapse to a single inline expression (e.g.T(p),*p,&p,p.(T)). Independent of-inline. - Closure inlining (
-inline) – inline simple non-identity closures as immediately-invoked function expressions (IIFE), reducing generated function count. Off by default. - Generic‑aware – supports generic functions and types natively.
- Observability – debug logging with runtime‑overridable
Logf;-debugalso prints resolved per-package import alias mappings. - Actionable errors – all error messages include source location (
file:line:col) and💡 Fix:suggestions. - Unused‑provider policies –
error(default),ignore, ordrop. - Module nesting – compose modules hierarchically; duplicate detection built‑in.
- Named instance injection – inject multiple instances of the same type by distinguishing them via parameter names.
- ShadowGuard – generator-level guard that auto-detects and avoids variable-name shadowing in generated code.
go get github.com/shanjunmei/dig@latest
go install github.com/shanjunmei/dig/cmd/digen@latestRequires Go 1.22+.
Build with Mage (optional, auto-injects version info):
mage build # build binary with version info from git
mage install # install to $GOPATH/bin
mage test # run tests with race detectorNote:
cmd/digenv1in this repository is a legacy single-file generator prototype and is not for end users — always usecmd/digen.
di.go (build tag //go:build digen):
//go:build digen
package main
import (
"context"
"github.com/shanjunmei/dig"
)
//go:generate go run -mod=mod github.com/shanjunmei/dig/cmd/digen -out dig_gen.go
func InitApp() func(context.Context) error {
return dig.Build(
dig.Provide(NewConfig),
dig.Provide(NewDB),
dig.Supply(DefaultTimeout), // direct value
dig.Provide(func(t Timeout) *Server { return NewServer(t) }),
dig.Invoke(func(srv *Server) error { return srv.Run() }),
)
}main.go (business logic):
package main
import "context"
type Config struct{ Addr string }
func NewConfig() *Config { return &Config{Addr: ":8080"} }
type DB struct{}
func NewDB(*Config) *DB { return &DB{} }
type Timeout int
var DefaultTimeout Timeout = 5
type Server struct{}
func NewServer(Timeout) *Server { return &Server{} }
func (*Server) Run() error { return nil }
func main() {
if err := InitApp()(context.Background()); err != nil {
panic(err)
}
}Generate & run:
digen ./... # or go generate ./...
go run .| Function | Purpose |
|---|---|
dig.Build(...Option) func(context.Context) error |
Assemble container; returns runnable function. |
dig.Provide(any) Option |
Register a constructor (returns a value). |
dig.Supply(any) Option |
Inject an existing value (any expression, runtime‑safe). |
dig.Invoke(any) Option |
Run a function after all providers are ready (may return error). |
dig.Module(...Option) Option |
Group options into reusable, nestable module. |
dig supports injecting multiple instances of the same type by differentiating them through parameter names. This is useful for scenarios like:
- Multiple database connections (primary, replica, reporting)
- Multiple Redis clients for different business domains
- Multiple HTTP clients with different configurations
- Define a provider with named return values – the names become the "instance names".
- Depend on a specific instance by using the same parameter name in your consumer function.
// Provider returns two *sql.DB instances with different names
dig.Provide(func() (mainDB *sql.DB, reportDB *sql.DB, error) {
main, err := connectMain()
if err != nil { return nil, nil, err }
report, err := connectReport()
if err != nil { return nil, nil, err }
return main, report, nil
})
// Consumer uses the main database
dig.Invoke(func(mainDB *sql.DB) {
// mainDB is automatically injected
})
// Consumer uses the report database
dig.Invoke(func(reportDB *sql.DB) {
// reportDB is automatically injected
})You can also supply named values directly:
dig.Supply(mainDB) // variable name becomes instance name
dig.Supply(reportDB)The generator uses the variable name (not the type) to distinguish instances.
If multiple instances exist for the same type and a consumer does not specify a parameter name, the generator will produce an error listing the available names:
ambiguous dependency: multiple providers for type *sql.DB available:
- mainDB
- reportDB
- Existing code that uses a single instance of a type remains unchanged.
- The feature is additive – no breaking changes.
Closures inside Provide/Invoke cannot capture local variables from InitApp – only package‑level symbols and literals are allowed (generator lifts them to package level).
✅ Allowed: func() Timeout { return DefaultTimeout }
❌ Forbidden: t := 5; func() Timeout { return Timeout(t) }
All InitApp parameters are automatically registered as Supply providers – inject them anywhere.
Use distinct types to avoid duplicate provider errors for same underlying type (e.g., multiple bools):
type UseMySQL bool
type UseRedis boolExplicitly instantiate generic types/functions:
dig.Provide(NewStore[int])
dig.Invoke(Process[string])Branching works inside closures (runtime). For compile‑time selection, use build tags – do not put conditionals inside Module() (all branches are parsed).
Run digen -debug to inject Logf calls. Override at runtime:
var Logf = log.Printf // defined in dig_gen.go
func main() { Logf = myLogger.Printf }-unused=error|ignore|drop (default error).
-alias=full|short|obfuscated|numeric controls generated import aliases. Resolved per-package alias mappings are printed as debug output when -debug is enabled.
-inline inlines simple provider/invoke closures as IIFEs instead of generating named package-level functions. Identity closures (func(p T) T { return p }, func(p *T) T { return *p }, func(p T) *T { return &p }, func(p any) T { return p.(T) } (type assertion), and direct type-conversion closures) collapse to a single inline expression.
Every file that contains a dig.Build(...) call must carry the //go:build digen constraint. digen hard-codes //go:build !digen on the generated dig_gen.go; without the matching tag on your source, a normal go build compiles both files and fails with InitApp redeclared. digen now enforces this at generation time — if the tag is missing it prints a clear error with a 💡 Fix: instead of letting a confusing redeclaration surface later.
Providers (constructors registered via dig.Provide / dig.Supply / dig.Module) may not declare a context.Context parameter. Providers are resolved eagerly inside InitApp, before the runtime context.Context exists, so the parameter would be undefined in the generated code. Context injection is only valid inside dig.Invoke(func(ctx context.Context) { ... }). digen rejects provider-side context.Context parameters at generation time with a 💡 Fix: pointing you to dig.Invoke or dig.Supply.
12. di.go holds wiring only: types / constructors / package-level vars must live in a non-//go:build digen file or an imported package
The di.go file (with //go:build digen) may only contain the dig.Build(...) wiring (Provide / Invoke / Supply / Module calls). Every domain type, constructor, and package-level variable referenced by the wiring must be defined in a file without that build tag (e.g. types.go) or in an imported package. Reason: the generated dig_gen.go carries //go:build !digen, so at a normal go build (without the digen tag) di.go is excluded and its symbols are invisible to the generated code, causing a confusing undefined: X. digen now runs a contract pre-check (checkContractVisibility) before writing any file: if the wiring references a main-package symbol defined inside a digen file, it aborts immediately with a clear error and a 💡 Fix:, instead of letting the type-checker catch it later.
Generation safety net. After code generation, digen runs a
go/typestype-check on the emitteddig_gen.go. Your source is already type-checked when digen loads it, so a type error in the generated file can only be one of two things: (a) a genuine internal generator bug, or (b) a digen-contract violation that slipped past the pre-check (only possible on an IR-cache hit where the pre-check is skipped). Both abort the write; contract violations get the same💡 Fix:guidance as the pre-check, while internal bugs print a one-click, pre-filled GitHub issue link (plus a copy-paste template) so the defect is reported upstream — never a silent, uncompilable file.
| Flag | Default | Description |
|---|---|---|
-out |
dig_gen.go |
Output filename (ignored in ./... mode) |
-unused |
error |
Policy for unused providers |
-debug |
false |
Enable debug logging (detailed errors are always shown) |
-alias |
full |
Import alias strategy: full / short / obfuscated / numeric. When -debug is enabled, resolved per-package alias mappings are also printed. |
-inline |
false |
Inline simple closures as IIFEs only; identity closures are ALWAYS collapsed to a type conversion (independent of this flag) |
-typecheck |
true |
Type-check generated code after emission to catch internal generator bugs. Disable (-typecheck=false) for large ./... runs where reloading the package graph per file is expensive. |
-cache |
false |
Cache the extracted IR to disk and reuse it for unchanged packages (skips extraction on cache hit). |
-cachedir |
"" |
IR cache directory (default: os.TempDir()/digen-ir-cache); ignored unless -cache is set. |
-version |
false |
Print version information and exit |
Besides the default generation run (digen [packages...]), digen provides subcommands for scaffolding, validation, and inspection:
| Command | Description |
|---|---|
digen init [path] |
Scaffold a di.go containing the dig.Build entry point. |
digen check [pkgs] |
Validate DI contracts (extraction + unused-provider check) without writing any file. |
digen graph [pkgs] |
Print the provider dependency graph as a Mermaid flowchart. |
digen explain <type> [pkgs] |
Explain how a type/provider is resolved (match by name or return type). |
digen completion <shell> |
Print a shell completion script (bash, zsh, fish). |
All flags (-out, -unused, -debug, -alias, -inline, -typecheck, -cache, -cachedir, -version) apply to both the generation run and the check / graph / explain subcommands.
| Feature | dig | Google Wire | Uber Fx |
|---|---|---|---|
| Approach | Code generation | Code generation | Runtime reflection |
| Codegen step required | ✅ digen |
✅ wire CLI |
❌ |
| Zero reflection | ✅ | ✅ | ❌ |
| Zero runtime dependency | ✅ | ✅ | ❌ (requires fx + dig runtime) |
| Validation timing | Generation time | Generation time | Runtime (fx.New / fx.ValidateApp) |
| Provider initialization | Eager (at InitApp call) |
Eager (in generated injector) | Lazy (only if consumed) |
| Binary size impact | Minimal | Minimal | Moderate (fx + dig + multierr) |
| Feature | dig | Google Wire | Uber Fx |
|---|---|---|---|
| Core API surface | 5 (Build/Provide/Supply/Invoke/Module) |
7 (Build/NewSet/Value/InterfaceValue/Bind/Struct/FieldsOf) |
15+ (Provide/Supply/Invoke/Module/Annotate/Annotated/Decorate/Replace/WithLogger/…) |
| Direct value injection | ✅ dig.Supply (any expr) |
wire.Value (no fn calls / channel recv) |
✅ fx.Supply (concrete only; interface needs fx.As) |
Built‑in Invoke |
✅ | ❌ | ✅ |
| Module definition | dig.Module(...Option) |
var Set = wire.NewSet(...) |
fx.Module("name", ...) |
| Module nesting | ✅ explicit | ✅ explicit, named | |
| Module naming required | ❌ | N/A | ✅ |
| Module scoping (private providers) | ❌ | ❌ | ✅ fx.Private |
| Interface binding | via identity closure (e.g. func(p *Impl) Iface { return p }, always collapsed to a conversion, independent of -inline) |
✅ explicit wire.Bind(new(Iface), new(*Impl)) |
✅ fx.Annotate(NewImpl, fx.As(new(Iface))) |
| Struct field injection | ❌ | ✅ wire.Struct |
❌ (use a constructor) |
| Struct field extraction | ❌ | ✅ wire.FieldsOf |
❌ |
| Multiple instances of same type | ✅ Named parameters | ❌ (must use wrapper types) | ✅ Named + Value Groups |
| Value groups (collections of same type) | ❌ | ❌ | ✅ group:"name" (with flatten / soft) |
| Optional dependencies | ❌ | ❌ | ✅ optional:"true" |
| Cleanup functions | ❌ | ✅ 2nd return func(), ordering guaranteed |
✅ via OnStop hooks |
| Lifecycle hooks (OnStart / OnStop) | ❌ | ❌ | ✅ fx.Lifecycle |
| Decorators (wrap / replace at runtime) | ❌ | ❌ | ✅ fx.Decorate / fx.Replace |
| Generic support | ✅ compile‑time (explicit instantiation) | ❌ (must wrap each instantiation) | |
| Closure capture safety | ✅ enforced by generator | N/A (functions only) | N/A |
| API ergonomics | Fx‑style, minimal | Wire‑style, verbose & counter‑intuitive | Fx‑style, minimal |
| Feature | dig | Google Wire | Uber Fx |
|---|---|---|---|
| Error propagation model | Provider errors panic (fail‑fast); Invoke errors returned |
Provider error return, propagated through injector |
app.Err(); failed start rolls back OnStop hooks |
| Source location in errors | ✅ file:line:col on every error |
||
| Actionable fix suggestions | ✅ 💡 Fix: on every error |
❌ | ❌ |
| Unused provider policies | 3 modes (error / ignore / drop) |
hard error only (no modes) | N/A (lazy; silently skipped) |
| Validation without running | ✅ digen check / generation |
✅ (generation = validation) | ✅ fx.ValidateApp(opts) |
| Debug logging | ✅ runtime‑overridable Logf |
❌ manual | ✅ fxevent (Console / Zap / Slog) |
| Dependency graph visualization | ✅ digen graph (Mermaid) |
❌ | ✅ fx.DotGraph + fx.VisualizeError (DOT) |
| Resolution path explanation | ✅ digen explain <type> |
❌ (read generated code) | ❌ (runtime errors only) |
| Testing helpers | ❌ | ❌ | ✅ fxtest package |
| Feature | dig | Google Wire | Uber Fx |
|---|---|---|---|
| App lifecycle object | ❌ (returns bare func(ctx) error) |
❌ (returns generated value) | ✅ *fx.App (Start / Stop / Done / Wait) |
| Signal handling (SIGINT / SIGTERM) | ❌ (caller's responsibility) | ❌ | ✅ built into app.Run |
| Programmatic shutdown | ❌ | ❌ | ✅ fx.Shutdowner + fx.ExitCode |
| Configurable start / stop timeouts | N/A | N/A | ✅ (default 15s) |
| Feature | dig | Google Wire | Uber Fx |
|---|---|---|---|
| Maintenance status | ✅ active | ✅ active | |
| Latest version | v1.0.24 | v0.7.0 (Aug 2025, beta) | v1.24.0 (May 2025) |
| Go version requirement | 1.22+ | standard | 1.22+ |
| Refactoring friendliness | High (static checks + source location) | Low (cryptic errors) | Medium (runtime errors) |
Wire specifics:
wire.Buildrequires a dummyreturn nil, nil(orpanic(wire.Build(...)));wire.Valueforbids function calls and channel receives (not just constants, but close);wire.NewSetcomposition is flattened during analysis (no scoping / visibility barriers); the project is archived as of v0.7.0 — upstream no longer accepts new features, though bug fixes are still accepted; generics are not supported (must write a concrete provider for each instantiation).Fx specifics: richest feature set — full lifecycle (
OnStart/OnStopin dependency order with reverse‑order teardown), decorators (fx.Decorate/fx.Replace), value groups withflatten/softmodes,fx.Privatefor module scoping,fxtestfor testing,fx.DotGraphfor visualization, and signal‑awareapp.Runwithfx.Shutdowner. The cost is runtime reflection (startup latency), runtime panics on wiring errors (mitigated byfx.ValidateAppin CI), and a hard dependency on thefx+digruntime.dig trade‑offs: deliberately minimal — no lifecycle hooks, no cleanup functions, no decorators, no optional dependencies, no app object / signal handling.
InitApp()returns a barefunc(context.Context) error, so graceful shutdown is the caller's responsibility. In exchange: zero runtime overhead, compile‑time safety, source‑located errors with💡 Fix:suggestions, native generics, and the smallest API surface of the three.
| Operation | dig | Wire | Fx |
|---|---|---|---|
| Constructor | dig.Provide(NewSvc) |
wire.NewSet(NewSvc) |
fx.Provide(NewSvc) |
| Value injection | dig.Supply(val) |
wire.Value(val) (no fn calls) |
fx.Supply(val) |
| Startup hook | dig.Invoke(fn) |
not built‑in | fx.Invoke(fn) |
| Module group | dig.Module(a, b) |
wire.NewSet(a, b) |
fx.Module("name", a, b) |
| Build container | dig.Build(...) (returns runnable) |
wire.Build(...) (dummy marker) |
fx.New(...) |
| Run | run := InitApp(); run(ctx) |
call generated function | app.Run(ctx) |
| Interface binding | dig.Provide(func(p *Impl) Iface { return p }) |
wire.Bind(new(Iface), new(*Impl)) |
fx.Annotate(NewImpl, fx.As(new(Iface))) |
| Multiple instances | named return values + named params | not supported (wrapper types) | fx.Annotated{Name:"x"} / group:"x" |
| Cleanup / teardown | not supported (caller manages) | provider returns func() |
fx.Lifecycle OnStop hook |
| Graceful shutdown | caller handles signals | caller handles signals | app.Run (SIGINT/SIGTERM) + fx.Shutdowner |
See example/ for a full demonstration covering cross‑package deps, generics, same‑name modules, nesting, external params, Supply, closures, debug logs, build tags, alias strategies, and named instance injection for multiple databases.
cd example
digen -unused=ignore ./...
go run .MIT – see LICENSE.