Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/goioc/di
Simple and yet powerful Dependency Injection for Go
https://github.com/goioc/di
dependency-injection go golang golang-library inversion-of-control
Last synced: 14 days ago
JSON representation
Simple and yet powerful Dependency Injection for Go
- Host: GitHub
- URL: https://github.com/goioc/di
- Owner: goioc
- License: mit
- Created: 2020-06-11T12:28:06.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-03-21T19:20:42.000Z (8 months ago)
- Last Synced: 2024-07-31T20:52:21.483Z (3 months ago)
- Topics: dependency-injection, go, golang, golang-library, inversion-of-control
- Language: Go
- Homepage: https://pkg.go.dev/github.com/goioc/di/?tab=doc
- Size: 169 KB
- Stars: 351
- Watchers: 4
- Forks: 15
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-go - goioc/di - Spring-inspired Dependency Injection Container. (Miscellaneous / Dependency Injection)
- zero-alloc-awesome-go - goioc/di - Spring-inspired Dependency Injection Container. (Miscellaneous / Dependency Injection)
- awesome-go-extra - di - 06-11T12:28:06Z|2022-08-16T12:39:51Z| (Microsoft Office / Dependency Injection)
README
# goioc/di: Dependency Injection
[](https://github.com/goioc)
[](https://github.com/goioc/di/actions)
[](https://pkg.go.dev/github.com/goioc/di/?tab=doc)
[](https://www.codefactor.io/repository/github/goioc/di)
[](https://goreportcard.com/report/github.com/goioc/di)
[](https://sonarcloud.io/dashboard?id=goioc_di)
[](https://codecov.io/gh/goioc/di)
[](https://deepsource.io/gh/goioc/di/?ref=repository-badge)
[](https://github.com/sindresorhus/awesome)
[](https://ko-fi.com/G2G5JUKU7)
## Why DI in Go? Why IoC at all?
I've been using Dependency Injection in Java for nearly 10 years via [Spring Framework](https://spring.io/). I'm not saying that one can't live without it, but it's proven to be very useful for large enterprise-level applications. You may argue that Go follows a completely different ideology, values different principles and paradigms than Java, and DI is not needed in this better world. And I can even partly agree with that. And yet I decided to create this light-weight Spring-like library for Go. You are free to not use it, after all 🙂
## Is it the only DI library for Go?
No, of course not. There's a bunch of libraries around which serve a similar purpose (I even took inspiration from some of them). The problem is that I was missing something in all of these libraries... Therefore I decided to create Yet Another IoC Container that would rule them all. You are more than welcome to use any other library, for example [this nice project](https://github.com/sarulabs/di). And still, I'd recommend stopping by here 😉
## So, how does it work?
It's better to show than to describe. Take a look at this toy-example (error-handling is omitted to minimize code snippets):
**services/weather_service.go**
```go
package services
import (
"io"
"net/http"
)
type WeatherService struct {
}
func (ws *WeatherService) Weather(city string) (*string, error) {
response, err := http.Get("https://wttr.in/" + city)
if err != nil {
return nil, err
}
all, err := io.ReadAll(response.Body)
if err != nil {
return nil, err
}
weather := string(all)
return &weather, nil
}
```
**controllers/weather_controller.go**
```go
package controllers
import (
"di-demo/services"
"github.com/goioc/di"
"net/http"
)
type WeatherController struct {
// note that injection works even with unexported fields
weatherService *services.WeatherService `di.inject:"weatherService"`
}
func (wc *WeatherController) Weather(w http.ResponseWriter, r *http.Request) {
weather, _ := wc.weatherService.Weather(r.URL.Query().Get("city"))
_, _ = w.Write([]byte(*weather))
}
```
**init.go**
```go
package main
import (
"di-demo/controllers"
"di-demo/services"
"github.com/goioc/di"
"reflect"
)
func init() {
_, _ = di.RegisterBean("weatherService", reflect.TypeOf((*services.WeatherService)(nil)))
_, _ = di.RegisterBean("weatherController", reflect.TypeOf((*controllers.WeatherController)(nil)))
_ = di.InitializeContainer()
}
```
**main.go**
```go
package main
import (
"di-demo/controllers"
"github.com/goioc/di"
"net/http"
)
func main() {
http.HandleFunc("/weather", func(w http.ResponseWriter, r *http.Request) {
di.GetInstance("weatherController").(*controllers.WeatherController).Weather(w, r)
})
_ = http.ListenAndServe(":8080", nil)
}
```
If you run it, you should be able to observe a neat weather forecast at http://localhost:8080/weather?city=London (or for any other city).
Of course, for such a simple example it may look like an overkill. But for larger projects with many interconnected services with complicated business logic, it can really simplify your life!
## Looks nice... Give me some details!
The main component of the library is the [Inversion of Control Container](https://www.martinfowler.com/articles/injection.html) that contains and manages instances of your structures (called "beans").
### Types of beans
- **Singleton**. Exists only in one copy in the container. Every time you retrieve the instance from the container (or every time it's being injected to another bean) - it will be the same instance.
- **Prototype**. It can exist in multiple copies: a new copy is created upon retrieval from the container (or upon injection into another bean).
- **Request**. Similar to `Prototype`, however it has a few differences and features (since its lifecycle is bound to a web request):
- Can't be injected to other beans.
- Can't be manually retrieved from the Container.
- `Request` beans are automatically injected to the `context.Context` of a corresponding `http.Request`.
- If a `Request` bean implements `io.Closer`, it will be "closed" upon corresponding request's cancellation.
### Beans registration
For the container to become aware of the beans, one must register them manually (unlike Java, unfortunately, we can't scan classpath to do it automatically, because Go runtime doesn't contain high-level information about types). How can one register beans in the container?
- **By type**. This is described in the example above. A structure is declared with a field tagged with `di.scope:""`. This field can be even omitted - in this case, the default scope will be `Singleton`. Then the registration is done like this:
```go
di.RegisterBean("beanID", reflect.TypeOf((*YourAwesomeStructure)(nil)))
```
- **Using pre-created instance**. What if you already have an instance that you want to register as a bean? You can do it like this:
```go
di.RegisterBeanInstance("beanID", yourAwesomeInstance)
```
For this type of beans, the only supported scope is `Singleton`, because I don't dare to clone your instances to enable prototyping 😅
- **Via bean factory**. If you have a method that is producing instances for you, you can register it as a bean factory:
```go
di.RegisterBeanFactory("beanID", Singleton, func(context.Context) (interface{}, error) {
return "My awesome string that is going to become a bean!", nil
})
```
Feel free to use any scope with this method. By the way, you can even lookup other beans within the factory:
```go
di.RegisterBeanFactory("beanID", Prototype, func(context.Context) (interface{}, error) {
return di.GetInstance("someOtherBeanID"), nil
})
```
Note that factory-method accepts `context.Context`. It can be useful for request-scoped beans (the HTTP request context is set in this case). For all other beans it will be `context.Background()`.
### Beans initialization
There's a special interface `InitializingBean` that can be implemented to provide your bean with some initialization logic that will be executed after the container is initialized (for `Singleton` beans) or after the `Prototype`/`Request` instance is created. Again, you can also lookup other beans during initialization (since the container is ready by that time):
```go
type PostConstructBean1 struct {
Value string
}
func (pcb *PostConstructBean1) PostConstruct() error {
pcb.Value = "some content"
return nil
}
type PostConstructBean2 struct {
Scope Scope `di.scope:"prototype"`
PostConstructBean1 *PostConstructBean1
}
func (pcb *PostConstructBean2) PostConstruct() error {
instance, err := di.GetInstanceSafe("postConstructBean1")
if err != nil {
return err
}
pcb.PostConstructBean1 = instance.(*PostConstructBean1)
return nil
}
```
### Beans post-processors
The alternative way of initializing beans is using so-called "beans post-processors". Take a look at the example:
```go
type postprocessedBean struct {
a string
b string
}
_, _ := RegisterBean("postprocessedBean", reflect.TypeOf((*postprocessedBean)(nil)))
_ = RegisterBeanPostprocessor(reflect.TypeOf((*postprocessedBean)(nil)), func(instance interface{}) error {
instance.(*postprocessedBean).a = "Hello, "
return nil
})
_ = RegisterBeanPostprocessor(reflect.TypeOf((*postprocessedBean)(nil)), func(instance interface{}) error {
instance.(*postprocessedBean).b = "world!"
return nil
})
_ = InitializeContainer()
instance := GetInstance("postprocessedBean")
postprocessedBean := instance.(*postprocessedBean)
println(postprocessedBean.a+postprocessedBean.b) // prints out "Hello, world!"
```
### Beans injection
As was mentioned above, one bean can be injected into another with the `PostConstruct` method. However, the more handy way of doing it is by using a special tag:
```go
type SingletonBean struct {
SomeOtherBean *SomeOtherBean `di.inject:"someOtherBean"`
}
```
... or via interface ...
```go
type SingletonBean struct {
SomeOtherBean SomeOtherBeansInterface `di.inject:"someOtherBean"`
}
```
Note that you can refer dependencies either by pointer, or by interface, but not by value. And just a reminder: you can't inject `Request` beans.
Sometimes we might want to have optional dependencies. By default, all declared dependencies are considered to be required: if some dependency is not found in the Container, you will get an error. However, you can specify an optional dependency like this:
```go
type SingletonBean struct {
SomeOtherBean *string `di.inject:"someOtherBean" di.optional:"true"`
}
```
In this case, if `someOtherBean` is not found in the Container, you will get `nil` injected into this field.
In fact, you don't need a bean ID to preform an injection! Check this out:
```go
type SingletonBean struct {
SomeOtherBean *string `di.inject:""`
}
```
In this case, DI will try to find a candidate for the injection automatically (among registered beans of type `*string`). Cool, ain't it? ðŸ¤
It will panic though if no candidates are found (and if the dependency is not marked as optional), or if there is more than one candidate found.
Finally, you can inject beans to slices and maps. It works similarly to the ID-less inections above, but injects all candidates that were found:
```go
type SingletonBean struct {
someOtherBeans []*string `di.inject:""`
}
```
```go
type SingletonBean struct {
someOtherBeans map[string]*string `di.inject:""`
}
```
### Circular dependencies
The problem with all IoC containers is that beans' interconnection may suffer from so-called circular dependencies. Consider this example:
```go
type CircularBean struct {
Scope Scope `di.scope:"prototype"`
CircularBean *CircularBean `di.inject:"circularBean"`
}
```
Trying to use such bean will result in the `circular dependency detected for bean: circularBean` error. There's no problem as such with referencing a bean from itself - if it's a `Singleton` bean. But doing it with `Prototype`/`Request` beans will lead to infinite creation of the instances. So, be careful with this: "with great power comes great responsibility" 🕸
## What about middleware?
We have some 😎 Here's an example with [gorilla/mux](https://github.com/gorilla/mux) router (but feel free to use any other router).
Basically, it's an extension of the very first example with the weather controller, but this time we add `Request` beans and access them via request's context.
Also, this example demonstrates how DI can automatically close resources for you (DB connection in this case). The proper error handling is, again, omitted for simplicity.
**controllers/weather_controller.go**
```go
package controllers
import (
"database/sql"
"di-demo/services"
"github.com/goioc/di"
"net/http"
)
type WeatherController struct {
// note that injection works even with unexported fields
weatherService *services.WeatherService `di.inject:"weatherService"`
}
func (wc *WeatherController) Weather(w http.ResponseWriter, r *http.Request) {
dbConnection := r.Context().Value(di.BeanKey("dbConnection")).(*sql.Conn)
city := r.URL.Query().Get("city")
_, _ = dbConnection.ExecContext(r.Context(), "insert into log values (?, ?, datetime('now'))", city, r.RemoteAddr)
weather, _ := wc.weatherService.Weather(city)
_, _ = w.Write([]byte(*weather))
}
```
**controllers/index_controller.go**
```go
package controllers
import (
"database/sql"
"fmt"
"github.com/goioc/di"
"net/http"
"strings"
"time"
)
type IndexController struct {
}
func (ic *IndexController) Log(w http.ResponseWriter, r *http.Request) {
dbConnection := r.Context().Value(di.BeanKey("dbConnection")).(*sql.Conn)
rows, _ := dbConnection.QueryContext(r.Context(), "select * from log")
columns, _ := rows.Columns()
_, _ = w.Write([]byte(strings.ToUpper(fmt.Sprintf("Requests log: %v\n\n", columns))))
for rows.Next() {
var city string
var ip string
var dateTime time.Time
_ = rows.Scan(&city, &ip, &dateTime)
_, _ = w.Write([]byte(fmt.Sprintln(city, "\t", ip, "\t", dateTime)))
}
}
```
**init.go**
```go
package main
import (
"context"
"database/sql"
"di-demo/controllers"
"di-demo/services"
"github.com/goioc/di"
"os"
"reflect"
)
func init() {
_, _ = di.RegisterBean("weatherService", reflect.TypeOf((*services.WeatherService)(nil)))
_, _ = di.RegisterBean("indexController", reflect.TypeOf((*controllers.IndexController)(nil)))
_, _ = di.RegisterBean("weatherController", reflect.TypeOf((*controllers.WeatherController)(nil)))
_, _ = di.RegisterBeanFactory("db", di.Singleton, func(context.Context) (interface{}, error) {
_ = os.Remove("./di-demo.db")
db, _ := sql.Open("sqlite3", "./di-demo.db")
db.SetMaxOpenConns(1)
_, _ = db.Exec("create table log ('city' varchar not null, 'ip' varchar not null, 'time' datetime not null)")
return db, nil
})
_, _ = di.RegisterBeanFactory("dbConnection", di.Request, func(ctx context.Context) (interface{}, error) {
db, _ := di.GetInstanceSafe("db")
return db.(*sql.DB).Conn(ctx)
})
_ = di.InitializeContainer()
}
```
**main.go**
```go
package main
import (
"di-demo/controllers"
"github.com/goioc/di"
"github.com/gorilla/mux"
_ "github.com/mattn/go-sqlite3"
"net/http"
)
func main() {
router := mux.NewRouter()
router.Use(di.Middleware)
router.Path("/").HandlerFunc(di.GetInstance("indexController").(*controllers.IndexController).Log)
router.Path("/weather").Queries("city", "{*?}").HandlerFunc(di.GetInstance("weatherController").(*controllers.WeatherController).Weather)
_ = http.ListenAndServe(":8080", router)
}
```
## Okaaay... More examples?
Please, take a look at the [unit-tests](https://github.com/goioc/di/blob/master/di_test.go) for more examples.