samber/cc-skills-golang / skills/golang-samber-do
golang-samber-do
VerifiedDependency injection in Golang using samber/do — service containers, lifecycle management, scopes, health checks, graceful shutdown, and module organization. Apply when using or adopting samber/do, when the codebase imports github.com/samber/do or github.com/samber/do/v2, or when refactoring manual constructor injection into a DI container.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.1 KB |
| evals/evals.json | config | 11.6 KB |
| references/advanced.md | markdown | 5.7 KB |
| references/testing.md | markdown | 1.4 KB |
references/advanced.md
View on GitHub# Advanced Usage
## Table of Contents
- [Scopes (Module Tree)](#scopes-module-tree)
- [Explicit Service Aliasing](#explicit-service-aliasing)
- [Struct Injection](#struct-injection)
- [Lifecycle Management](#lifecycle-management)
- [Health Checks](#health-checks)
- [Graceful Shutdown](#graceful-shutdown)
- [Debugging](#debugging)
- [List Services](#list-services)
- [Explain Injector](#explain-injector)
- [Migration from Manual DI](#migration-from-manual-di)
- [Quick Reference](#quick-reference)
- [Aliasing](#aliasing)
- [Lifecycle & Health](#lifecycle--health)
- [Container Management](#container-management)
- [Debugging](#debugging-1)
## Scopes (Module Tree)
Scopes SHOULD be used to organize services by module:
```go
root := do.New()
// Register shared services in root
do.Provide(root, func(i do.Injector) (Database, error) {
return &Database{}, nil
})
// Create child scope
apiScope := root.Scope("api")
// Services in apiScope can access root services
do.Provide(apiScope, func(i do.Injector) (UserService, error) {
db := do.MustInvoke[Database](i) // from root
return &userService{db: db}, nil
})
// Child scopes are isolated from each other
userScope := root.Scope("user")
```
Organize services by lifecycle and visibility:
```go
root := do.New()
// Global/stateless services in root
do.Provide(root, NewConfig)
do.Provide(root, NewLogger)
// Request-scoped services
requestScope := root.Scope("request")
do.Provide(requestScope, NewRequestContext)
```
## Explicit Service Aliasing
For rare cases when you need to adapt to legacy code:
```go
do.Provide(injector, func(i do.Injector) (*PostgreSQLDatabase, error) {
return &PostgreSQLDatabase{}, nil
})
do.MustAs[*PostgreSQLDatabase, Database](injector)
// Now both work:
db1 := do.MustInvoke[*PostgreSQLDatabase](injector)
db2 := do.MustInvoke[Database](injector)
```
Prefer implicit aliasing with `InvokeAs()` in most cases.
## Struct Injection
Inject services directly into struct fields using tags:
```go
type App struct {
Database *Database `do:""`
Logger *Logger `do:"app-logger"`
Config *Config `do:""`
}
app := do.MustInvokeStruct[App](injector)
```
## Lifecycle Management
### Health Checks
Implement the `Healthchecker` interface:
```go
func (d *Database) HealthCheck() error {
return d.conn.Ping()
}
// With context support:
func (d *Database) HealthCheck(ctx context.Context) error {
return d.conn.PingContext(ctx)
}
// Check health
if err := do.HealthCheck[Database](injector); err != nil {
log.Printf("Database unhealthy: %v", err)
}
```
### Graceful Shutdown
Implement the `Shutdowner` interface (4 variants):
```go
// Simple
func (d *Database) Shutdown() { d.conn.Close() }
// With context
func (d *Database) Shutdown(ctx context.Context) { d.conn.Close() }
// With error
func (d *Database) Shutdown() error { return d.conn.Close() }
// With context + error (most flexible)
func (d *Database) Shutdown(ctx context.Context) error { return d.conn.Close() }
```
Shutdown with timeout:
```go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
report := injector.ShutdownWithContext(ctx)
```
## Debugging
### List Services
```go
services := injector.ListProvidedServices()
for _, svc := range services {
fmt.Printf("%s: %s\n", svc.ScopeName, svc.Service)
}
```
### Explain Injector
```go
explanation := do.ExplainInjector(injector)
fmt.Println(explanation.String())
```
## Migration from Manual DI
Before (manual):
```go
func main() {
config := &Config{Port: 8080}
db := NewDatabase(config)
userRepo := NewUserRepository(db)
userService := NewUserService(userRepo)
api := NewAPI(userService)
}
```
After (with do):
```go
func main() {
injector := do.New()
do.Provide(injector, func(i do.Injector) (*Config, error) {
return &Config{Port: 8080}, nil
})
do.Provide(injector, NewDatabase)
// ... register other services
api := do.MustInvoke[*API](injector)
}
```
## Quick Reference
### Aliasing
| Function | Purpose |
| ------------------------------ | ----------------------- |
| `do.As[Initial, Alias]()` | Create type alias |
| `do.AsNamed[Initial, Alias]()` | Create named type alias |
### Lifecycle & Health
| Function | Purpose |
| -------------------------------- | --------------------------- |
| `do.HealthCheck[T]()` | Check service health |
| `do.HealthCheckNamed()` | Check named service health |
| `do.HealthCheckWithContext[T]()` | Health check with timeout |
| `do.Shutdown[T]()` | Gracefully shutdown service |
| `do.ShutdownNamed()` | Shutdown named service |
| `do.ShutdownWithContext[T]()` | Shutdown with timeout |
| `do.MustShutdown[T]()` | Shutdown (panic on error) |
### Container Management
| Function | Purpose |
| ------------------ | ----------------------------- |
| `do.New()` | Create new root container |
| `do.NewWithOpts()` | Create container with options |
| `injector.Scope()` | Create child scope |
### Debugging
| Function | Purpose |
| --------------------------------- | ------------------------------------ |
| `do.ExplainInjector()` | Visualize scope tree and services |
| `do.ExplainService[T]()` | Get service details and dependencies |
| `do.NameOf[T]()` | Get service name (use sparingly) |
| `injector.ListProvidedServices()` | List all available services |
| `injector.ListInvokedServices()` | List invoked services only |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |