DI Anti-Patterns - Learning Module

Loading content...

0/246

DI Best Practices Checklist

From Knowledge to Practice

You now understand the major dependency injection anti-patterns: constructor over-injection, circular dependencies, and captive dependencies. But knowledge without application is incomplete. This page consolidates everything into an actionable best practices checklist—a practical reference you can apply to code reviews, new project setup, and architectural decisions.

Think of this checklist as a pre-flight checklist for DI. Pilots don't wing it; they systematically verify everything before takeoff. Similarly, these practices should become habitual verification points in your development workflow.

What You Will Learn

By the end of this page, you will have a comprehensive checklist covering constructor design, interface design, lifetime management, container configuration, testing, and code review criteria. Each practice is actionable, verifiable, and directly applicable to production code.

Constructor Design Best Practices

The constructor is the primary injection point and the first place to look for DI health. These practices ensure constructors remain clean and maintainable:

Constructor Design Checklist

•☐ Limit constructor parameters to 4 or fewer — If exceeding 4, scrutinize for SRP violations. If exceeding 7, refactoring is mandatory.
•☐ Inject abstractions, not concretions — Parameters should be interfaces or abstract classes, never concrete implementations directly.
•☐ All injected dependencies should be required — If a dependency is optional, use setter injection or Null Object pattern instead.
•☐ Constructor should only assign dependencies — No business logic, no initialization calls, no external resource access. Just assignment.
•☐ Store dependencies as private readonly fields — Prevents accidental reassignment and signals immutability intent.
•☐ Guard clauses for null checks if container doesn't guarantee — Fail fast with clear error messages: this.service = service ?? throw new ArgumentNullException(nameof(service))
•☐ No Service Locator calls in constructor — Never resolve additional dependencies; receive only what's declared.
•☐ Avoid constructor work — Don't call virtual methods, don't start async operations, don't access external resources.

IdealConstructorExample.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// ✅ Ideal constructor following all best practices
 
class OrderService {
    // Private readonly fields - immutable after construction
    private readonly orderRepository: IOrderRepository;
    private readonly pricingService: IPricingService;
    private readonly eventPublisher: IEventPublisher;
    
    constructor(
        // Abstractions, not concretions
        orderRepository: IOrderRepository,
        pricingService: IPricingService,
        eventPublisher: IEventPublisher
    ) {
        // Guard clauses - fail fast with clear messages
        if (!orderRepository) throw new Error('orderRepository is required');
        if (!pricingService) throw new Error('pricingService is required');
        if (!eventPublisher) throw new Error('eventPublisher is required');
        
        // ONLY assignment - no logic, no calls, no initialization
        this.orderRepository = orderRepository;
        this.pricingService = pricingService;
        this.eventPublisher = eventPublisher;
        
        // ❌ WRONG: Don't do any of these in constructor:
        // this.warmupCache();           // Side effect
        // await this.loadConfig();      // Async work
        // this.repository.validate();   // External call
        // console.log('Constructed');   // Side effect
    }
}

The Boring Constructor Principle

The best constructor is the most boring constructor. It should be so simple that reviewing it takes seconds. Any complexity in the constructor is either misplaced logic or a design smell waiting to cause problems.

Interface Design Best Practices

Well-designed interfaces are the foundation of effective dependency injection. These practices ensure interfaces serve their purpose as abstraction points:

Interface Design Checklist

•☐ Interfaces should represent capabilities, not implementations — IEmailSender not ISmtpClient; IPaymentProcessor not IStripeGateway.
•☐ Apply Interface Segregation Principle — Many small, focused interfaces over few large interfaces. Clients should not depend on methods they don't use.
•☐ Interfaces belong to consumers, not providers — Define interfaces in the module that needs them, not the module that implements them.
•☐ Avoid leaky abstractions — Interfaces should not expose implementation details like connection strings, retry policies, or technology choices.
•☐ Consider lifetime in interface naming — For scoped services with inherent lifetime, indicate in name: IRequestScopedContext vs ISingletonCache.
•☐ Document expected semantics — Interface comments should specify contracts: idempotency, thread-safety, resource management, exception behavior.
•☐ Avoid 'God interfaces' — If an interface has more than 5-7 methods, it likely needs splitting.
•☐ Marker interfaces should be avoided — Use attributes, decorators, or explicit type markers instead of empty interfaces.

InterfaceDesignExamples.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
// ✅ GOOD: Focused, consumer-oriented interfaces
 
/**
 * Sends notifications to users through the configured channel.
 * Thread-safe. Idempotent when given same notificationId.
 * @throws NotificationFailedException if all retry attempts exhausted
 */
interface INotificationSender {
    send(notification: Notification): Promise<void>;
    scheduleForLater(notification: Notification, sendAt: Date): Promise<string>;
}
 
/**
 * Provides access to the current user's context within a request.
 * SCOPED: New instance per HTTP request. Do not inject into singletons.
 */
interface IRequestScopedUserContext {
    readonly userId: string;
    readonly tenantId: string;
    readonly permissions: ReadonlyArray<string>;
    hasPermission(permission: string): boolean;
}
 
/**
 * Thread-safe cache for read-heavy, write-light data.
 * SINGLETON: Single instance across application lifetime.
 */
interface ISingletonCache<K, V> {
    get(key: K): V | undefined;
    set(key: K, value: V, options?: CacheOptions): void;
    invalidate(key: K): void;
}
 
// ❌ BAD: Leaky, implementation-coupled interfaces
 
interface IUserRepository {
    // Exposes SQL - leaky abstraction
    executeQuery(sql: string): Promise<any[]>;
    
    // Exposes MongoDB - implementation detail
    getMongoCollection(): MongoCollection;
    
    // Too many methods - God interface
    findById(id: string): Promise<User>;
    findByEmail(email: string): Promise<User>;
    findByPhone(phone: string): Promise<User>;
    search(criteria: SearchCriteria): Promise<User[]>;
    save(user: User): Promise<void>;
    delete(id: string): Promise<void>;
    bulkImport(users: User[]): Promise<void>;
    exportToCSV(): Promise<string>;
    // ... 15 more methods
}

Lifetime Management Best Practices

Correct lifetime management prevents captive dependencies and ensures resources are properly scoped and disposed:

Lifetime Management Checklist

•☐ Prefer scoped over singleton — Singleton is a global variable in disguise. Use only when statelessness or explicit shared state is required.
•☐ Dependencies must have equal or longer lifetime — Scoped can depend on singleton. Singleton must never depend on scoped or transient.
•☐ Use factories for singletons that need scoped resources — Inject Func<T> or IServiceScopeFactory, not the scoped service directly.
•☐ Enable lifetime validation in development — Turn on ValidateScopes or equivalent to catch captive dependencies at runtime.
•☐ Document lifetime in registration — Add comments explaining why a service is singleton/scoped/transient. Future maintainers will thank you.
•☐ Disposable services should be scoped or transient — Singletons live forever; if they hold disposable resources, disposal never happens.
•☐ Background services need explicit scope creation — Jobs, timers, and event handlers must create their own scopes for scoped dependencies.
•☐ Avoid ambient contexts — Static HttpContext.Current or thread-local storage is implicit global state. Pass context explicitly.

Lifetime Selection Guide
Service Type	Recommended Lifetime	Reasoning
Database Context	Scoped	Unit of work per request; connection management
HTTP Client	Singleton (pooled)	Connection pooling; DNS changes handled internally
User Context	Scoped	Request-specific state; security boundary
Configuration	Singleton	Immutable after startup; shared read-only
Logger	Singleton	Stateless; thread-safe by design
Validator	Transient or Scoped	Typically stateless; no sharing needed
Cache	Singleton	Shared state is the point; thread-safe required
Domain Service	Scoped	May use unit of work; isolated per request
Background Worker Host	Singleton	Long-running; creates scopes internally
Factory	Singleton	Stateless creator; produces scoped instances

When in Doubt, Choose Scoped

Scoped lifetime is the safest default. It provides request isolation, automatic disposal, and prevents most captive dependency issues. Only upgrade to singleton when you have explicit reasons (shared state, expensive construction, stateless services).

Container Configuration Best Practices

How you configure the IoC container impacts maintainability, testability, and the likelihood of anti-patterns:

Container Configuration Checklist

•☐ Use Composition Root pattern — All container configuration in one location. No scattered registrations across modules.
•☐ Prefer convention-based registration — Auto-register by naming pattern or interface implementation rather than explicit per-class registration.
•☐ Avoid container references outside composition root — Business code should never see IServiceProvider, IContainer, or IScope.
•☐ Register open generics when possible — Register(typeof(IRepository<>), typeof(Repository<>)) over individual registrations.
•☐ Validate container at startup — Call the container's validation method to catch missing registrations before first request.
•☐ Use modules/installers for organization — Group related registrations into installer classes for large applications.
•☐ Avoid conditional registration based on runtime state — Configuration should be deterministic at startup.
•☐ Enable detailed logging in development — Log all resolutions to understand and debug the container's behavior.

CompositionRoot.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// ✅ GOOD: Clean composition root with organized modules
 
// === COMPOSITION ROOT (single location for all wiring) ===
class CompositionRoot {
    static configureContainer(container: Container, config: AppConfig): void {
        // Infrastructure module - databases, external services
        InfrastructureModule.register(container, config);
        
        // Domain module - business logic services
        DomainModule.register(container, config);
        
        // Application module - use cases, handlers
        ApplicationModule.register(container, config);
        
        // Presentation concerns - controllers, view models (if applicable)
        PresentationModule.register(container, config);
        
        // Validate all registrations at startup
        container.validate();
        
        console.log(`Container configured with ${container.registrationCount} services`);
    }
}
 
// === INFRASTRUCTURE MODULE ===
class InfrastructureModule {
    static register(container: Container, config: AppConfig): void {
        // Database context - scoped (unit of work per request)
        container.register(IDbContext, DbContext, Lifetime.Scoped);
        
        // HTTP client - singleton (connection pooling)
        container.register(IHttpClient, HttpClient, Lifetime.Singleton);
        
        // Cache - singleton (shared state)
        container.register(ICache, RedisCache, Lifetime.Singleton);
        
        // Message bus - singleton (connection pooling)
        container.register(IMessageBus, RabbitMqBus, Lifetime.Singleton);
    }
}
 
// === DOMAIN MODULE (using convention-based registration) ===
class DomainModule {
    static register(container: Container, config: AppConfig): void {
        // Auto-register all domain services by convention
        container.registerByConvention({
            assemblies: ['domain'],
            pattern: /.*Service$/,        // Classes ending in 'Service'
            asInterface: true,            // Register as I{ClassName}
            lifetime: Lifetime.Scoped,    // Default to scoped
        });
        
        // Register open generic repository
        container.registerGeneric(
            IRepository, 
            Repository, 
            Lifetime.Scoped
        );
    }
}

Testing Best Practices

Dependency injection is fundamentally about testability. These practices ensure DI delivers its testing benefits:

Testing Checklist

•☐ Unit tests should not use the container — Create mocks manually and pass to constructor. Container adds complexity without value.
•☐ Integration tests should use the real container — Validate actual wiring works. Create test-specific registrations only where necessary.
•☐ Mock only direct dependencies — Don't mock dependencies of dependencies. If test setup is too complex, the class has too many dependencies.
•☐ Prefer fakes over mocks for repositories — In-memory fakes are more realistic than mocks for data access tests.
•☐ Test lifetime behavior explicitly — Write tests that verify singleton vs scoped behavior when it matters.
•☐ CI should run with ValidateScopes enabled — Catch captive dependencies in the test pipeline.
•☐ Test composition root validation — Have a test that calls container.validate() to catch missing registrations.
•☐ Avoid testing implementation details — Test behavior, not that specific dependencies were called in specific order.

TestingExamples.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
// ✅ GOOD: Unit test without container
 
describe('OrderService', () => {
    it('should calculate total with discount', async () => {
        // Arrange: Create mocks manually - no container needed
        const mockRepository = createMock<IOrderRepository>();
        const mockPricingService = createMock<IPricingService>();
        const mockEventPublisher = createMock<IEventPublisher>();
        
        mockPricingService.calculateTotal.mockReturnValue({ 
            subtotal: 100, 
            discount: 10, 
            total: 90 
        });
        
        // Create service with mocks - just like production wiring
        const service = new OrderService(
            mockRepository,
            mockPricingService,
            mockEventPublisher
        );
        
        // Act
        const result = await service.createOrder(testOrder);
        
        // Assert
        expect(result.total).toBe(90);
        expect(mockEventPublisher.publish).toHaveBeenCalledWith(
            expect.objectContaining({ type: 'OrderCreated' })
        );
    });
});
 
// ✅ GOOD: Integration test with real container
 
describe('OrderService Integration', () => {
    let container: Container;
    
    beforeAll(() => {
        container = new Container();
        CompositionRoot.configureContainer(container, testConfig);
        
        // Override only what needs test isolation
        container.override(IPaymentGateway, FakePaymentGateway);
        container.override(IEmailSender, FakeEmailSender);
    });
    
    it('should complete order flow end-to-end', async () => {
        // Resolve from container - tests real wiring
        const orderService = container.resolve(IOrderService);
        
        const result = await orderService.createOrder(testOrder);
        
        expect(result.status).toBe('Completed');
        // Verify side effects in fakes
        expect(container.resolve(FakeEmailSender).sentEmails).toHaveLength(1);
    });
});
 
// ✅ GOOD: Composition root validation test
 
describe('CompositionRoot', () => {
    it('should validate all registrations successfully', () => {
        const container = new Container();
        
        // This will throw if any registration is missing a dependency
        expect(() => {
            CompositionRoot.configureContainer(container, productionConfig);
        }).not.toThrow();
    });
    
    it('should catch lifetime violations with scope validation', () => {
        const container = new Container({ validateScopes: true });
        CompositionRoot.configureContainer(container, productionConfig);
        
        // Create a scope and resolve all services to verify lifetimes
        const scope = container.createScope();
        const registrations = container.getAllRegistrations();
        
        for (const reg of registrations) {
            expect(() => scope.resolve(reg.serviceType)).not.toThrow();
        }
    });
});

Code Review Criteria

Code reviews are the last line of defense against DI anti-patterns. Use this checklist when reviewing code that involves dependency injection:

Code Review Checklist

•☐ Does this change add a constructor parameter? — If yes, what's the new total? Flag if exceeding 4.
•☐ Does a new dependency create a circular reference? — Mentally trace the dependency chain. Use tooling if the graph is complex.
•☐ Are lifetime scopes correctly matched? — Singleton depending on scoped? Scoped captured in event handler? Flag for discussion.
•☐ Is the new dependency an abstraction? — Concrete class injection should be rare and justified.
•☐ Is container access leaking into business code? — IServiceProvider or Container.Resolve() outside composition root is a smell.
•☐ Could this dependency be method-injected instead? — If used by only one method, consider passing as parameter.
•☐ Are disposables being properly managed? — Transient disposables resolved without scope may leak.
•☐ Is the registration in the composition root? — Scattered registrations reduce visibility and maintainability.

Review Decision Matrix
Observation	Action	Severity
5+ constructor parameters	Request decomposition into smaller classes	Block PR
New circular dependency path possible	Request dependency graph check with tooling	Block PR
Singleton with scoped dependency	Request factory injection or lifetime change	Block PR
Concrete type injected without justification	Request interface extraction	Request changes
IServiceProvider in business class	Request refactoring to explicit dependencies	Block PR
Missing null checks in constructor	Add guard clauses	Request changes
Undocumented lifetime choice	Add comment explaining lifetime decision	Optional

Automate What You Can

Configure linters and static analysis to catch constructor parameter counts, circular dependencies, and other mechanical checks. Reserve human review time for design decisions that require judgment and context.

Anti-Pattern Quick Reference

A consolidated reference of the anti-patterns we've covered, with instant recognition cues and remediation approaches:

DI Anti-Patterns at a Glance
Anti-Pattern	Recognition Cue	Root Cause	Primary Fix
Constructor Over-Injection	7+ constructor parameters	SRP violation; class doing too much	Extract cohesive classes; facade pattern
Circular Dependency	Stack overflow at startup; construction fails	Missing abstraction; misplaced responsibilities	Extract interface; mediator; events
Captive Dependency	Memory leak; stale data; ObjectDisposedException	Singleton holding scoped/transient reference	Factory injection; scope factory
Service Locator	IServiceProvider in business code	Hiding dependencies; avoiding explicit injection	Constructor injection; explicit dependencies
Bastard Injection	Default dependencies in constructor	Testing convenience; legacy code	Full constructor injection; DI container
Control Freak	New keyword for dependencies in class	Not understanding DI benefits	Move instantiation to composition root
Ambient Context	Static Current property; thread-local	Convenience over explicitness	Explicit context injection

AntiPatternExamplesQuickRef.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
// ANTI-PATTERNS QUICK VISUAL REFERENCE
 
// ❌ Constructor Over-Injection
class BadService {
    constructor(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H) {} // 8 params!
}
 
// ❌ Circular Dependency  
class A { constructor(b: B) {} }
class B { constructor(a: A) {} } // A ↔ B cycle
 
// ❌ Captive Dependency
class Singleton { 
    constructor(scopedService: ScopedService) {} // Singleton ← Scoped
}
 
// ❌ Service Locator
class BadController {
    private service: IService;
    constructor(container: IServiceProvider) {
        this.service = container.resolve(IService); // Hidden dependency!
    }
}
 
// ❌ Bastard Injection
class BadService {
    constructor(
        repo: IRepository = new ConcreteRepository() // Default = hidden coupling
    ) {}
}
 
// ❌ Control Freak
class BadService {
    doWork() {
        const helper = new Helper(); // Creating dependency internally
        helper.help();
    }
}
 
// ❌ Ambient Context
class BadService {
    doWork() {
        const user = HttpContext.Current.User; // Static global state
    }
}

Summary and Mastery Criteria

Let's consolidate everything from this module into a final checklist and mastery criteria:

DI Mastery Criteria

•You can identify constructor over-injection at a glance — The 4-parameter threshold is internalized; you automatically scrutinize exceeding classes.
•You trace dependency graphs mentally — When adding a dependency, you consider potential cycles without needing tooling for simple cases.
•You understand lifetime hierarchy instinctively — Singleton → Scoped → Transient flows naturally; violations feel wrong.
•Your constructors are boring — Assignment only, no logic, no surprises. This is a feature, not a limitation.
•You reach for interfaces automatically — Concrete injection feels uncomfortable; abstraction is the default.
•You design for testability from the start — Mock-friendly interfaces, focused dependencies, no hidden state.
•You configure containers systematically — Composition root, organized modules, validation at startup.
•You catch anti-patterns in code review — The recognition is instant; remediation paths are known.

The Expert's Insight

True DI mastery isn't about following rules mechanically—it's about understanding why these patterns exist. The rules prevent problems discovered through decades of collective experience. When you deeply understand the problems, the solutions become obvious rather than prescriptive.

Module Complete:

You have now completed the comprehensive exploration of DI anti-patterns and best practices. You understand:

Constructor over-injection — The visible symptom of SRP violations, diagnosed through dependency counting and method-dependency matrices
Circular dependencies — The impossible construction cycle, detected through static analysis and resolved through abstractions and events
Captive dependencies — The silent memory killer, prevented through lifetime discipline and factory injection
Best practices — A comprehensive checklist covering construction, interfaces, lifetimes, containers, testing, and code review

These patterns apply across languages, frameworks, and decades of software evolution. They are foundational knowledge for any engineer building maintainable systems.

Module Complete

Congratulations! You have completed Module 8: DI Anti-Patterns and Best Practices. You now possess the knowledge to identify, prevent, and resolve the most common dependency injection problems. Apply this checklist to your projects, share it with your team, and make DI a strength rather than a source of technical debt.