Skip to main content

​
ADR-002: Dependency Injection Framework

​
Context

The Tasteful framework needed a robust dependency injection system to:
  • Manage service lifecycles across flavors
  • Enable testability through easy mocking and overrides
  • Provide configuration management for different environments
  • Support complex dependency graphs between services
  • Maintain type safety where possible
The original Heka v2 had tight coupling issues because there was no clear dependency injection architecture, making testing difficult and maintenance expensive.

​
Decision

We chose the dependency-injector library as our IoC (Inversion of Control) container framework.

​
Key Features Utilized

  1. Declarative Containers: Clean definition of dependencies
  2. Provider Types: Factory, Singleton, Configuration providers
  3. Container Overriding: Easy testing and environment-specific configurations
  4. Provider Traversal: Ability to inspect and manage the dependency graph
  5. Wiring: Automatic injection into functions and methods

​
Implementation Pattern

Tasteful implements a sophisticated dependency injection system that combines the power of the dependency-injector library with graph-based dependency resolution: Container Architecture: Each flavor maintains its own declarative container that automatically registers services and repositories based on constructor dependencies. This eliminates the need for manual provider configuration while maintaining full control over the dependency graph. Graph-Based Resolution: The system uses a dependency graph to analyze constructor signatures and determine the correct order for dependency registration. This ensures that dependencies are available when needed and prevents circular dependency issues. Automatic Registration: Services and repositories are automatically registered as singleton providers in the container, with their constructor dependencies resolved and injected automatically.

​
Service Registration Pattern

The framework employs an intelligent service registration mechanism that: Analyzes Constructor Signatures: Uses Python’s inspection capabilities to examine constructor parameters and their type annotations to understand dependency requirements. Resolves Dependencies: Automatically identifies which dependencies are available in the injectable classes list and creates the appropriate provider relationships. Creates Providers: Dynamically creates singleton providers for each service, ensuring proper lifecycle management and dependency injection. Maintains Type Safety: Preserves type annotations and IDE support while providing runtime dependency resolution.

​
Consequences

​
Positive

  • Testability: Easy to mock dependencies and override containers for testing
  • Flexibility: Can swap implementations based on environment or configuration
  • Type Safety: Maintains Python type hints and IDE support
  • Performance: Efficient lazy loading and singleton management
  • Documentation: Self-documenting dependency graphs
  • Debugging: Clear dependency resolution path

​
Negative

  • Learning Curve: Team needs to understand DI concepts and this specific library
  • Boilerplate: Requires container definitions for each module
  • Runtime Complexity: Additional abstraction layer
  • Debugging Complexity: Dependency resolution errors can be harder to trace

​
Trade-offs

  • Flexibility vs. Simplicity: More powerful but requires more setup
  • Runtime vs. Compile-time: Some dependency issues only surface at runtime
  • Explicit vs. Implicit: Clear dependency declarations but more verbose

​
Alternatives Considered

  1. Manual Dependency Injection: Constructor injection without framework
    • Rejected: Too much boilerplate and error-prone for complex graphs
  2. injector library: Simpler DI framework
    • Rejected: Less mature, fewer features for configuration management
  3. FastAPI’s built-in dependency injection: Using Depends()
    • Considered: Good for HTTP layer but not suitable for service layer architecture
  4. Service Locator Pattern: Global registry of services
    • Rejected: Anti-pattern that hides dependencies

​
Implementation Guidelines

​
Service Definition

class UserService(BaseService):
    def __init__(self, repository: UserRepository):
        self.repository = repository
    
    def get_user(self, user_id: int) -> User:
        return self.repository.find_by_id(user_id)

​
Flavor Integration

class UserController(BaseController):
    def __init__(self, user_service: UserService):
        super().__init__(prefix="/users", tags=["users"])
        self.user_service = user_service
    
    @Get("/{user_id}")
    def get_user(self, user_id: int):
        return self.user_service.get_user(user_id)

class UserFlavor(BaseFlavor):
    def __init__(self):
        super().__init__(
            controller=UserController,
            services=[UserService],
            repositories=[UserRepository],
            config=UserConfig
        )

​
Testing Override

def test_user_service():
    # Create flavor instance
    flavor = UserFlavor()
    
    # Override specific dependencies in the container
    mock_repo = Mock(spec=UserRepository)
    with flavor.container.UserRepository.override(mock_repo):
        # Access controller which has the injected service
        controller = flavor.controller
        # Test with mocked repository
        result = controller.get_user(1)

​
References

⌘I