Initial commit

2025-11-29 18:28:30 +08:00
commit 171acedaa4
220 changed files with 85967 additions and 0 deletions
--- a/skills/spring-boot/spring-boot-dependency-injection/references/reference.md
+++ b/skills/spring-boot/spring-boot-dependency-injection/references/reference.md
@@ -0,0 +1,640 @@
+# Spring Boot Dependency Injection - References
+
+Complete API reference for dependency injection in Spring Boot applications.
+
+## Core Interfaces and Classes
+
+### ApplicationContext
+Root interface for Spring IoC container.
+
+```java
+public interface ApplicationContext extends EnvironmentCapable, ListableBeanFactory, 
+                                          HierarchicalBeanFactory, MessageSource,
+                                          ApplicationEventPublisher, ResourcePatternResolver {
+    
+    // Get a bean by type
+    <T> T getBean(Class<T> requiredType);
+    
+    // Get a bean by name and type
+    <T> T getBean(String name, Class<T> requiredType);
+    
+    // Get all beans of a type
+    <T> Map<String, T> getBeansOfType(Class<T> type);
+    
+    // Get all bean names
+    String[] getBeanDefinitionNames();
+}
+```
+
+### BeanFactory
+Lower-level interface for accessing beans (used internally).
+
+```java
+public interface BeanFactory {
+    Object getBean(String name);
+    <T> T getBean(String name, Class<T> requiredType);
+    <T> T getBean(Class<T> requiredType);
+    Object getBean(String name, Object... args);
+}
+```
+
+## Dependency Injection Annotations
+
+### @Autowired
+Auto-wire dependencies (property, constructor, or method injection).
+
+```java
+@Autowired                        // Required dependency
+@Autowired(required = false)      // Optional dependency
+@Autowired private UserRepository repository;  // Field injection (avoid)
+```
+
+### @Qualifier
+Disambiguate when multiple beans of same type exist.
+
+```java
+@Autowired
+@Qualifier("primaryDB")
+private DataSource dataSource;
+
+@Bean
+@Qualifier("cache")
+public CacheService cacheService() { }
+```
+
+### @Primary
+Mark bean as preferred when multiple exist.
+
+```java
+@Bean
+@Primary
+public DataSource primaryDataSource() { }
+
+@Bean
+public DataSource secondaryDataSource() { }
+```
+
+### @Value
+Inject properties and SpEL expressions.
+
+```java
+@Value("${app.name}")             // Property injection
+@Value("${app.port:8080}")        // With default value
+@Value("#{T(java.lang.Math).PI}") // SpEL expression
+@Value("#{'${app.servers}'.split(',')}")  // Collection
+private String value;
+```
+
+### @Lazy
+Delay bean initialization until first access.
+
+```java
+@Bean
+@Lazy
+public ExpensiveBean expensiveBean() { }
+
+@Autowired
+@Lazy
+private ExpensiveBean bean;  // Lazy proxy
+```
+
+### @Scope
+Define bean lifecycle scope.
+
+```java
+@Scope("singleton")     // One per container (default)
+@Scope("prototype")     // New instance each time
+@Scope("request")       // One per HTTP request
+@Scope("session")       // One per HTTP session
+@Scope("application")   // One per ServletContext
+@Scope("websocket")     // One per WebSocket session
+```
+
+### @Configuration
+Mark class as providing bean definitions.
+
+```java
+@Configuration
+public class AppConfig {
+    @Bean
+    public UserService userService() { }
+}
+```
+
+### @Bean
+Define a bean in configuration class.
+
+```java
+@Bean
+public UserService userService(UserRepository repository) {
+    return new UserService(repository);
+}
+
+@Bean(name = "customName")
+public UserService userService() { }
+
+@Bean(initMethod = "init", destroyMethod = "cleanup")
+public UserService userService() { }
+```
+
+### @Component / @Service / @Repository / @Controller
+Stereotype annotations for component scanning.
+
+```java
+@Component              // Generic Spring component
+@Service               // Business logic layer
+@Repository           // Data access layer
+@Controller           // Web layer (MVC)
+@RestController       // Web layer (REST)
+public class UserService { }
+```
+
+## Conditional Bean Registration
+
+### @ConditionalOnProperty
+Create bean only if property exists.
+
+```java
+@Bean
+@ConditionalOnProperty(
+    name = "feature.notifications.enabled",
+    havingValue = "true"
+)
+public NotificationService notificationService() { }
+
+// OR if property matches any value
+@ConditionalOnProperty(name = "feature.enabled")
+public NotificationService notificationService() { }
+```
+
+### @ConditionalOnClass / @ConditionalOnMissingClass
+Create bean based on classpath availability.
+
+```java
+@Bean
+@ConditionalOnClass(RedisTemplate.class)
+public CacheService cacheService() { }
+
+@Bean
+@ConditionalOnMissingClass("org.springframework.data.redis.core.RedisTemplate")
+public LocalCacheService fallbackCacheService() { }
+```
+
+### @ConditionalOnBean / @ConditionalOnMissingBean
+Create bean based on other beans.
+
+```java
+@Bean
+@ConditionalOnBean(DataSource.class)
+public UserService userService() { }
+
+@Bean
+@ConditionalOnMissingBean
+public UserService defaultUserService() { }
+```
+
+### @ConditionalOnExpression
+Create bean based on SpEL expression.
+
+```java
+@Bean
+@ConditionalOnExpression("'${environment}'.equals('production')")
+public SecurityService securityService() { }
+```
+
+## Profile-Based Configuration
+
+### @Profile
+Activate bean only in specific profiles.
+
+```java
+@Configuration
+@Profile("production")
+public class ProductionConfig { }
+
+@Bean
+@Profile({"dev", "test"})
+public TestDataLoader testDataLoader() { }
+
+@Bean
+@Profile("!production")  // All profiles except production
+public DebugService debugService() { }
+```
+
+**Activate profiles:**
+```properties
+# application.properties
+spring.profiles.active=production
+
+# application-production.properties
+# Profile-specific property file
+spring.datasource.url=jdbc:postgresql://prod-db:5432/prod
+```
+
+## Component Scanning
+
+### @ComponentScan
+Configure component scanning.
+
+```java
+@Configuration
+@ComponentScan(basePackages = {"com.example.users", "com.example.products"})
+public class AppConfig { }
+
+@Configuration
+@ComponentScan(
+    basePackages = "com.example",
+    excludeFilters = @ComponentScan.Filter(
+        type = FilterType.REGEX,
+        pattern = "com\\.example\\.internal\\..*"
+    )
+)
+public class AppConfig { }
+```
+
+### Filter Types
+- `FilterType.ANNOTATION` - By annotation
+- `FilterType.ASSIGNABLE_TYPE` - By class type
+- `FilterType.ASPECTJ` - By AspectJ pattern
+- `FilterType.REGEX` - By regex pattern
+- `FilterType.CUSTOM` - Custom filter
+
+## Injection Points
+
+### Constructor Injection (Recommended)
+
+```java
+@Service
+@RequiredArgsConstructor  // Lombok generates constructor
+public class UserService {
+    private final UserRepository repository;  // Final field
+    private final EmailService emailService;
+}
+
+// Explicit
+@Service
+public class UserService {
+    private final UserRepository repository;
+    
+    public UserService(UserRepository repository) {
+        this.repository = Objects.requireNonNull(repository);
+    }
+}
+```
+
+### Setter Injection (Optional Dependencies Only)
+
+```java
+@Service
+public class UserService {
+    private final UserRepository repository;
+    private EmailService emailService;  // Optional
+    
+    public UserService(UserRepository repository) {
+        this.repository = repository;
+    }
+    
+    @Autowired(required = false)
+    public void setEmailService(EmailService emailService) {
+        this.emailService = emailService;
+    }
+}
+```
+
+### Field Injection (❌ Avoid)
+
+```java
+// ❌ NOT RECOMMENDED
+@Service
+public class UserService {
+    @Autowired
+    private UserRepository repository;  // Hidden dependency
+    
+    @Autowired
+    private EmailService emailService;  // Mutable state
+}
+```
+
+## Circular Dependency Resolution
+
+### Problem: Circular Dependencies
+
+```java
+// ❌ WILL FAIL
+@Service
+public class UserService {
+    private final OrderService orderService;
+    
+    public UserService(OrderService orderService) {
+        this.orderService = orderService;  // Circular!
+    }
+}
+
+@Service
+public class OrderService {
+    private final UserService userService;
+    
+    public OrderService(UserService userService) {
+        this.userService = userService;  // Circular!
+    }
+}
+```
+
+### Solution 1: Setter Injection
+
+```java
+@Service
+public class UserService {
+    private final UserRepository userRepository;
+    private OrderService orderService;  // Optional
+    
+    public UserService(UserRepository userRepository) {
+        this.userRepository = userRepository;
+    }
+    
+    @Autowired(required = false)
+    public void setOrderService(OrderService orderService) {
+        this.orderService = orderService;
+    }
+}
+```
+
+### Solution 2: Event-Driven (Recommended)
+
+```java
+public class UserRegisteredEvent extends ApplicationEvent {
+    private final String userId;
+    
+    public UserRegisteredEvent(Object source, String userId) {
+        super(source);
+        this.userId = userId;
+    }
+}
+
+@Service
+@RequiredArgsConstructor
+public class UserService {
+    private final UserRepository userRepository;
+    private final ApplicationEventPublisher eventPublisher;
+    
+    public User registerUser(CreateUserRequest request) {
+        User user = userRepository.save(User.create(request));
+        eventPublisher.publishEvent(new UserRegisteredEvent(this, user.getId()));
+        return user;
+    }
+}
+
+@Service
+@RequiredArgsConstructor
+public class OrderService {
+    private final OrderRepository orderRepository;
+    
+    @EventListener
+    public void onUserRegistered(UserRegisteredEvent event) {
+        orderRepository.createWelcomeOrder(event.getUserId());
+    }
+}
+```
+
+### Solution 3: Refactor to Separate Concerns
+
+```java
+// Shared service without circular dependency
+@Service
+@RequiredArgsConstructor
+public class UserOrderService {
+    private final UserRepository userRepository;
+    private final OrderRepository orderRepository;
+}
+
+@Service
+@RequiredArgsConstructor
+public class UserService {
+    private final UserOrderService userOrderService;
+}
+
+@Service
+@RequiredArgsConstructor
+public class OrderService {
+    private final UserOrderService userOrderService;
+}
+```
+
+## ObjectProvider for Flexibility
+
+### ObjectProvider Interface
+
+```java
+public interface ObjectProvider<T> extends ObjectFactory<T>, Iterable<T> {
+    T getObject();
+    T getObject(Object... args);
+    T getIfAvailable();
+    T getIfAvailable(Supplier<T> defaultSupplier);
+    void ifAvailable(Consumer<T> consumer);
+    void ifAvailableOrElse(Consumer<T> consumer, Runnable emptyRunnable);
+    <X> ObjectProvider<X> map(Function<? super T, ? extends X> mapper);
+    <X> ObjectProvider<X> flatMap(Function<? super T, ObjectProvider<X>> mapper);
+    Optional<T> getIfUnique();
+    Optional<T> getIfUnique(Supplier<T> defaultSupplier);
+}
+```
+
+### Usage Example
+
+```java
+@Service
+public class FlexibleService {
+    private final ObjectProvider<CacheService> cacheProvider;
+    
+    public FlexibleService(ObjectProvider<CacheService> cacheProvider) {
+        this.cacheProvider = cacheProvider;
+    }
+    
+    public void process() {
+        // Safely handle optional bean
+        cacheProvider.ifAvailable(cache -> cache.invalidate());
+        
+        // Get with fallback
+        CacheService cache = cacheProvider.getIfAvailable(() -> new NoOpCache());
+        
+        // Iterate if multiple beans exist
+        cacheProvider.forEach(cache -> cache.initialize());
+    }
+}
+```
+
+## Bean Lifecycle Hooks
+
+### InitializingBean / DisposableBean
+
+```java
+@Component
+public class ResourceManager implements InitializingBean, DisposableBean {
+    
+    @Override
+    public void afterPropertiesSet() throws Exception {
+        // Called after constructor and property injection
+        System.out.println("Bean initialized");
+    }
+    
+    @Override
+    public void destroy() throws Exception {
+        // Called when context shutdown
+        System.out.println("Bean destroyed");
+    }
+}
+```
+
+### @PostConstruct / @PreDestroy
+
+```java
+@Component
+public class ResourceManager {
+    
+    @PostConstruct
+    public void init() {
+        // Called after constructor and injection
+        System.out.println("Bean initialized");
+    }
+    
+    @PreDestroy
+    public void cleanup() {
+        // Called before bean destroyed
+        System.out.println("Bean destroyed");
+    }
+}
+```
+
+### @Bean with initMethod and destroyMethod
+
+```java
+@Configuration
+public class AppConfig {
+    
+    @Bean(initMethod = "init", destroyMethod = "cleanup")
+    public ResourceManager resourceManager() {
+        return new ResourceManager();
+    }
+}
+
+public class ResourceManager {
+    public void init() {
+        System.out.println("Initialized");
+    }
+    
+    public void cleanup() {
+        System.out.println("Cleaned up");
+    }
+}
+```
+
+## Testing Patterns
+
+### Unit Test (No Spring)
+
+```java
+class UserServiceTest {
+    private UserRepository mockRepository;
+    private UserService service;
+    
+    @BeforeEach
+    void setUp() {
+        mockRepository = mock(UserRepository.class);
+        service = new UserService(mockRepository);  // Manual injection
+    }
+    
+    @Test
+    void shouldFetchUser() {
+        User user = new User(1L, "Test");
+        when(mockRepository.findById(1L)).thenReturn(Optional.of(user));
+        
+        User result = service.getUser(1L);
+        assertThat(result).isEqualTo(user);
+    }
+}
+```
+
+### Integration Test (With Spring)
+
+```java
+@SpringBootTest
+@ActiveProfiles("test")
+class UserServiceIntegrationTest {
+    @Autowired
+    private UserService userService;
+    
+    @Autowired
+    private UserRepository userRepository;
+    
+    @BeforeEach
+    void setUp() {
+        userRepository.deleteAll();
+    }
+    
+    @Test
+    void shouldFetchUserFromDatabase() {
+        User user = User.create("test@example.com");
+        userRepository.save(user);
+        
+        User retrieved = userService.getUser(user.getId());
+        assertThat(retrieved.getEmail()).isEqualTo("test@example.com");
+    }
+}
+```
+
+### Slice Test
+
+```java
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+    @Autowired
+    private MockMvc mockMvc;
+    
+    @MockBean  // Mock the service
+    private UserService userService;
+    
+    @Test
+    void shouldReturnUser() throws Exception {
+        User user = new User(1L, "Test");
+        when(userService.getUser(1L)).thenReturn(user);
+        
+        mockMvc.perform(get("/users/1"))
+            .andExpect(status().isOk());
+    }
+}
+```
+
+## Best Practices Summary
+
+| Practice | Recommendation | Why |
+|----------|---|---|
+| Constructor injection | ✅ Mandatory | Explicit, immutable, testable |
+| Setter injection | ⚠️ Optional deps | Clear optionality |
+| Field injection | ❌ Never | Hidden, untestable |
+| @Autowired on constructor | ✅ Implicit (4.3+) | Clear intent |
+| Lombok @RequiredArgsConstructor | ✅ Recommended | Reduces boilerplate |
+| Circular dependencies | ❌ Avoid | Use events instead |
+| Too many dependencies | ❌ Avoid | SRP violation |
+| @Lazy for expensive beans | ✅ Appropriate | Faster startup |
+| Profiles for environments | ✅ Recommended | Environment-specific config |
+| @Value for properties | ✅ Recommended | Type-safe injection |
+
+## External Resources
+
+### Official Documentation
+- [Spring IoC Container](https://docs.spring.io/spring-framework/reference/core/beans.html)
+- [Spring Boot Auto-Configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/using.html#using.auto-configuration)
+- [Conditional Bean Registration](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.developing-auto-configuration.condition-annotations)
+
+### Related Skills
+- **spring-boot-crud-patterns/SKILL.md** - DI in CRUD applications
+- **spring-boot-test-patterns/SKILL.md** - Testing with DI
+- **spring-boot-rest-api-standards/SKILL.md** - REST layer with DI
+
+### Books
+- "Spring in Action" (latest edition)
+- "Spring Microservices in Action"
+
+### Articles
+- [Baeldung Spring Dependency Injection](https://www.baeldung.com/spring-dependency-injection)
+- [Martin Fowler IoC](https://www.martinfowler.com/articles/injection.html)