Spring Boot Under the Hood. Part 4: @SpringBootApplication — Three Annotations, Three Mechanisms

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@SpringBootConfiguration
@EnableAutoConfiguration
@ComponentScan(excludeFilters = { 
    @Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class),
    @Filter(type = FilterType.CUSTOM, classes = AutoConfigurationExcludeFilter.class) 
})
public @interface SpringBootApplication {
    // aliases for @ComponentScan
    @AliasFor(annotation = ComponentScan.class, attribute = "basePackages")
    String[] scanBasePackages() default {};

    @AliasFor(annotation = ComponentScan.class, attribute = "basePackageClasses")
    Class<?>[] scanBasePackageClasses() default {};

    // aliases for @EnableAutoConfiguration
    @AliasFor(annotation = EnableAutoConfiguration.class)
    Class<?>[] exclude() default {};

    @AliasFor(annotation = EnableAutoConfiguration.class)
    String[] excludeName() default {};
}

refreshContext()
  └─ AbstractApplicationContext.refresh()
        └─ invokeBeanFactoryPostProcessors()
              └─ ConfigurationClassPostProcessor.postProcessBeanDefinitionRegistry()
                    └─ ConfigurationClassParser.parse()
                          ├─ @SpringBootConfiguration → registerAsConfigClass()
                          ├─ @ComponentScan         → doProcessConfigurationClass() → scan()
                          └─ @EnableAutoConfiguration → AutoConfigurationImportSelector

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Configuration
@Indexed
public @interface SpringBootConfiguration {
    @AliasFor(annotation = Configuration.class)
    boolean proxyBeanMethods() default true;
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Repeatable(ComponentScans.class)
public @interface ComponentScan {
    @AliasFor("basePackages")
    String[] value() default {};

    @AliasFor("value")
    String[] basePackages() default {};

    Class<?>[] basePackageClasses() default {};

    // ...
}

package com.example.myapp;   // ← the root package

@SpringBootApplication
public class MyApplication { }

com.example.myapp
  ├─ MyApplication.java      ← @SpringBootApplication
  ├─ service/
  │    └─ UserService.java   ← @Service  ✅ will be found
  └─ web/
       └─ UserController.java ← @Controller ✅ will be found

com.example.myapp
  └─ MyApplication.java

com.other.service            ← outside the root package
  └─ UserService.java        ← @Service  ❌ NOT found

@SpringBootApplication(scanBasePackages = {"com.example.myapp", "com.other.service"})

@SpringBootApplication(
    scanBasePackageClasses = {MyApplication.class, AnotherMarker.class}
)

public class ClassPathScanningCandidateComponentProvider {
    private final List<TypeFilter> includeFilters = new ArrayList<>();
    private final List<TypeFilter> excludeFilters = new ArrayList<>();

    public Set<BeanDefinition> findCandidateComponents(String basePackage) {
        // 1. Collect all .class files in the package
        // 2. For each, read the metadata (via ASM, not reflection!)
        // 3. Apply the include/exclude filters
        // 4. Return the matching BeanDefinitions
    }
}

public enum FilterType {
    ANNOTATION,        // by annotation
    ASSIGNABLE_TYPE,   // by type (class/interface)
    ASPECTJ,           // by AspectJ expression
    REGEX,             // by regex on the class name
    CUSTOM             // your own TypeFilter
}

// ANNOTATION: include everything annotated with @MyService
@ComponentScan(includeFilters = @Filter(type = FilterType.ANNOTATION, 
    classes = MyService.class))

// ASSIGNABLE_TYPE: include everything that implements Animal
@ComponentScan(includeFilters = @Filter(type = FilterType.ASSIGNABLE_TYPE, 
    classes = Animal.class))

// CUSTOM: your own logic
@ComponentScan(includeFilters = @Filter(type = FilterType.CUSTOM, 
    classes = MyCustomFilter.class))

@ComponentScan(
    useDefaultFilters = false,
    includeFilters = @Filter(type = FilterType.ANNOTATION, 
        classes = MyService.class)
)

@ComponentScan(excludeFilters = { 
    @Filter(type = CUSTOM, classes = TypeExcludeFilter.class),
    @Filter(type = CUSTOM, classes = AutoConfigurationExcludeFilter.class) 
})

public class TypeExcludeFilter implements TypeFilter, BeanFactoryAware {
    @Override
    public boolean match(MetadataReader metadataReader, 
            MetadataReaderFactory metadataReaderFactory) {
        if (this.beanFactory instanceof ListableBeanFactory lbf) {
            Collection<TypeExcludeFilter> filters = lbf.getBeansOfType(
                TypeExcludeFilter.class).values();
            return filters.stream().anyMatch(filter -> 
                filter.match(metadataReader, metadataReaderFactory));
        }
        return false;
    }
}

@Bean
MyExcludeFilter myExcludeFilter() {
    return new MyExcludeFilter();
}

@Override
public boolean match(MetadataReader metadataReader, 
        MetadataReaderFactory factory) {
    return isConfiguration(metadataReader) && isAutoConfiguration(metadataReader);
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@AutoConfigurationPackage
@Import(AutoConfigurationImportSelector.class)
public @interface EnableAutoConfiguration {
    // ...
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@Import(AutoConfigurationPackages.Registrar.class)
public @interface AutoConfigurationPackage { }

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Indexed { }

META-INF/spring.components

com.example.myapp.service.UserService=org.springframework.stereotype.Component
com.example.myapp.web.UserController=org.springframework.stereotype.Component
com.example.myapp.config.AppConfig=org.springframework.context.annotation.Configuration

@SpringBootApplication
@Indexed
public class MyApplication { }

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context-indexer</artifactId>
    <optional>true</optional>
</dependency>

ConfigurationClassPostProcessor.postProcessBeanDefinitionRegistry()
  │
  └─ ConfigurationClassParser.parse()
        │
        ├─ processConfigurationClass(MyApplication.class)
        │     │
        │     ├─ @SpringBootConfiguration → registerAsConfigClass()
        │     │
        │     ├─ @ComponentScan → doProcessConfigurationClass()
        │     │     │
        │     │     ├─ ComponentScanAnnotationParser.parse()
        │     │     │     ├─ basePackages = {pkg(MyApplication)}
        │     │     │     ├─ excludeFilters = [TypeExcludeFilter, AutoConfigurationExcludeFilter]
        │     │     │     └─ useDefaultFilters = true
        │     │     │
        │     │     └─ ClassPathBeanDefinitionScanner.doScan(basePackages)
        │     │           │
        │     │           ├─ CandidateComponentsIndexLoader.loadIndex()   ← @Indexed
        │     │           │     └─ if the index exists → read spring.components
        │     │           │
        │     │           └─ findCandidateComponents(basePackage)
        │     │                 ├─ for each .class:
        │     │                 │     ├─ SimpleMetadataReader (ASM)
        │     │                 │     ├─ isCandidateComponent() → include/exclude
        │     │                 │     └─ if it passes → BeanDefinition
        │     │                 │
        │     │                 └─ registerBeanDefinition()
        │     │
        │     └─ @EnableAutoConfiguration → AutoConfigurationImportSelector
        │           └─ auto-configuration loading   ← Part 5
        │
        └─ ...

public class MyBeanRegistrar implements BeanRegistrar {
    @Override
    public void register(BeanRegistry registry, Environment env) {
        if (env.acceptsProfiles(Profiles.of("dev"))) {
            registry.registerBean("myService", MyService.class);
        }
    }
}