Skip to content

samber/cc-skills-golang / skills/golang-samber-do

golang-samber-do

Verified

Dependency 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.

FileKindSize
SKILL.mdskill md9.1 KB
evals/evals.jsonconfig11.6 KB
references/advanced.mdmarkdown5.7 KB
references/testing.mdmarkdown1.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           |
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 implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall