README
¶
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 improving 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. It does not rely on reflection.
Table of contents
- Basic usage
- Scopes
- Container deletion
- Methods to retrieve an object
- Unscoped retrieval
- Panic in Build and Close functions
- HTTP helpers
- Examples
- Migration from v1
Basic usage
Object definition
A Definition contains at least the Name of the object and a Build function to create the object.
di.Def{
Name: "my-object",
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
}
The definition can be added to a Builder with the Add method:
builder, _ := di.NewBuilder()
builder.Add(di.Def{
Name: "my-object",
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
})
If you have an already built object to put in the container, you can use the Set shortcut:
obj := &MyObject{}
builder, _ := di.NewBuilder()
builder.Set("my-object", obj)
Note that you can override a definition by adding a definition with the same name. This could be useful in some contexts (for example in unit tests to mock a dependency):
builder.Set("my-object", "A")
// override the previous definition
builder.Add(di.Def{
Name: "my-object",
Build: func(ctn di.Container) (interface{}, error) {
return "B", nil
},
})
// override the definition again, as if the two previous ones never existed
builder.Set("my-object", "C")
Object retrieval
Once the definitions have been added to a Builder, the Builder can generate a Container. This Container will provide the objects defined in the Builder.
ctn := builder.Build() // create the container
obj := ctn.Get("my-object").(*MyObject) // retrieve the object
The Get method returns an interface{}. You need to cast the interface before using the object.
Definitions and dependencies
The Build function can also use the Get method of the Container. That allows to build objects that depend on other objects defined in the Container.
di.Def{
Name: "object-with-dependency",
Build: func(ctn di.Container) (interface{}, error) {
return &MyObjectWithDependency{
Object: ctn.Get("my-object").(*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.
Unshared objects
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.
builder.Add(di.Def{
Name: "my-object",
Unshared: true, // The Build function will be called each time.
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
})
ctn.Get("my-object").(*MyObject) == ctn.Get("my-object").(*MyObject) // false
Scopes
The principle
Definitions can also have a scope. They can be useful in request based applications, like a web application.
di.Def{
Name: "my-object",
Scope: di.Request,
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
}
The available scopes are defined when the Builder is created:
builder, err := di.NewBuilder(di.App, di.Request)
Scopes are defined from the more generic to the more specific (eg: App ≻ Request ≻ SubRequest). If no scope is given to NewBuilder, the Builder is created with the three default scopes: di.App, di.Request and di.SubRequest. These scopes should be enough almost all the time.
The containers belong to one of these scopes. A container may have a parent in a more generic scope and children in a more specific scope. The Builder generates a Container in the most generic scope. Then the Container can generate children in the next scope thanks to the SubContainer method.
A container is only able to build objects defined in its own scope, but it can retrieve objects in a more generic scope thanks to its parent. For example a Request container can retrieve an App object, but an App container can not retrieve a Request object.
If a Definition does not have a scope, the most generic scope will be used.
Scopes in practice
// Create a Builder with the default scopes (App, Request, SubRequest).
builder, _ := di.NewBuilder()
// Define an object in the App scope.
builder.Add(di.Def{
Name: "app-object",
Scope: di.App, // this line is optional, di.App is the default scope
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
})
// Define an object in the Request scope.
builder.Add(di.Def{
Name: "request-object",
Scope: di.Request,
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
})
// Build creates a Container in the most generic scope (App).
app := builder.Build()
// The App Container can create sub-containers in the Request scope.
req1, _ := app.SubContainer()
req2, _ := app.SubContainer()
// app-object can be retrieved from the three containers.
// The retrieved objects are the same: o1 == o2 == o3.
// The object is stored in app.
o1 := app.Get("app-object").(*MyObject)
o2 := req1.Get("app-object").(*MyObject)
o3 := req2.Get("app-object").(*MyObject)
// request-object can only be retrieved from req1 and req2.
// The retrieved objects are not the same: o4 != o5.
// o4 is stored in req1, and o5 is stored in req2.
o4 := req1.Get("request-object").(*MyObject)
o5 := req2.Get("request-object").(*MyObject)
More graphically, the containers could be represented like this:
The App container can only get the App object. A Request container or a SubRequest container can get either the App object or the Request object, possibly by using their parent. The objects are built and stored in containers that have the same scope. They are only created when they are requested.
Scopes and dependencies
If an object depends on other objects defined in the container, the scopes of the dependencies must be either equal or more generic compared to the object scope.
For example the following definitions are not valid:
di.Def{
Name: "request-object",
Scope: di.Request,
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
}
di.Def{
Name: "object-with-dependency",
Scope: di.App, // NOT ALLOWED !!! should be di.Request or di.SubRequest
Build: func(ctn di.Container) (interface{}, error) {
return &MyObjectWithDependency{
Object: ctn.Get("request-object").(*MyObject),
}, nil
},
}
Container deletion
A definition can also have a Close function.
di.Def{
Name: "my-object",
Scope: di.App,
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
return obj.(*MyObject).Close()
},
}
This function is called when the Delete method is called on a Container.
// Create the Container.
app := builder.Build()
// Retrieve an object.
obj := app.Get("my-object").(*MyObject)
// Delete the Container, the Close function will be called on obj.
app.Delete()
Delete closes all the objects stored in the Container. Once a Container has been deleted, it becomes unusable.
It is important to always use Delete even if the objects definitions do not have a Close function. It allows to free the memory taken by the Container.
There are actually two delete methods: Delete and DeleteWithSubContainers
DeleteWithSubContainers deletes the children of the Container and then the Container. It does this right away. Delete is a softer approach. It does not delete the children of the Container. Actually it does not delete the Container as long as it still has a child alive. So you have to call Delete on all the children. The parent Container will be deleted when Delete is called on the last child.
You probably want to use Delete and close the children manually. DeleteWithSubContainers can cause errors if the parent is deleted while its children are still used.
Methods to retrieve an object
When 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.
A container can only build objects defined in the same scope. 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
Get returns an interface that can be cast afterwards. If the object can not be created, the Get function panics.
obj := ctn.Get("my-object").(*MyObject)
SafeGet
Get is an easy way to retrieve an object. The problem is that it can panic. If it is a problem for you, you can use SafeGet. Instead of panicking, it returns an error.
objectInterface, err := ctn.SafeGet("my-object")
object, ok := objectInterface.(*MyObject)
Fill
The third and last method to retrieve an object is Fill. It returns an error if something goes wrong like SafeGet, but it may be more practical in some situations. It uses reflection to fill the given object. Using reflection makes it is slower than SafeGet.
var object *MyObject
err := ctn.Fill("my-object", &object)
Unscoped retrieval
The previous methods can retrieve an object defined in the same scope or a more generic one. If you need an object defined in a more specific scope, you need to create a sub-container to retrieve it. For example, an App container can not create a Request object. A Request container should be created to retrieve the Request object. It is logical but not always very practical.
UnscopedGet, UnscopedSafeGet and UnscopedFill work like Get, SafeGet and Fill but can retrieve objects defined in a more generic scope. To do so, they generate sub-containers that can only be accessed internally by these three methods. To remove these containers without deleting the current container, you can call the Clean method.
builder, _ := di.NewBuilder()
builder.Add(di.Def{
Name: "request-object",
Scope: di.Request,
Build: func(ctn di.Container) (interface{}, error) {
return &MyObject{}, nil
},
Close: func(obj interface{}) error {
return obj.(*MyObject).Close()
},
})
app := builder.Build()
// app can retrieve a request-object with unscoped methods.
obj := app.UnscopedGet("request-object").(*MyObject)
// Once the objects created with unscoped methods are no longer used,
// you can call the Clean method. In this case, the Close function
// will be called on the object.
app.Clean()
Panic in Build and Close functions
Panics in Build and Close functions of a definition are recovered and converted into errors. In particular that allows you to use the Get method in a Build function.
HTTP helpers
DI includes some elements to ease its integration in a web application.
The HTTPMiddleware function can be used to inject a container in an http.Request.
// create an App container
builder, _ := NewBuilder()
builder.Add(/* some definitions */)
app := builder.Build()
handlerWithDiMiddleware := di.HTTPMiddleware(handler, app, func(msg string) {
logger.Error(msg) // use your own logger here, it is used to log container deletion errors
})
For each http.Request, a sub-container of the app container is created. It is deleted at the end of the http request.
The container can be used in the handler:
handler := func(w http.ResponseWriter, r *http.Request) {
// retrieve the Request container with the C function
ctn := di.C(r)
obj := ctn.Get("object").(*MyObject)
// there is a shortcut to do that
obj := di.Get(r, "object").(*MyObject)
}
The handler and the middleware can panic. Do not forget to use another middleware to recover from the panic and log the errors.
Examples
The sarulabs/di-example repository is a good example to understand how DI can be used in a web application.
More explanations about this repository can be found in this blog post:
If you do not have time to check this repository, here is a shorter example that does not use the HTTP helpers. It does not handle the errors to be more concise.
package main
import (
"context"
"database/sql"
"net/http"
"github.com/sarulabs/di"
_ "github.com/go-sql-driver/mysql"
)
func main() {
app := createApp()
defer app.Delete()
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
// Create a request and delete it once it has been handled.
// Deleting the request will close the connection.
request, _ := app.SubContainer()
defer request.Delete()
handler(w, r, request)
})
http.ListenAndServe(":8080", nil)
}
func createApp() di.Container {
builder, _ := di.NewBuilder()
builder.Add([]di.Def{
{
// Define the connection pool in the App scope.
// There will be one for the whole application.
Name: "mysql-pool",
Scope: di.App,
Build: func(ctn di.Container) (interface{}, error) {
db, err := sql.Open("mysql", "user:password@/")
db.SetMaxOpenConns(1)
return db, err
},
Close: func(obj interface{}) error {
return obj.(*sql.DB).Close()
},
},
{
// Define the connection in the Request scope.
// Each request will use its own connection.
Name: "mysql",
Scope: di.Request,
Build: func(ctn di.Container) (interface{}, error) {
pool := ctn.Get("mysql-pool").(*sql.DB)
return pool.Conn(context.Background())
},
Close: func(obj interface{}) error {
return obj.(*sql.Conn).Close()
},
},
}...)
// Returns the app Container.
return builder.Build()
}
func handler(w http.ResponseWriter, r *http.Request, ctn di.Container) {
// Retrieve the connection.
conn := ctn.Get("mysql").(*sql.Conn)
var variable, value string
row := conn.QueryRowContext(context.Background(), "SHOW STATUS WHERE `variable_name` = 'Threads_connected'")
row.Scan(&variable, &value)
// Display how many connections are opened.
// As the connection is closed when the request is deleted,
// the value should not be be higher than the number set with db.SetMaxOpenConns(1).
w.Write([]byte(variable + ": " + value))
}
Migration from v1
DI v2 improves error handling. It should also be faster. Migrating to v2 is highly recommended and should not be too difficult. There should not be any more changes in the API for a long time.
Renamed elements
Some elements have been renamed.
A Context is now a Container.
The Context methods SubContext, NastySafeGet, NastyGet, NastyFill have been renamed. Their new names are SubContainer, UnscopedSafeGet, UnscopedGet, and UnscopedFill.
Definition is now Def. The AddDefinition of the Builder is now Add and can take more than one definition as parameter.
Definition Tags were removed in v2.0 but they are back in v2.1.
Errors
The Close function in a definition now returns an error.
The Container methods Clean, Delete and DeleteWithSubContainers also return an error.
Get
The Get method used to return nil if it could not retrieve the object. Now it panics with the error.
Logger
The Logger does not exist anymore. The errors are now directly handled by the retrieval functions.
// remove this line if you have it
builder.Logger = ...
Builder.Set
The Set method of the builder does not exist anymore. You should use the Add method and a Def.
Documentation
¶
Index ¶
Constants ¶
const App = "app"
App is the name of the application scope.
const Request = "request"
Request is the name of the request scope.
const SubRequest = "subrequest"
SubRequest is the name of the subrequest scope.
Variables ¶
var C = func(i interface{}) Container { if c, ok := i.(Container); ok { return c } r, ok := i.(*http.Request) if !ok { panic("could not get the container with C()") } c, ok := r.Context().Value(containerKey).(Container) if !ok { panic("could not get the container from the given *http.Request") } return c }
C retrieves a Container from an interface. The function panics if the Container can not be retrieved.
The interface can be :
- a Container
- an *http.Request containing a Container in its context.Context for the ContainerKey("di") key.
The function can be changed to match the needs of your application.
Functions ¶
func HTTPMiddleware ¶
func HTTPMiddleware(h http.HandlerFunc, app Container, logFunc func(msg string)) http.HandlerFunc
HTTPMiddleware adds a container in the request context.
The container injected in each request, is a new sub-container of the app container given as parameter.
It can panic, so it should be used with another middleware to recover from the panic, and to log the error.
It uses logFunc, a function that can log an error. logFunc is used to log the errors during the container deletion.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder can be used to create a Container. The Builder should be created with NewBuilder. Then you can add definitions with the Add method, and finally build the Container with the Build method.
func NewBuilder ¶
NewBuilder is the only way to create a working Builder. It initializes a Builder with a list of scopes. The scopes are ordered from the most generic to the most specific. If no scope is provided, the default scopes are used: [App, Request, SubRequest] It can return an error if the scopes are not valid.
func (*Builder) Add ¶
Add adds one or more definitions in the Builder. It returns an error if a definition can not be added. If a definition with the same name has already been added, it will be replaced by the new one, as if the first one never existed.
func (*Builder) Build ¶
Build creates a Container in the most generic scope with all the definitions registered in the Builder.
func (*Builder) Definitions ¶
Definitions returns a map with the all the objects definitions registered with the Add method. The key of the map is the name of the Definition.
type Container ¶
type Container interface {
// Definition returns the map of the available definitions ordered by name.
// These definitions represent all the objects that this Container can build.
Definitions() map[string]Def
// Scope returns the Container scope.
Scope() string
// Scoped returns the context Container scope.
Scoped(ctx context.Context) context.Context
// Scopes returns the list of available scopes.
Scopes() []string
// ParentScopes returns the list of scopes that are more generic than the Container scope.
ParentScopes() []string
// SubScopes returns the list of scopes that are more specific than the Container scope.
SubScopes() []string
// Parent returns the parent Container.
Parent() Container
// SubContainer creates a new Container in the next sub-scope
// that will have this Container as parent.
SubContainer() (Container, error)
// SafeGet retrieves an object from the Container.
// The object has to belong to this scope or a more generic one.
// If the object does not already exist, it is created and saved in the Container.
// If the object can not be created, it returns an error.
SafeGet(name string) (interface{}, error)
// Get is similar to SafeGet but it does not return the error.
// Instead it panics.
Get(name string) interface{}
// Fill is similar to SafeGet but it does not return the object.
// Instead it fills the provided object with the value returned by SafeGet.
// The provided object must be a pointer to the value returned by SafeGet.
Fill(name string, dst interface{}) error
// UnscopedSafeGet retrieves an object from the Container, like SafeGet.
// The difference is that the object can be retrieved
// even if it belongs to a more specific scope.
// To do so, UnscopedSafeGet creates a sub-container.
// When the created object is no longer needed,
// it is important to use the Clean method to delete this sub-container.
UnscopedSafeGet(name string) (interface{}, error)
// UnscopedGet is similar to UnscopedSafeGet but it does not return the error.
// Instead it panics.
UnscopedGet(name string) interface{}
// UnscopedFill is similar to UnscopedSafeGet but copies the object in dst instead of returning it.
UnscopedFill(name string, dst interface{}) error
// Clean deletes the sub-container created by UnscopedSafeGet, UnscopedGet or UnscopedFill.
Clean() error
// DeleteWithSubContainers takes all the objects saved in this Container
// and calls the Close function of their Definition on them.
// It will also call DeleteWithSubContainers on each child and remove its reference in the parent Container.
// After deletion, the Container can no longer be used.
// The sub-containers are deleted even if they are still used in other goroutines.
// It can cause errors. You may want to use the Delete method instead.
DeleteWithSubContainers() error
// Delete works like DeleteWithSubContainers if the Container does not have any child.
// But if the Container has sub-containers, it will not be deleted right away.
// The deletion only occurs when all the sub-containers have been deleted manually.
// So you have to call Delete or DeleteWithSubContainers on all the sub-containers.
Delete() error
// IsClosed returns true if the Container has been deleted.
IsClosed() bool
}
Container represents a dependency injection container. To create a Container, you should use a Builder or another Container.
A Container has a scope and may have a parent in a more generic scope and children in a more specific scope. Objects can be retrieved from the Container. If the requested object does not already exist in the Container, it is built thanks to the object definition. The following attempts to get this object will return the same object.
type ContainerKey ¶
type ContainerKey string
ContainerKey is a type that can be used to store a container in the context.Context of an http.Request. By default, it is used in the C function and the HTTPMiddleware.
type Def ¶
type Def struct {
// Build is the function that is used to create the object.
Build func(ctn Container) (interface{}, error)
// Close is the function that is used to clean the object when the container is deleted.
// It can be nil if nothing needs to be done to close the object.
Close func(obj interface{}) error
// Name is the key that is used to retrieve the object from the container.
Name string
// Scope determines in which container the object is stored.
// Typical scopes are "app" and "request".
Scope string
// Tags are not used inside this library. But they can be useful to sort your definitions.
Tags []Tag
// They are singleton and the same instance will be returned each time "Get", "SafeGet" or "Fill" is called.
// If you want to retrieve a new object every time, "Unshared" needs to be set to true.
Unshared bool
}
Def contains information to build and close an object inside a Container.
Source Files