go-kid-ioc

go-kid/ioc

English | 中文

go-kid/ioc is a Go runtime dependency injection (IoC/DI) framework based on tag + interface.

✨ Features

• Component Dependency Injection (wire tag)
  • Inject by pointer type, interface type, or component name
  • Multiple implementation selection strategies (Primary/Qualifier)
  • Inject into interface slices/arrays
• Configuration Injection (value / prop / prefix tags)
  • Multiple configuration sources (command-line args, files, raw content)
  • Configuration placeholders ${...}
  • Expression evaluation #{...} (arithmetic, logical, conditional, collection operations)
• Constructor Injection: Function-based dependency injection (built-in)
• Lifecycle Management: ApplicationRunner, CloserComponent, LazyInitComponent
• context.Context lifecycle support: WithContext variants for all lifecycle interfaces
• Scope mechanism: Singleton/Prototype
• Conditional component registration: Register components based on runtime conditions
• Application event mechanism: Publish and listen for application events
• Type-safe generic registration: ioc.Provide[T] validates return type at registration time
• log/slog adapter support: Integrate with Go's structured logging

📦 Installation

Requires Go 1.21+.

go get github.com/go-kid/ioc

🚀 Quick Start

package main

import (
	"fmt"
	"github.com/go-kid/ioc"
)

// Component to be injected
type ComponentA struct {
	Name string
}

func (a *ComponentA) GetName() string {
	return a.Name
}

// Target struct that depends on ComponentA
type App struct {
	ComponentA *ComponentA `wire:""` // pointer + exported field + wire tag
}

func main() {
	a := new(App)

	// Register components
	ioc.Register(a)
	ioc.Register(&ComponentA{Name: "Comp-A"})

	// Run the framework
	_, err := ioc.Run()
	if err != nil {
		panic(err)
	}

	// Output: "Comp-A"
	fmt.Println(a.ComponentA.GetName())
}

Key points: Dependency fields must be exported (start with uppercase) and use wire:"" to declare injection.

📖 Documentation

1. Component Dependency Injection (wire tag)

Component injection is controlled via tag: wire:"<name>,arg1=xxx,arg2=yyy"

• <name>: optional, inject by component name
• ,arg=...: optional extra arguments (e.g., qualifier)
• wire:"" (empty) means inject by type

Inject by Pointer Type

type Component struct {
	Name string
}

type App struct {
	C *Component `wire:""` // injected by *Component type
}

Inject by Interface Type

type IComponent interface {
	GetName() string
}

type ComponentA struct{ Name string }
func (a *ComponentA) GetName() string { return a.Name }

type App struct {
	C IComponent `wire:""` // inject by interface type
}

Inject by Name

Implement NamingComponent interface to define component names:

type ComponentA struct {
	Name          string
	componentName string
}

func (a *ComponentA) Naming() string { return a.componentName }

type App struct {
	ByName IComponent `wire:"comp-A"` // inject by component name
}

Multiple Implementation Selection Strategy

When an interface has multiple implementations, the container selects by priority:

1. Components implementing WirePrimary interface (primary)
2. Components without alias (not implementing Naming())
3. One will be chosen (order not guaranteed)

Using Primary marker:

type ComponentA struct {
	Name string
	definition.WirePrimaryComponent // embed Primary component
}

Using Qualifier:

type ComponentA struct {
	qualifier string
}

func (a *ComponentA) Qualifier() string { return a.qualifier }

type App struct {
	C IComponent `wire:",qualifier=comp-A"` // use qualifier
}

Inject into Slice/Array

type App struct {
	All []Interface `wire:""` // all Interface implementations
}

2. Configuration Injection

prefix: Bind Config Prefix

type configA struct {
	B int   `yaml:"b"`
	C []int `yaml:"c"`
}

type App struct {
	A *configA `prefix:"a"` // bind config prefix "a"
}

Configuration (YAML):

a:
  b: 123
  c: [1,2,3,4]

value: Literals / Placeholders / Expressions

type T struct {
	DSN string `value:"${db.dsn}"`           // config placeholder
	Sum int    `value:"#{1+2}"`               // expression
	Str string `value:"foo"`                  // literal
}

prop: Sugar for value

type DBConfig struct {
	DSN string `prop:"db.dsn"` // equivalent to value:"${db.dsn}"
}

Placeholders and Expressions

• ${...}: Configuration placeholder, reads value from config
• #{...}: Expression evaluation, supports arithmetic, logical, conditional, collection operations

Example: