Dependency injection container in go (golang)
Dependency injection framework for go programs (golang).
DI handles the life cycle of the objects in your application. It creates them when they are needed, resolves their dependencies, and closes them properly when they are no longer used.
If you do not know if DI could help improve your application, learn more about dependency injection and dependency injection containers:
There is also an Examples section at the end of the documentation.
DI is focused on performance.
A definition contains at least a Build function to create the object.
MyObjectDef := &di.Def{
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
}
// It is possible to add a name or a type to make the definition easier to retrieve.
// But it is not mandatory. Check the "Definitions" part of the documentation to learn more about that.
MyObjectDef.SetName("my-object")
MyObjectDef.SetIs((*MyObject)(nil))The definition can be added to a builder with the Add method:
builder, err := di.NewEnhancedBuilder()
err = builder.Add(MyObjectDef)Once all the definitions are added to the Builder, you can call the Build method to generate a Container.
ctn, err := builder.Build()Objects can then be retrieved from the container:
// Either with the definition (recommended)
ctn.Get(MyObjectDef).(*MyObject)
// Or the name (which is slower)
ctn.Get("my-object").(*MyObject)
// Or the type (even slower)
ctn.Get(reflect.typeOf((*MyObject)(nil))).(*MyObject)The Get method returns an interface{}. You need to cast the interface before using the object.
The container will only call the definition Build function the first time the Get method is called. After that, the same object is returned (unless the definition has its Unshared field set to true). That means the three calls in the example above return the same pointer. Check the Definitions section to learn more about them.
You need a builder to create a container.
You should use the EnhancedBuilder. It was introduced to add features that could not be added to the original Builder without breaking backward compatibility.
You need to use the NewEnhancedBuilder function to create the builder. Then you register the definitions with the Add method.
If you add two definitions with the same name, the first one is replaced.
builder, err := di.NewEnhancedBuilder()
// Adding a definition named "my-object".
err = builder.Add(&di.Def{
Name: "my-object",
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{Value: "A"}, nil
},
})
// Replacing the definition named "my-object".
err = builder.Add(&di.Def{
Name: "my-object",
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{Value: "B"}, nil
},
})
ctn, err := builder.Build()
ctn.Get("my-object").(*MyObject).Value // BBe sure to handle the errors properly even if it is not the case in this example for conciseness.
It is only possible to call the EnhancedBuilder.Build function once. After that, it will return an error.
Also, it is not possible to use the same definition in two different EnhancedBuilder.
And you should not update a definition once it has been added to the builder.
All these restrictions exist because the EnhancedBuilder.Build function alters the definitions. It resets the definition fields to their value at the time when the definition was added to the builder. Thus the definitions are linked to the builder and to the container it generates.
A definition only requires a Build function. It is used to create the object.
// You can either use the structure directly.
&di.Def{
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
}
// Or use the NewDef function to create the definition.
di.NewDef(func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
})The Build function returns the object and an error if it can not be created.
panics in Build functions are recovered and work as if an error was returned.
The Build function can also use the container. This allows you to build objects that depend on other objects defined in the container.
MyObjectDef := di.NewDef(func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
})
MyObjectWithDependencyDef := di.NewDef(func(ctn di.Container) (interface{}, error) {
// Using the Get method inside the build function is safe.
// Panics in this function are recovered.
// But be sure to add a name to the definitions if you want understandable error messages.
return &MyObjectWithDependency{
Object: ctn.Get(MyObjectDef).(*MyObject),
}, nil
})You can not create a cycle in the definitions (A needs B and B needs A). If that happens, an error will be returned at the time of the creation of the object.
You can add a name to the definition. It allows you to retrieve the definition from its name.
// Create a definition with a name.
MyObjectDef := &di.Def{
Name: "my-object",
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
}
// The SetName method can also be used.
MyObjectDef.SetName("my-object")
// Retrieve the definition from the container.
ctn.Get("my-object").(*MyObject)If you do not provide a name, a name will be automatically generated when the container is created.
:warning: Names are used in error messages. So it is recommended to set your own names to avoid troubles when debugging.
Retrieving an object from its name instead of its definition requires an additional lookup in a map[string]int. That makes it significantly slower. If performance is critical for you, you should retrieve objects from their definitions.
Another advantage of using the definitions for object retrieval is that it avoids the risk of a typo in the name.
The drawback is that you need to import the package containing the definitions which may lead to import cycles depending on your project structure.
There is a shortcut to create a definition for an object that is already built.
MyObjectDef = di.NewDefFor(myObject)
// is the same as
MyObjectDef = &di.Def{
Build: func(ctn di.Container) (interface{}, error) {
return myObject, nil
},
}By default, the Get method called on the same container always returns the same object.
The object is created when the Get method is called for the first time.
It is then stored inside the container and the same instance is returned in the next calls.
That means that the Build function is only called once.
If you want to retrieve a new instance of the object each time the Get method is called, you need to set the Unshared field of the definition to true.
MyObjectDef = &di.Def{
Unshared: true, // The Build function will be called each time.
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
}
// ...
// o1 != o2 because of Unshared=true
o1 := ctn.Get(MyObjectDef).(*MyObject)
o2 := ctn.Get(MyObjectDef).(*MyObject)A definition can also have a Close function.
di.Def{
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
Close: func(obj interface{}) error {
// Assuming that MyObject has a Close method that returns an error on failure.
return obj.(*MyObject).Close()
},
}This function is called when the container is deleted.
The deletion of the container must be triggered manually by calling the Delete method.
// Create the Container.
app, err := builder.Build()
// Retrieve an object.
obj := app.Get("my-object").(*MyObject)
// Delete the Container, the Close function will be called on obj.
err = app.Delete()It is possible to set the type of the object generated by the Build function.
It is only declarative and no checks are done to ensure that this information is valid.
It can be used to retrieve an object by its type instead of its name.
You can set multiple types, for example, a structure and an interface implemented by this structure.
…:warning: If multiple definitions have the same type, the one that was added last in the builder is used to retrieve the object.
It is possible to use the NewBuildFuncForType function to generate a Build function for a given structure (or pointer to a structure). When the object is created using reflection, it will try to set the fields based on their types and the other definitions. There is also a shortcut NewDefForType to create a definition based on NewBuildFuncForType.
…:warning: It is not recommended to use this because it is hard to know which fields are set and how. In addition to that, the use of reflection in the generated Build function makes it very slow. The behavior of the NewBuildFuncForType may also change in the future if ways to improve the feature are found.
You can add tags to a definition. Tags are not used internally by this library. They are only there to help you organize your definitions.
MyObjectDef = di.NewDefFor(myObject)
tag := di.Tag{
Name: "my-tag",
Args: map[string]string{
"tag-argument": "argument-value",
},
Data: "Data is an interface{} if Args are not enough",
}
MyObjectDef.SetTags(tag)
MyObjectDef.Tags[0] == tag // trueWhen a container is asked to retrieve an object, it starts by checking if the object has already been created. If it has, the container returns the already-built instance of the object. Otherwise, it uses the Build function of the associated definition to create the object. It returns the object, but also keeps a reference to be able to return the same instance if the object is requested again (unless the definition is UnShared).
A container can only build objects defined in the same scope (scopes documentation). If the container is asked to retrieve an object that belongs to a different scope. It forwards the request to its parent.
There are three methods to retrieve an object: Get, SafeGet and Fill.
Get returns an interface that can be cast afterward. If the object can not be created, the Get function panics.
// Retrieve the object from the definition (recoNo open issues yet, or sync has not completed.