Spring Boot Dependency Injection

Overview

• Prioritize constructor injection to keep dependencies explicit, immutable, and mockable.
• Treat optional collaborators through guarded setters or providers while documenting defaults.
• Resolve bean ambiguity intentionally through qualifiers, primary beans, and profiles.
• Validate wiring with focused unit tests before relying on Spring's TestContext framework.

When to Use

• Implement constructor injection for new

  @Service

  ,

  @Component

  , or

  @Repository

  classes.
• Replace legacy field injection while modernizing Spring modules.
• Configure optional or pluggable collaborators (feature flags, multi-tenant adapters).
• Audit bean definitions before adding integration tests or migrating Spring Boot versions.

Prerequisites

• Align project with Java 17+ and Spring Boot 3.5.x (or later) to leverage records and

  @ServiceConnection

  .
• Keep build tooling ready to run

  ./gradlew test

  or

  mvn test

  for validation.
• Load supporting material from

  ./references/

  when deeper patterns or samples are required.

Workflow

1. Map Collaborators

• Inventory constructors,

  @Autowired

  members, and configuration classes.
• Classify dependencies as mandatory (must exist) or optional (feature-flagged, environment-specific).

2. Apply Constructor Injection

• Introduce constructors (or Lombok

  @RequiredArgsConstructor

  ) that accept every mandatory collaborator.
• Mark injected fields

  final

  and protect invariants with

  Objects.requireNonNull

  if Lombok is not used.
• Update

  @Configuration

  or

  @Bean

  factories to pass dependencies explicitly; consult

  ./references/reference.md

  for canonical bean wiring.

3. Handle Optional Collaborators

• Supply setters annotated with

  @Autowired(required = false)

  or inject

  ObjectProvider<T>

  for lazy access.
• Provide deterministic defaults (for example, no-op implementations) and document them inside configuration modules.
• Follow

  ./references/examples.md#example-2-setter-injection-for-optional-dependencies

  for a full workflow.

4. Resolve Bean Selection

• Choose

  @Primary

  for dominant implementations and

  @Qualifier

  for niche variants.
• Use profiles, conditional annotations, or factory methods to isolate environment-specific wiring.
• Reference

  ./references/reference.md#conditional-bean-registration

  for conditional and profile-based samples.

5. Validate Wiring

• Write unit tests that instantiate classes manually with mocks to prove Spring-free testability.
• Add slice or integration tests (

  @WebMvcTest

  ,

  @DataJpaTest

  ,

  @SpringBootTest

  ) only after constructor contracts are validated.
• Reuse patterns in

  ./references/reference.md#testing-with-dependency-injection

  to select the proper test style.

Examples

Basic Constructor Injection

@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;
    private final EmailService emailService;

    public User register(UserRegistrationRequest request) {
        User user = User.create(request.email(), request.name());
        userRepository.save(user);
        emailService.sendWelcome(user);
        return user;
    }
}

• Instantiate directly in tests:

  new UserService(mockRepo, mockEmailService);

  with no Spring context required.

Intermediate: Optional Dependency with Guarded Setter

@Service
public class ReportService {
    private final ReportRepository reportRepository;
    private CacheService cacheService = CacheService.noOp();

    public ReportService(ReportRepository reportRepository) {
        this.reportRepository = reportRepository;
    }

    @Autowired(required = false)
    public void setCacheService(CacheService cacheService) {
        this.cacheService = cacheService;
    }
}

• Provide fallbacks such as

  CacheService.noOp()

  to ensure deterministic behavior when the optional bean is absent.

Advanced: Conditional Configuration Across Modules

@Configuration
@Import(DatabaseConfig.class)
public class MessagingConfig {

    @Bean
    @ConditionalOnProperty(name = "feature.notifications.enabled", havingValue = "true")
    public NotificationService emailNotificationService(JavaMailSender sender) {
        return new EmailNotificationService(sender);
    }

    @Bean
    @ConditionalOnMissingBean(NotificationService.class)
    public NotificationService noopNotificationService() {
        return NotificationService.noOp();
    }
}

• Combine

  @Import

  , profiles, and conditional annotations to orchestrate cross-cutting modules.

./references/examples.md

Best Practices

• Prefer constructor injection for mandatory dependencies; allow Spring 4.3+ to infer

  @Autowired

  on single constructors.
• Encapsulate optional behavior inside dedicated adapters or providers instead of accepting

  null

  pointers.
• Keep service constructors lightweight; extract orchestrators when dependency counts exceed four.
• Favor domain interfaces in the domain layer and defer framework imports to infrastructure adapters.
• Document bean names and qualifiers in shared constants to avoid typo-driven mismatches.

Constraints

• Avoid field injection and service locator patterns because they obscure dependencies and impede unit testing.
• Prevent circular dependencies by publishing domain events or extracting shared abstractions.
• Limit

  @Lazy

  usage to performance-sensitive paths and record the deferred initialization risk.
• Do not add profile-specific beans without matching integration tests that activate the profile.
• Ensure each optional collaborator has a deterministic default or feature-flag handling path.

Reference Materials

• extended documentation covering annotations, bean scopes, testing, and anti-pattern mitigations
• progressive examples from constructor injection basics to multi-module configurations
• curated excerpts from the official Spring Framework documentation (constructor vs setter guidance, conditional wiring)

Related Skills

• spring-boot-crud-patterns

  – service-layer orchestration patterns that rely on constructor injection.

• spring-boot-rest-api-standards

  – controller-layer practices that assume explicit dependency wiring.

• unit-test-service-layer

  – Mockito-based testing patterns for constructor-injected services.