spring-boot-dependency-injection ยท diff
git:20260323.2528036 to git:20260324.a02e282
21 added, 15 removed. Audit A to A.
---
name: spring-boot-dependency-injection
description: Provides dependency injection patterns for Spring Boot projects, including constructor-first design, optional collaborator handling, bean selection, and wiring validation. Use when creating services and configurations, replacing field injection, or troubleshooting ambiguous or fragile Spring wiring.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---
# Spring Boot Dependency Injection
## Overview
- Use this skill to keep Spring Boot wiring explicit, testable, and predictable.
-
- The core model is simple:
- - constructor injection for mandatory collaborators
- - explicit strategies for optional collaborators
- - configuration classes that make bean selection obvious
-
- This skill is about shaping code so it remains easy to test without depending on the Spring container for every unit test.
+ Provides constructor-first dependency injection patterns for Spring Boot:
+ - mandatory collaborators via constructor injection
+ - optional collaborators via `ObjectProvider` or no-op fallbacks
+ - bean selection via `@Primary` and `@Qualifier`
+ - validation via minimal context tests before full integration
## When to Use
Use this skill when:
- creating a new `@Service`, `@Component`, `@Repository`, or `@Configuration` class
- replacing field injection in legacy Spring code
- resolving multiple beans of the same type with qualifiers or primary beans
- handling optional features, adapters, or integrations without null-driven wiring
- reviewing circular dependencies or brittle context startup failures
- preparing code for direct constructor-based unit testing
- Typical trigger phrases include `spring dependency injection`, `constructor injection`, `replace field injection`, `qualifier vs primary`, and `optional bean`.
## Instructions
### 1. Separate mandatory and optional collaborators
For each class, identify:
- mandatory collaborators required for correct behavior
- optional collaborators that enable integrations, caching, notifications, or feature-flagged behavior
Mandatory collaborators belong in the constructor. Optional ones need an explicit strategy such as `ObjectProvider`, conditional beans, or a no-op implementation.
### 2. Default to constructor injection
For application services and adapters:
- inject mandatory dependencies through the constructor
- keep injected fields `final`
- instantiate the class directly in unit tests without starting Spring
A single constructor is usually enough; `@Autowired` is unnecessary in that case.
### 3. Resolve optional behavior intentionally
Good options include:
- `ObjectProvider<T>` when lazy access is useful
- `@ConditionalOnProperty` or `@ConditionalOnMissingBean` when wiring should change by configuration
- a no-op implementation when the caller should not care whether the feature is enabled
Avoid nullable collaborators that leave runtime behavior ambiguous.
### 4. Use bean selection annotations only when needed
When multiple beans share the same type:
- use `@Primary` for the default implementation
- use `@Qualifier` for named variants
- keep the qualifier names stable and easy to grep
If selection rules become complex, move them into a dedicated configuration class instead of spreading them across services.
### 5. Keep wiring in configuration, not business code
Use `@Configuration` and `@Bean` methods when:
- the object comes from a third-party library
- conditional creation logic is needed
- you need environment-specific wiring or explicit composition
Business services should not know how infrastructure collaborators are instantiated.
- ### 6. Validate wiring with the smallest useful test
+ ### 6. Validate wiring explicitly
- Test in this order:
- - direct constructor-based unit tests for service behavior
- - slice tests when Spring MVC, JPA, or messaging integration matters
- - full `@SpringBootTest` only when container-wide wiring must be proven
+ After writing a new service or configuration:
- This keeps failures localized and makes dependency problems obvious.
+ 1. **Verify the bean loads** with a minimal context test:
+ ```java
+ @SpringBootTest
+ @ContextConfiguration(classes = UserService.class)
+ class UserServiceWiringTest {
+ @Autowired UserService userService;
+ @Test void serviceIsInstantiated() { assertNotNull(userService); }
+ }
+ ```
+ 2. **Run constructor-based unit tests** for service behavior (no Spring needed).
+ 3. **Add slice tests** only when MVC, JPA, or messaging integration must be verified.
+ 4. **Reserve `@SpringBootTest`** for container-wide wiring validation.
+
+ Failures at step 1 indicate wiring issues before business logic is added.
## Examples
### Example 1: Constructor-first application service
```java
@Service
public class UserService {
private final UserRepository userRepository;
private final EmailSender emailSender;
public UserService(UserRepository userRepository, EmailSender emailSender) {
this.userRepository = userRepository;
this.emailSender = emailSender;
}
public User register(UserRegistrationRequest request) {
User user = userRepository.save(User.from(request));
emailSender.sendWelcome(user);
return user;
}
}
```
This class is easy to instantiate directly in a unit test with mocks.
### Example 2: Optional dependency with a no-op fallback
```java
@Service
public class ReportService {
private final ReportRepository reportRepository;
private final NotificationGateway notificationGateway;
public ReportService(
ReportRepository reportRepository,
ObjectProvider<NotificationGateway> notificationGatewayProvider
) {
this.reportRepository = reportRepository;
this.notificationGateway = notificationGatewayProvider.getIfAvailable(NotificationGateway::noOp);
}
}
```
This keeps optional behavior explicit without leaking `null` handling through the rest of the class.
### Example 3: Multiple beans with clear selection
```java
@Configuration
public class PaymentConfiguration {
@Bean
@Primary
PaymentGateway stripeGateway() {
return new StripePaymentGateway();
}
@Bean
@Qualifier("fallbackGateway")
PaymentGateway mockGateway() {
return new MockPaymentGateway();
}
}
```
Use `@Primary` for the default path and `@Qualifier` only where a specific variant is required.
## Best Practices
- Prefer constructor injection for mandatory dependencies.
- Keep service constructors small; if a class needs too many collaborators, the design probably wants another abstraction.
- Use no-op or conditional beans instead of nullable optional dependencies.
- Keep framework-specific creation logic in configuration classes.
- Test services without Spring first, then add container tests only where they add value.
- Remove field injection during refactors instead of extending it.
## Constraints and Warnings
- Field injection hides dependencies and makes tests harder to write.
- Circular dependencies are usually a design problem, not a wiring trick to solve with `@Lazy`.
- Overusing qualifiers can make the codebase hard to reason about; prefer better abstractions or clearer configuration.
- Optional collaborators still need deterministic behavior when absent.
- Full-context tests can hide the real source of wiring failures if used too early.
## References
- `references/reference.md`
- `references/examples.md`
- `references/spring-official-dependency-injection.md`
## Related Skills
- `spring-boot-crud-patterns`
- `spring-boot-rest-api-standards`
- `unit-test-service-layer`