Package Usage: go: go.uber.org/dig
Package dig provides an opinionated way of resolving object dependencies.
STABLE. No breaking changes will be made in this major version.
Dig exposes type Container as an object capable of resolving a directed
acyclic dependency graph. Use the New function to create one.
Constructors for different types are added to the container by using the
Provide method. A constructor can declare a dependency on another type by
simply adding it as a function parameter. Dependencies for a type can be
added to the graph both, before and after the type was added.
Multiple constructors can rely on the same type. The container creates a
singleton for each retained type, instantiating it at most once when
requested directly or as a dependency of another type.
Constructors can declare any number of dependencies as parameters and
optionally, return errors.
Constructors can also return multiple results to add multiple types to the
container.
Constructors that accept a variadic number of arguments are treated as if
they don't have those arguments. That is,
Is treated the same as,
The constructor will be called with all other dependencies and no variadic
arguments.
Types added to the container may be consumed by using the Invoke method.
Invoke accepts any function that accepts one or more parameters and
optionally, returns an error. Dig calls the function with the requested
type, instantiating only those types that were requested by the function.
The call fails if any type or its dependencies (both direct and transitive)
were not available in the container.
Any error returned by the invoked function is propagated back to the
caller.
Constructors declare their dependencies as function parameters. This can
very quickly become unreadable if the constructor has a lot of
dependencies.
A pattern employed to improve readability in a situation like this is to
create a struct that lists all the parameters of the function as fields and
changing the function to accept that struct instead. This is referred to as
a parameter object.
Dig has first class support for parameter objects: any struct embedding
dig.In gets treated as a parameter object. The following is equivalent to
the constructor above.
Handlers can receive any combination of parameter objects and parameters.
Result objects are the flip side of parameter objects. These are structs
that represent multiple outputs from a single function as fields in the
struct. Structs embedding dig.Out get treated as result objects.
The above is equivalent to,
Constructors often don't have a hard dependency on some types and
are able to operate in a degraded state when that dependency is missing.
Dig supports declaring dependencies as optional by adding an
`optional:"true"` tag to fields of a dig.In struct.
Fields in a dig.In structs that have the `optional:"true"` tag are treated
as optional by Dig.
If an optional field is not available in the container, the constructor
will receive a zero value for the field.
Constructors that declare dependencies as optional MUST handle the case of
those dependencies being absent.
The optional tag also allows adding new dependencies without breaking
existing consumers of the constructor.
Some use cases call for multiple values of the same type. Dig allows adding
multiple values of the same type to the container with the use of Named
Values.
Named Values can be produced by passing the dig.Name option when a
constructor is provided. All values produced by that constructor will have
the given name.
Given the following constructors,
You can provide *sql.DB into a Container under different names by passing
the dig.Name option.
Alternatively, you can produce a dig.Out struct and tag its fields with
`name:".."` to have the corresponding value added to the graph under the
specified name.
Regardless of how a Named Value was produced, it can be consumed by another
constructor by accepting a dig.In struct which has exported fields with the
same name AND type that you provided.
The name tag may be combined with the optional tag to declare the
dependency optional.
Added in Dig 1.2.
Dig provides value groups to allow producing and consuming many values of
the same type. Value groups allow constructors to send values to a named,
unordered collection in the container. Other constructors can request all
values in this collection as a slice.
Constructors can send values into value groups by returning a dig.Out
struct tagged with `group:".."`.
Any number of constructors may provide values to this named collection.
Other constructors can request all values for this collection by requesting
a slice tagged with `group:".."`. This will execute all constructors that
provide a value to that group in an unspecified order.
Note that values in a value group are unordered. Dig makes no guarantees
about the order in which these values will be produced.
Value groups can be used to provide multiple values for a group from a
dig.Out using slices, however considering groups are retrieved by requesting
a slice this implies that the values must be retrieved using a slice of
slices. As of dig v1.9.0, if you want to provide individual elements to the
group instead of the slice itself, you can add the `flatten` modifier to the
group from a dig.Out.
27 versions
Latest release: almost 2 years ago
2,052 dependent packages
View more package details: https://packages.ecosystem.code.gouv.fr/registries/proxy.golang.org/packages/go.uber.org/dig