Get Started
Installing godi
Requirements
Install
Verify Installation
VS Code Setup (Recommended)
What’s Next?
Troubleshooting
“Module not found”
“Cannot find package”
IDE not recognizing godi
Quick Start - Learn godi in 5 Minutes
Install
Level 1: Basic DI (Start Here!)
Level 2: Multiple Services
Level 3: Web Apps with Scopes
Level 4: Testing with Mocks
Level 5: Module Organization
Common Patterns
Pattern 1: Configuration
Pattern 2: Interfaces for Flexibility
Pattern 3: Groups of Services
Cheat Sheet
What’s Next?
Getting Started with godi
Why Dependency Injection?
Installation
Your First App: User API
Step 1: Define Your Services
Step 2: Create Modules
Step 3: Wire Everything in main.go
Step 4: Run Your App
What Just Happened?
Adding Features is Easy
Testing is a Breeze
Key Concepts
1. Services
2. Modules
3. Lifetimes
4. Scopes
Next Steps
Tips for Success
Why Dependency Injection?
The Problem You’re Having Right Now
Problem #1: The Constructor Cascade
Problem #2: Testing Nightmare
Problem #3: Request Isolation
Problem #4: Environment Differences
The Real Magic: Examples
Adding Multi-Tenancy
Adding Request Tracing
Switching Databases
Common Concerns Addressed
“But I like Go’s simplicity!”
“I don’t want a framework!”
“It’s overkill for small apps!”
When You Need DI
The Bottom Line
Learn
Core Concepts
1. Services
2. Constructors
3. Modules
4. Lifetimes
Singleton (One Forever)
Scoped (One Per Request)
5. Scopes
Quick Reference
Visual: How It All Works
Common Patterns
Pattern 1: Shared Database, Scoped Transaction
Pattern 2: Request Context
Pattern 3: Module Composition
Next Steps
Simple Registration vs Modules
The Evolution of Your Code
Day 1: Simple Registration
Week 2: Growing Pains
The Module Solution
Why Always Use Modules?
1. Organization
2. Dependencies Are Clear
3. Testing Is Easier
4. Reusability
5. Environment Switching
Module Best Practices
Start with Modules from Day 1
One Module Per Feature/Layer
Module Naming
Migration Path
Step 1: Group by Purpose
Step 2: Extract to Files
Summary
Building a Web Application with godi
What We’re Building
Setup
Project Structure
Step 1: Define Models
Step 2: Core Services
Step 3: HTTP Handlers
Step 4: Modules
Step 5: Wire Everything Together
Step 6: Test Your API
Key Patterns
1. Request Scoping
2. Module Organization
3. Clean Architecture
Testing Your Web App
Next Steps
Testing with godi
Why DI Makes Testing Amazing
Quick Example
Step-by-Step Guide
Step 1: Define Interfaces
Step 2: Create Mock Implementations
Step 3: Create Test Modules
Step 4: Write Your Tests
Advanced Testing Patterns
Table-Driven Tests with DI
Testing with Scopes
Spy Pattern for Behavior Verification
Testing Best Practices
1. Use Test Helpers
2. Test Module Variants
3. Integration Test Support
Summary
How-to Guides
Using Scopes
What are Scopes?
Basic Usage
Creating and Using Scopes
Real-World Example: Web API
Module Setup
HTTP Handler
Automatic Disposal
Disposal Example
Disposal Order
Context-Aware Disposal
Scope Isolation
Advanced Patterns
Middleware with Scopes
Unit of Work Pattern
Best Practices
1. Always Close Scopes
2. One Scope Per Request
3. Pass Context Through Scopes
4. Implement Disposal for Resources
Common Use Cases
1. Database Transactions
2. Request Logging
3. User Context
4. Resource Cleanup
5. Metrics Collection
Summary
Keyed Services
When to Use Keyed Services
Basic Example
Real-World Example: Multiple Databases
Using Parameter Objects
Environment-Based Selection
Feature Flags Pattern
Testing with Keyed Services
Best Practices
1. Use Clear, Descriptive Keys
2. Document Available Keys
3. Provide Defaults When Possible
4. Consider Using Enums for Keys
When NOT to Use Keyed Services
Summary
Service Groups
Basic Example
Real-World Example: HTTP Middleware
Plugin System Example
Event System Example
Combining Groups with Keys
Best Practices
1. Order Matters
2. Document Group Members
3. Empty Groups are OK
4. Type Safety
When to Use Groups
Summary
How to Use Modules
Basic Module
Module Dependencies
Real-World Examples
Example 1: Web API Module Structure
Example 2: Environment-Specific Modules
Example 3: Plugin System with Modules
Advanced Patterns
Dynamic Module Configuration
Conditional Module Registration
Testing with Module Overrides
Best Practices
1. One Module Per Package
2. Clear Module Dependencies
3. Module Naming Conventions
4. Document Module Purpose
Common Patterns
Feature Toggle Module
Multi-Tenant Module
Summary
Decorators
Basic Example
Common Decorators
Caching Decorator
Metrics Decorator
Retry Decorator
Chaining Decorators
When to Use Decorators
Best Practices
Testing with Decorators
Parameter Objects
Input Parameters (In)
Basic Example
Optional Dependencies
Named Dependencies
Groups
Output Parameters (Out)
Basic Example
Named Outputs
Groups in Output
Real-World Example
Best Practices
When to Use
Advanced Patterns
Factory Pattern
Strategy Pattern
Chain of Responsibility
Unit of Work Pattern
Lazy Loading Pattern
Circuit Breaker Pattern
When to Use These Patterns
Remember
Reference
API Reference
Core Types
ServiceCollection
ServiceProvider
Scope
Modules
Registration Options
Lifetime Options
Decorators
Parameter Objects
Input Parameters (In)
Output Parameters (Out)
Disposal Interfaces
Provider Options
Service Lifetimes
Error Types
Generic Helpers
Complete Example
Error Reference
Common Errors
ServiceNotFoundError
CircularDependencyError
ScopeDisposedError
LifetimeConflictError
ConstructorError
Error Checking Helpers
Quick Diagnosis
Service Provider Options
Basic Usage
Available Options
ValidateOnBuild
OnServiceResolved
OnServiceError
ResolutionTimeout
Complete Example
Development vs Production
Development Options
Production Options
Best Practices
Quick Reference
Changelog
2.0.4 (2025-07-22)
Bug Fixes
2.0.3 (2025-07-22)
Bug Fixes
2.0.2 (2025-07-21)
Bug Fixes
2.0.1 (2025-07-21)
Bug Fixes
2.0.0 (2025-07-21)
⚠ BREAKING CHANGES
Features
1.6.2 (2025-07-17)
Bug Fixes
1.6.1 (2025-07-17)
Bug Fixes
1.6.0 (2025-07-17)
Features
1.5.1 (2025-07-17)
Bug Fixes
1.5.0 (2025-07-17)
Features
1.4.0 (2025-07-17)
Features
1.3.3 (2025-07-16)
Bug Fixes
1.3.2 (2025-07-16)
Bug Fixes
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)
1.1.0 (2025-07-14)
⚠ BREAKING CHANGES
Features
1.0.2 (2025-07-13)
1.0.1 (2025-07-12)
1.0.0 (2025-07-11)
Conceptual Guides
Best Practices
Use Modules from the Start
Design for Interfaces
Choose the Right Lifetime
Singleton - Shared Forever
Scoped - Per Request/Operation
Common Mistake: Captive Dependencies
Always Close Scopes
Error Handling
Module Organization
Testing Best Practices
Create Test Modules
Use Helper Functions
Common Anti-Patterns to Avoid
1. Service Locator Pattern
2. Over-Injection
Performance Tips
Summary Checklist
Troubleshooting & Performance
Common Issues
1. “Service Not Found” Error
2. “Circular Dependency” Error
3. “Scope Already Disposed” Error
4. “Captive Dependency” (Singleton using Scoped)
Performance Issues
Slow Startup
Comparing godi to Other DI Solutions
godi vs Manual Dependency Injection
godi vs wire (Google)
godi vs fx (Uber)
Quick Decision Guide
Feature Comparison
For .NET Developers
Summary
Quick Links
GitHub
pkg.go.dev
Go Report Card
Community
Discussions
Issues
godi
Index
Edit on GitHub
Index