Spring Boot Internals
Deep Dive

// This is what Spring internally builds from @Service UserService.class
BeanDefinition bd = new RootBeanDefinition(UserService.class);
bd.setScope(BeanDefinition.SCOPE_SINGLETON);
bd.setLazyInit(false);
bd.setAutowireMode(AbstractBeanDefinition.AUTOWIRE_BY_TYPE);
// Constructor dependencies discovered via reflection
bd.getConstructorArgumentValues()
    .addGenericArgumentValue(new RuntimeBeanReference("userRepository"));
bd.setInitMethodName("init");    // if @PostConstruct present
bd.setDestroyMethodName("cleanup"); // if @PreDestroy present

// You can programmatically inspect/modify bean definitions:
ConfigurableApplicationContext ctx = ...;
ConfigurableListableBeanFactory factory = ctx.getBeanFactory();

BeanDefinition userServiceDef = factory.getBeanDefinition("userService");
System.out.println(userServiceDef.getScope());         // singleton
System.out.println(userServiceDef.getBeanClassName()); // com.example.UserService
System.out.println(userServiceDef.isLazyInit());       // false

// Override a bean definition at runtime (useful in tests)
// This is how @TestConfiguration works
GenericBeanDefinition override = new GenericBeanDefinition();
override.setBeanClass(MockUserRepository.class);
((BeanDefinitionRegistry) factory).registerBeanDefinition("userRepository", override);

/**
 * BeanPostProcessor intercepts every bean after creation.
 * Spring uses this same mechanism for @Transactional, @Async, @Cacheable.
 * Here: log the time taken to initialise each bean (startup profiling).
 */
@Component
public class BeanInitTimingPostProcessor implements BeanPostProcessor {

    private final Map<String, Long> startTimes = new ConcurrentHashMap<>();

    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) {
        startTimes.put(beanName, System.currentTimeMillis());
        return bean; // Return the same bean — don't replace it here
    }

    @Override
    public Object postProcessAfterInitialization(Object bean, String beanName) {
        Long start = startTimes.remove(beanName);
        if (start != null) {
            long elapsed = System.currentTimeMillis() - start;
            if (elapsed > 100) { // Log only slow beans
                log.warn("Slow bean init: {} took {}ms", beanName, elapsed);
            }
        }
        return bean; // To wrap with a proxy, return a proxy object here instead
    }
}

/**
 * BeanDefinitionRegistryPostProcessor runs BEFORE beans are instantiated.
 * Use it to programmatically register additional bean definitions.
 * This is how @ComponentScan actually works internally.
 */
@Component
public class CustomBeanRegistrar implements BeanDefinitionRegistryPostProcessor {

    @Override
    public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) {
        // Register a bean programmatically — no @Component annotation needed
        RootBeanDefinition def = new RootBeanDefinition(DynamicService.class);
        def.setScope(BeanDefinition.SCOPE_SINGLETON);
        registry.registerBeanDefinition("dynamicService", def);
    }

    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) {
        // Modify existing bean definitions here
    }
}

org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration
org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration
org.springframework.boot.autoconfigure.kafka.KafkaAutoConfiguration
org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration
# ... 150+ more entries

@AutoConfiguration
@ConditionalOnClass({ DataSource.class, EmbeddedDatabaseType.class })
// Only activate if DataSource.class is on the classpath (spring-jdbc present)
@ConditionalOnMissingBean(type = "io.r2dbc.spi.ConnectionFactory")
// Don't activate if using reactive R2DBC
@EnableConfigurationProperties(DataSourceProperties.class)
@Import({ DataSourcePoolMetadataProvidersConfiguration.class,
          DataSourceInitializationConfiguration.class })
public class DataSourceAutoConfiguration {

    @Configuration(proxyBeanMethods = false)
    @Conditional(EmbeddedDatabaseCondition.class)
    // Activates if an embedded DB (H2, HSQL) is on the classpath
    protected static class EmbeddedDatabaseConfiguration {
        @Bean
        @ConditionalOnMissingBean
        // Only create if NO DataSource bean already exists — user config wins
        public DataSource dataSource(DataSourceProperties properties) {
            return new EmbeddedDatabaseBuilder()
                .setType(properties.determineEmbeddedDatabaseType())
                .build();
        }
    }

    @Configuration(proxyBeanMethods = false)
    @Conditional(PooledDataSourceCondition.class)
    // Activates if HikariCP, Tomcat DBCP, or DBCP2 is on classpath
    protected static class PooledDataSourceConfiguration {
        @Bean
        @ConditionalOnMissingBean
        public DataSource dataSource(DataSourceProperties properties) {
            // DataSourceBuilder picks the best pool (HikariCP preferred)
            return DataSourceBuilder
                .create(properties.getClassLoader())
                .type(properties.getType())
                .url(properties.determineUrl())
                .username(properties.determineUsername())
                .password(properties.determinePassword())
                .build();
        }
    }
}

// The key conditions you see everywhere:
// @ConditionalOnClass(Foo.class)       — class must be on classpath
// @ConditionalOnMissingClass("Foo")    — class must NOT be on classpath
// @ConditionalOnBean(FooService.class) — a FooService bean must exist
// @ConditionalOnMissingBean            — NO bean of this type may exist yet
// @ConditionalOnProperty("app.feature.enabled", havingValue="true")
// @ConditionalOnWebApplication         — must be a web application
// @ConditionalOnExpression("#{...}")   — SpEL expression must be true

@AutoConfiguration
@ConditionalOnClass(AuditService.class)
@ConditionalOnProperty(prefix = "audit", name = "enabled",
                       havingValue = "true", matchIfMissing = true)
@EnableConfigurationProperties(AuditProperties.class)
public class AuditLibraryAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean  // User can override by defining their own AuditService
    public AuditService auditService(AuditProperties props,
                                     ApplicationEventPublisher publisher) {
        return new DefaultAuditService(props, publisher);
    }

    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnBean(DataSource.class)  // Only create if JDBC is available
    public AuditRepository auditRepository(DataSource dataSource) {
        return new JdbcAuditRepository(dataSource);
    }
}

// Register in: src/main/resources/META-INF/spring/
//   org.springframework.boot.autoconfigure.AutoConfiguration.imports
// Content: com.yourlib.audit.AuditLibraryAutoConfiguration

@Service
public class OrderService {

    // BROKEN: self-invocation — @Transactional on processOrder() is IGNORED
    // because this.processOrder() bypasses the proxy
    public void placeAndProcess(Order order) {
        orderRepository.save(order);
        this.processOrder(order); // Calls the REAL object, not the proxy
        // No transaction wraps processOrder() — it runs without a transaction
    }

    @Transactional  // Never fires when called from placeAndProcess above
    public void processOrder(Order order) {
        paymentService.charge(order);
        inventoryService.deduct(order);
    }
}

// FIX 1: Inject self — forces calls through the proxy
@Service
public class OrderService {

    @Autowired
    @Lazy  // Lazy to avoid circular dependency
    private OrderService self; // Injected proxy, not 'this'

    public void placeAndProcess(Order order) {
        orderRepository.save(order);
        self.processOrder(order); // Goes through proxy — @Transactional fires
    }

    @Transactional
    public void processOrder(Order order) { ... }
}

// FIX 2: Extract to a separate bean (cleaner, recommended)
@Service
@RequiredArgsConstructor
public class OrderPlacementService {

    private final OrderService orderService; // Different bean = proxy

    public void placeAndProcess(Order order) {
        orderRepository.save(order);
        orderService.processOrder(order); // Goes through proxy — correct
    }
}

// FIX 3: Use AopContext.currentProxy() — least clean, avoid if possible
@Service
public class OrderService {

    public void placeAndProcess(Order order) {
        ((OrderService) AopContext.currentProxy()).processOrder(order);
        // Requires @EnableAspectJAutoProxy(exposeProxy = true)
    }
}

// This is effectively what Spring generates as your @Transactional proxy:
public class OrderService$$SpringCGLIB$$0 extends OrderService {

    private final TransactionInterceptor txInterceptor; // injected by Spring

    @Override
    public Order placeOrder(CreateOrderRequest request) {
        // Before invocation: begin transaction
        TransactionInfo txInfo = txInterceptor.createTransactionIfNecessary(
            txAttributeSource.getTransactionAttribute(method, targetClass),
            joinpointIdentification
        );

        Object retVal;
        try {
            // Invoke the real method on the actual object
            retVal = super.placeOrder(request); // calls YOUR code

            // After successful return: commit
            txInterceptor.commitTransactionAfterReturning(txInfo);
            return (Order) retVal;

        } catch (Throwable ex) {
            // On exception: rollback (if exception matches rollbackFor)
            txInterceptor.completeTransactionAfterThrowing(txInfo, ex);
            throw ex;
        } finally {
            txInterceptor.cleanupTransactionInfo(txInfo);
        }
    }
}

// Transaction propagation controls what happens when a @Transactional method
// calls another @Transactional method:
//
// REQUIRED (default): join existing tx; create new if none exists
// REQUIRES_NEW:       always suspend current tx; create a brand-new tx
// NESTED:             create a savepoint inside current tx (partial rollback)
// SUPPORTS:           join if exists; run non-transactionally if none
// NOT_SUPPORTED:      always run non-transactionally; suspend current if exists
// MANDATORY:          must run inside existing tx; throw if none
// NEVER:              must NOT run inside tx; throw if one exists

// Spring resolves method parameters using HandlerMethodArgumentResolver.
// @RequestBody uses RequestResponseBodyMethodProcessor internally.
// Here's how to write your own — to inject a custom object from the request:

@Component
public class CurrentTenantArgumentResolver implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        // This resolver handles parameters annotated with @CurrentTenant
        return parameter.hasParameterAnnotation(CurrentTenant.class);
    }

    @Override
    public Object resolveArgument(MethodParameter parameter,
                                   ModelAndViewContainer mavContainer,
                                   NativeWebRequest webRequest,
                                   WebDataBinderFactory binderFactory) {

        HttpServletRequest request =
            (HttpServletRequest) webRequest.getNativeRequest();

        // Extract tenant from JWT claims (already parsed by SecurityFilter)
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (auth instanceof JwtAuthenticationToken jwt) {
            String tenantId = jwt.getToken().getClaimAsString("tenant_id");
            return new TenantContext(tenantId);
        }

        if (parameter.hasParameterAnnotation(CurrentTenant.class) &&
            parameter.getParameterAnnotation(CurrentTenant.class).required()) {
            throw new MissingTenantException("No tenant context in JWT");
        }
        return null;
    }
}

// Register it:
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new CurrentTenantArgumentResolver());
    }
}

// Use it in controllers:
@GetMapping("/orders")
public List<OrderResponse> getOrders(@CurrentTenant TenantContext tenant) {
    return orderService.getOrdersForTenant(tenant.getId());
}

// HttpMessageConverters translate between Java objects and HTTP body bytes.
// MappingJackson2HttpMessageConverter handles JSON.
// You can customise it to change serialisation behaviour globally:

@Configuration
public class JacksonConfig {

    @Bean
    public ObjectMapper objectMapper() {
        return JsonMapper.builder()
            // Serialize dates as ISO-8601 strings, not timestamps
            .configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false)
            // Don't fail on unknown JSON properties
            .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false)
            // Omit null fields from JSON output
            .serializationInclusion(JsonInclude.Include.NON_NULL)
            // Register Java 8 date/time types
            .addModule(new JavaTimeModule())
            // Register Kotlin module if using Kotlin
            // .addModule(new KotlinModule.Builder().build())
            .build();
    }
}

// Custom serialiser for Money value object:
public class MoneySerializer extends JsonSerializer<Money> {

    @Override
    public void serialize(Money money, JsonGenerator gen,
                           SerializerProvider provider) throws IOException {
        gen.writeStartObject();
        gen.writeNumberField("amount",
            money.getAmount().setScale(2, RoundingMode.HALF_UP));
        gen.writeStringField("currency", money.getCurrency());
        gen.writeEndObject();
    }
}
// Result: { "amount": 49.99, "currency": "USD" }
// Instead of the default embedded object serialisation

// When Spring processes @Autowired, it does this (simplified):

public class AutowiredAnnotationBeanPostProcessor implements BeanPostProcessor {

    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) {
        Class<?> clazz = bean.getClass();

        // Walk the entire class hierarchy looking for @Autowired fields
        while (clazz != null && clazz != Object.class) {
            for (Field field : clazz.getDeclaredFields()) {
                if (field.isAnnotationPresent(Autowired.class)) {
                    injectField(field, bean);
                }
            }
            clazz = clazz.getSuperclass();
        }
        return bean;
    }

    private void injectField(Field field, Object bean) {
        // Make the field accessible even if it's private
        field.setAccessible(true); // This bypasses Java access control

        // Resolve the dependency from the bean factory
        Object dependency = beanFactory.getBean(field.getType());

        try {
            field.set(bean, dependency); // Inject via reflection
        } catch (IllegalAccessException e) {
            throw new BeanCreationException("Cannot inject field: " + field.getName());
        }
    }
}

// WHY CONSTRUCTOR INJECTION IS PREFERRED:
// 1. No reflection needed — constructor is called during normal instantiation
// 2. Dependencies are explicit and visible
// 3. Makes the bean testable without a Spring context
// 4. Enforces non-null dependencies at construction time
// 5. Works with Java module system (no setAccessible needed)
//
// @Autowired field injection requires setAccessible(true) —
// this breaks with Java 9+ strong module encapsulation

// Step 1: Define the annotation
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME) // Must be RUNTIME for reflection/AOP to see it
@Documented
public @interface AuditAction {
    String value();          // action name, e.g. "CREATE_ORDER"
    boolean logArgs() default false;
}

// Step 2: Write the AOP aspect that processes the annotation
@Aspect
@Component
@RequiredArgsConstructor
@Slf4j
public class AuditAspect {

    private final AuditEventRepository auditRepository;

    // Pointcut: any method annotated with @AuditAction
    @Around("@annotation(auditAction)")
    public Object auditMethod(ProceedingJoinPoint pjp,
                               AuditAction auditAction) throws Throwable {

        String userId = SecurityContextHolder.getContext()
            .getAuthentication().getName();
        String action = auditAction.value();
        Instant startTime = Instant.now();

        try {
            Object result = pjp.proceed(); // Execute the actual method

            // Record successful audit event
            auditRepository.save(AuditEvent.builder()
                .action(action)
                .userId(userId)
                .status("SUCCESS")
                .durationMs(Duration.between(startTime, Instant.now()).toMillis())
                .arguments(auditAction.logArgs() ?
                    Arrays.toString(pjp.getArgs()) : null)
                .build());

            return result;

        } catch (Exception e) {
            // Record failed audit event
            auditRepository.save(AuditEvent.builder()
                .action(action)
                .userId(userId)
                .status("FAILED")
                .errorMessage(e.getMessage())
                .build());
            throw e; // Re-throw — don't swallow the exception
        }
    }
}

// Step 3: Use it
@RestController
public class OrderController {

    @PostMapping("/orders")
    @AuditAction("CREATE_ORDER")  // Spring AOP intercepts this call
    public OrderResponse placeOrder(@RequestBody CreateOrderRequest request) {
        return orderService.placeOrder(request);
    }
}

// @Configuration classes are CGLIB-proxied to intercept @Bean method calls
// This ensures each @Bean method returns the SAME instance (singleton guarantee)

@Configuration
public class AppConfig {

    @Bean
    public DataSource dataSource() {
        return new HikariDataSource(hikariConfig());
    }

    @Bean
    public HikariConfig hikariConfig() {
        // Returns a new HikariConfig object...
        return new HikariConfig();
    }

    @Bean
    public JdbcTemplate jdbcTemplate() {
        // Calls dataSource() — but thanks to CGLIB proxy,
        // this returns the SAME DataSource bean from the container,
        // NOT a new one. Spring intercepts this call and returns the cached bean.
        return new JdbcTemplate(dataSource());
    }
}
// dataSource() is called twice (once for dataSource bean, once from jdbcTemplate)
// But only ONE DataSource is created. This is the @Configuration proxy magic.

// @Component does NOT get this proxy treatment:
@Component
public class AppConfig {  // NOT @Configuration!

    @Bean
    public DataSource dataSource() { return new HikariDataSource(); }

    @Bean
    public JdbcTemplate jdbcTemplate() {
        // This calls the REAL dataSource() method — creates a SECOND DataSource!
        // Two connection pools! Two separate databases! Memory leak!
        return new JdbcTemplate(dataSource());
    }
}
// Rule: ALWAYS use @Configuration (not @Component) for classes with @Bean methods
// that call other @Bean methods. Use @Configuration(proxyBeanMethods=false)
// only when you are certain no @Bean method calls another @Bean method.

// BROKEN: Circular dependency with constructor injection (throws BeanCreationException)
@Service
public class ServiceA {
    public ServiceA(ServiceB b) { ... } // A needs B
}

@Service
public class ServiceB {
    public ServiceB(ServiceA a) { ... } // B needs A — circular!
}
// Spring throws: The dependencies of some of the beans in the application context
// form a cycle: serviceA → serviceB → serviceA

// Spring CAN resolve circular dependencies with FIELD injection (it uses
// a "early reference" cache of partially-constructed beans), but this is
// a code smell indicating poor design.

// CORRECT FIX 1: Break the cycle with @Lazy
@Service
public class ServiceA {
    public ServiceA(@Lazy ServiceB b) { ... }
    // ServiceB is created lazily on first call, not at startup
}

// CORRECT FIX 2: Use setter injection for one dependency
@Service
public class ServiceA {
    private ServiceB b;

    @Autowired
    public void setServiceB(ServiceB b) { this.b = b; }
}

// CORRECT FIX 3: Extract shared logic to a third service (best — fixes the design)
@Service
public class SharedService { ... } // Contains what both A and B needed from each other

@Service
public class ServiceA {
    public ServiceA(SharedService shared) { ... }
}

@Service
public class ServiceB {
    public ServiceB(SharedService shared) { ... }
}
// No cycle. Better design. Always prefer this approach.

// Reflection was historically 10-50x slower than direct method calls.
// Modern JVMs (Java 17+) have closed this gap significantly via
// Method Handles and inlining. Spring mitigates remaining costs by:

// 1. Caching reflection lookups
//    Spring caches Method objects, Field objects, and Constructor objects
//    after the first lookup. Subsequent calls use cached references.

// 2. Generating bytecode at startup instead of reflecting at runtime
//    Spring's JIT-friendly code generation means hot paths don't use
//    reflection after the first few invocations.

// 3. AOT compilation (Spring Boot 3.x)
//    @SpringBootApplication AOT processing generates source code for
//    bean registration, eliminating runtime classpath scanning and
//    reflection entirely when compiled to GraalVM native image.

// You can measure reflection overhead with:
// -Djdk.reflect.useDirectMethodHandle=true (Java 17+)
// This switches to MethodHandle-based reflection which is JIT-inlinable

// BENCHMARK (approximate, JVM-warmed):
// Direct method call:       1ns
// Cached Method.invoke():   3-5ns
// Uncached reflection:      100-500ns
// For 10,000 req/s, uncached reflection adds ~5ms/req — noticeable
// For 10,000 req/s, cached reflection adds ~0.05ms/req — negligible

spring:
  # Lazy initialisation: beans created only when first needed, not at startup
  # Reduces startup time by 20-40%, but first request is slower (cold start)
  # Use for non-critical beans. NEVER for beans needed for health checks.
  main:
    lazy-initialization: true

  # Background initialisation: initialise some beans in background threads
  # while other startup work continues in the main thread
  threads:
    virtual:
      enabled: true  # Enable virtual threads (Java 21+) for Tomcat threads

jpa:
  # Disable open-session-in-view (OSIV) — it keeps a DB transaction open
  # for the entire HTTP request lifecycle. Causes connection pool exhaustion.
  # Off by default in Spring Boot 3.x, but check your config.
  open-in-view: false