Get Started
Installing godi
Requirements
Installation
Using Go Modules (Recommended)
Import in Your Code
Verify Installation
Version Management
Check Current Version
Update to Latest
Use Specific Version
Development Setup
Editor Support
Next Steps
Quick Start: From Simple to Advanced
Level 1: Just the Basics (5 minutes)
Level 2: Add Scopes for Web Apps (10 minutes)
Level 3: Add Interfaces for Testing (15 minutes)
Level 4: Organize with Modules (20 minutes)
Level 5: Advanced Patterns (as needed)
Keyed Services (Multiple Implementations)
Service Groups (Collections)
Decorators (Wrap Services)
Decision Tree: What Do I Need?
Common Progression Path
Key Principle: Start Simple
Summary
Getting Started with godi
Why Use Dependency Injection?
Your First App: A Simple API
Step 1: Define Your Services
Step 2: Wire Everything with godi
Understanding Service Lifetimes
Singleton - Shared Across Everything
Scoped - One Per Request/Operation
Transient - New Every Time
Real Example: Why Scoped Services Matter
Next Steps
Key Takeaways
Why Use Dependency Injection?
The Problem: A Real Example
The Cascade of Changes
The DI Solution
Real-World Benefits
1. Testing Becomes Trivial
2. Request Isolation in Web Apps
3. Clean Architectural Boundaries
4. Resource Management
Common Concerns Addressed
“But I like Go’s simplicity!”
“I don’t want a framework!”
“It’s overkill for small apps!”
The Real Magic: Examples
Adding Multi-Tenancy
Adding Request Tracing
Switching Databases
When You Really Need DI
Summary: The 80/20 of DI
Learn
Core Concepts
Services: Your Application Building Blocks
Constructors: How Services Are Created
The Container: Where Everything Comes Together
1. ServiceCollection - The Recipe Book
2. ServiceProvider - The Kitchen
Service Lifetimes: When Things Are Created
Singleton - One for the Whole App
Scoped - One per “Operation”
Transient - New Every Time
Scopes: Isolation for Operations
Real Example: Putting It All Together
The Magic of Dependency Injection
Quick Reference
Next Steps
AddScoped vs Modules: When to Use What
Start Simple: Direct Registration
When You Need Modules
Example: Your App Grows
The Module Solution
Real-World Module Examples
Module Example 1: Feature Modules
Module Example 2: Environment-Specific Modules
Module Example 3: Shared Libraries
Module Best Practices
1. One Module Per Package
2. Module Dependencies
3. Keep Modules Focused
Decision Guide
Use Direct Registration When:
Use Modules When:
Mix Both!
Summary
Building a Web Application with godi
Prerequisites
Project Setup
Project Structure
Step 1: Define Models and Interfaces
Step 2: Create Configuration
Step 3: Implement Repositories
Step 4: Implement Services
Step 5: Create HTTP Handlers
Step 6: Wire Everything with godi
Step 7: Test the API
Key Takeaways
Next Steps
Testing with godi
Why DI Makes Testing Better
Setting Up
Step 1: Create Test Utilities
Step 2: Create Mocks
Step 3: Unit Testing Services
Step 4: Integration Testing
Step 5: Testing Scoped Services
Step 6: Testing Best Practices
Step 7: Benchmark Tests
Testing Strategies
1. Unit Testing with Mocks
2. Integration Testing
3. End-to-End Testing
4. Test Organization
Key Testing Benefits with godi
1. Easy Mock Injection
2. Isolated Test Environments
3. Parallel Testing
4. Test-Specific Configuration
Common Testing Patterns
Factory Pattern for Test Data
Test Fixtures
Cleanup Helpers
Summary
Next Steps
How-to Guides
Registering Services
Basic Registration
AddSingleton
AddScoped
AddTransient
Constructor Patterns
Simple Constructor
Constructor with Error
Interface Registration
Keyed Services
Service Groups
Instance Registration
Conditional Registration
Generic Services
Registration Options
Service Replacement
Remove Services
Factory Pattern
Best Practices
1. Register by Interface
2. Use Appropriate Lifetimes
3. Validate Early
4. Document Dependencies
Common Patterns
Options Pattern
Multi-Stage Initialization
Next Steps
Understanding Scoped Services
What Are Scoped Services?
Real Example 1: Database Transactions
Real Example 2: Request Context & User Info
Real Example 3: Multi-Tenant Applications
Real Example 4: Performance Monitoring
When to Use Each Lifetime
Use Singleton When:
Use Scoped When:
Use Transient When:
Common Patterns
Pattern 1: Request Pipeline
Pattern 2: Shared State in Scope
Pattern 3: Scope Hierarchies
Summary
Keyed Services
When to Use Keyed Services
Basic Registration
Resolving Keyed Services
Database Example
Notification Channels
Payment Gateways
Environment-Based Services
Feature Flags
Storage Backends
Injecting Keyed Services
Dynamic Key Resolution
Testing with Keyed Services
Best Practices
1. Use Constants for Keys
2. Document Available Keys
3. Provide Fallbacks
4. Validate at Startup
Summary
Service Groups
Basic Concept
HTTP Handler Example
Middleware Chain
Event Handlers
Validation Rules
Plugin System
Observers and Listeners
Conditional Registration
Testing with Groups
Best Practices
1. Use Meaningful Group Names
2. Document Group Members
3. Handle Empty Groups
4. Order Matters Sometimes
Summary
Modules
What are Modules?
Creating a Module
Basic Module
Module with Dependencies
Using Modules
Single Module
Multiple Modules
Module Patterns
Layered Architecture
Feature Modules
Environment-Specific Modules
Advanced Module Techniques
Module with Configuration
Conditional Registration in Modules
Module Composition
Testing with Modules
Test Module
Module Override Pattern
Module Organization
Directory Structure
Module File Example
Best Practices
1. Single Responsibility
2. Clear Dependencies
3. Avoid Circular Dependencies
4. Document Module Purpose
5. Test Modules Independently
Module Patterns for Common Scenarios
Web Application Module
Background Jobs Module
Plugin System Module
Summary
Decorators
What are Decorators?
Basic Decorator
Simple Logging Decorator
Registering Decorators
Common Decorator Patterns
Caching Decorator
Metrics Decorator
Retry Decorator
Validation Decorator
Chaining Decorators
Advanced Decorator Patterns
Conditional Decorator
Context-Aware Decorator
Generic Decorator
Circuit Breaker Decorator
Testing Decorators
Unit Testing Decorators
Integration Testing
Best Practices
1. Keep Decorators Focused
2. Maintain Interface Compatibility
3. Make Decorators Optional
4. Document Decorator Order
5. Consider Performance
Common Use Cases
1. Cross-Cutting Concerns
2. Security
3. Resilience
4. Performance
5. Business Logic
Summary
Parameter Objects
Understanding Parameter Objects
Input Parameter Objects (In)
Basic Usage
Optional Dependencies
Named Dependencies
Groups in Parameters
Output Result Objects (Out)
Basic Usage
Named Results
Group Results
Advanced Patterns
Nested Parameter Objects
Combining In and Out
Factory Pattern with Parameters
Best Practices
1. When to Use Parameter Objects
2. Naming Conventions
3. Field Documentation
4. Validation
5. Avoid Overuse
Testing with Parameter Objects
Mock Specific Fields
Test Helpers
Common Patterns
Configuration Parameters
Multi-Database Parameters
Plugin Parameters
Summary
Service Disposal
Disposable Interface
Basic Disposal
Simple Disposable Service
Context-Aware Disposal
Disposal Order
Lifetime-Based Disposal
Singleton Disposal
Scoped Disposal
Transient Disposal
Disposal Patterns
Resource Pool
Composite Disposal
Graceful Shutdown
Error Handling
Multiple Disposal Errors
Panic Recovery
Testing Disposal
Verify Disposal
Test Disposal Order
Best Practices
1. Always Implement Disposal for Resources
2. Use Defer for Scopes
3. Handle Disposal Errors
4. Make Disposal Idempotent
5. Document Disposal Behavior
Summary
Advanced Patterns
Factory Pattern
Service Factory
Abstract Factory
Strategy Pattern
Dynamic Strategy Selection
Chain of Responsibility
Middleware Chain
Lazy Initialization
Lazy Service Resolution
Service Locator (Anti-)Pattern
Composite Pattern
Composite Services
Proxy Pattern
Service Proxy
Observer Pattern
Event System
Command Pattern
Command Execution
Unit of Work Pattern
Transaction Management
Specification Pattern
Dynamic Queries
Summary
Reference
API Reference
Core Types
ServiceCollection
Creating a ServiceCollection
ServiceProvider
Scope
ServiceLifetime
Registration Functions
Basic Registration
Keyed Registration
Group Registration
Interface Registration
Resolution Functions
Generic Resolution Helpers
Direct Resolution
Dependency Injection
Constructor Injection
Parameter Objects (In)
Result Objects (Out)
Modules
Service Provider Options
Decorators
Disposal
Disposable Interface
Error Handling
Error Types
Common Errors
Invoke Function
Default Provider
Complete Example
Service Lifetimes Reference
Overview
Singleton Services
Characteristics
When to Use
Example
Implementation Details
Scoped Services
Characteristics
When to Use
Example
Scope Hierarchy
Transient Services
Characteristics
When to Use
Example
Factory Pattern
Lifetime Compatibility
Dependency Rules
Captive Dependencies
Disposal Order
Best Practices
Choose the Right Lifetime
Avoid Common Pitfalls
Testing Considerations
Performance Implications
Optimization Tips
Summary
Error Handling Reference
Error Categories
Common Error Values
Service Resolution Errors
Lifecycle Errors
Constructor Errors
Typed Errors
ResolutionError
CircularDependencyError
LifetimeConflictError
TimeoutError
Error Checking Functions
IsNotFound
IsCircularDependency
IsDisposed
IsTimeout
Error Handling Patterns
Basic Error Handling
Registration Error Handling
Build Error Handling
Graceful Degradation
Custom Error Types
Creating Custom Errors
Wrapping Errors
Error Recovery
Panic Recovery
Validation Options
Testing Error Scenarios
Testing Not Found Errors
Testing Circular Dependencies
Testing Disposal Errors
Best Practices
1. Always Check Errors
2. Use Error Context
3. Handle Specific Errors
4. Fail Fast on Configuration
Summary
Configuration Options Reference
ServiceProviderOptions
ValidateOnBuild
OnServiceResolved
OnServiceError
ResolutionTimeout
DryRun
RecoverFromPanics
DeferAcyclicVerification
Provide Options
Name Option
Group Option
As Option
Callback Options
Decorate Options
Complete Example
Option Patterns
Development vs Production
Testing Configuration
Monitoring Configuration
Best Practices
1.3.1 (2025-07-16)
Bug Fixes
1.3.0 (2025-07-16)
Features
1.2.2 (2025-07-16)
1.2.1 (2025-07-15)
1.2.0 (2025-07-14)
Conceptual Guides
Architecture Guide
How godi Works
Core Components
Lifetime Management
Resolution Process
Application Architecture Patterns
Clean Architecture
Hexagonal Architecture (Ports and Adapters)
Vertical Slice Architecture
Service Organization Patterns
Service Layers
Service Boundaries
Dependency Management
Dependency Direction
Avoiding Circular Dependencies
Testing Architecture
Test Pyramid with DI
Test Organization
Performance Considerations
Service Resolution Performance
Scope Management
Scalability Patterns
Modular Monolith
Microservices Ready
Best Practices Summary
Conclusion
Best Practices
Service Design
Use Interfaces
Constructor Injection
Single Responsibility
Lifetime Management
Choose the Right Lifetime
Avoid Captive Dependencies
Scope Management
Always Close Scopes
One Scope Per Operation
Error Handling
Check Resolution Errors
Constructor Validation
Testing
Use Test Containers
Test Helpers
Module Organization
Group Related Services
Module Dependencies
Performance
Cache Service Resolution
Avoid Over-Injection
Common Pitfalls
1. Circular Dependencies
2. Service Locator Anti-Pattern
3. Leaking Abstractions
Summary Checklist
Migration Guide
Migrating from Manual Dependency Management
Before: Manual Wiring
After: With godi
Migration Steps
Migrating from Google Wire
Wire Approach
godi Approach
Key Differences
Migration Steps
Migrating from Uber Fx
Fx Approach
godi Approach
Key Differences
Migration Steps
Migrating from Microsoft.Extensions.DependencyInjection
.NET Approach
godi Approach (Very Similar!)
Familiar Concepts
Migration Steps
Migrating from Spring/Java DI
Spring Approach
godi Approach
Key Differences
Common Migration Patterns
1. Converting Singletons
2. Converting Factory Functions
3. Converting Init Functions
Testing Migration
Before: Complex Setup
After: Clean DI
Migration Checklist
Benefits After Migration
Getting Help
Performance Guide
Performance Overview
Performance Characteristics
Resolution Performance
Singleton Services
Scoped Services
Transient Services
Optimization Techniques
1. Cache Service Resolution
2. Minimize Transient Usage
3. Optimize Scope Usage
4. Lazy Resolution
Benchmarking
Basic Benchmark
Concurrent Benchmark
Memory Optimization
1. Dispose Scopes Promptly
2. Avoid Service Leaks
3. Pool Expensive Objects
Provider Options for Performance
Validation Timing
Resolution Monitoring
Common Performance Pitfalls
1. Excessive Transient Usage
2. Deep Dependency Chains
3. Scope Explosion
Performance Best Practices
1. Profile Before Optimizing
2. Measure Resolution Times
3. Use Appropriate Lifetimes
4. Batch Operations
Optimization Checklist
Conclusion
Troubleshooting Guide
Common Issues
Service Not Found
Circular Dependencies
Disposed Provider/Scope
Lifetime Conflicts
Missing Dependencies
Constructor Errors
Debugging Techniques
1. Enable Validation
2. Add Resolution Logging
3. Check Service Registration
4. Trace Dependency Chain
Performance Issues
Slow Resolution
Memory Leaks
Testing Issues
Mocks Not Being Used
Test Isolation
Error Patterns
Check Error Types
Wrap Errors with Context
Prevention Strategies
1. Consistent Registration Pattern
2. Validate Early
3. Document Dependencies
Getting Help
Quick Reference
Comparison with Other DI Solutions
Comparison Table
Detailed Comparisons
godi vs wire (Google)
godi vs fx (Uber)
godi vs dig (Uber)
godi vs Manual DI
Feature-by-Feature Comparison
Service Lifetimes
Developer Experience
Testing Support
Use Cases
Code Examples Side-by-Side
Basic Setup
With Dependencies
Testing
Decision Matrix
Migration Effort
Conclusion
Quick Links
GitHub
pkg.go.dev
Go Report Card
Community
Discussions
Issues
godi
Index
Edit on GitHub
Index