Spring Component Scanning: @ComponentScan, Filters, and Base Packages Mastery

Component scanning is the backbone of Spring's auto-discovery mechanism. Since Spring 2.5, @ComponentScan replaced the tedious XML <context:component-scan> configuration, and with Spring Boot's @SpringBootApplication (which meta-annotates @ComponentScan), it's become almost invisible — until it breaks. I've debugged countless production incidents where a bean 'mysteriously' wasn't found, only to discover someone had placed a @Service in a package that wasn't scanned. In a microservices architecture with 200+ modules, scanning misconfiguration can cause silent failures, duplicate beans, or ClassCastException at runtime. This article covers the internals of @ComponentScan, how to use filters effectively, and how to debug scanning issues in large codebases. We'll look at real patterns from payment processing and SaaS billing systems where precise scanning is critical for security and performance. By the end, you'll be able to configure scanning like a senior engineer — not just adding @ComponentScan and hoping for the best.

Understanding @ComponentScan: The Basics

@ComponentScan is an annotation you place on a @Configuration class to tell Spring where to look for components. Without it, Spring would only register beans explicitly defined via @Bean methods or XML. The default behavior scans the package of the annotated class and all subpackages recursively. In Spring Boot, @SpringBootApplication includes @ComponentScan, so you often don't need to add it manually. However, when you have a multi-module project or want to exclude certain packages, you must customize it. For example, if your main application is in com.acme.app and you have a library module in com.acme.lib, you might need to add @ComponentScan("com.acme.lib") to scan that library's beans. The scanning process uses the ASM library to read bytecode, so it doesn't instantiate classes until they're matched. This is efficient for most projects, but scanning thousands of classes can still impact startup time. In Spring 6.x, scanning has been optimized with parallel scanning and caching, but you should still be mindful of the package structure.

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

@Configuration
@ComponentScan(basePackages = {"com.acme.service", "com.acme.repository"})
public class AppConfig {
    // Explicit beans can still be defined here
}

// Alternative using basePackageClasses (type-safe)
@ComponentScan(basePackageClasses = {ServicesMarker.class, RepositoriesMarker.class})
public class AppConfigWithMarkers {
    // Marker interfaces are empty interfaces used solely for package anchoring
}

What the Official Docs Won't Tell You

The official Spring documentation covers the syntax but glosses over real-world pitfalls. Here's what I've learned from production: First, @ComponentScan on a @Configuration class in a library JAR is often ignored unless the importing application explicitly includes it. This is a common source of 'why isn't my bean found?' questions on Stack Overflow. Second, the order of filter evaluation matters: exclude filters are evaluated first, then include filters. If you exclude a package, then include a specific class within it, the exclude wins. Third, useDefaultFilters=false is your friend when you want to disable the default detection of @Component, @Service, etc., and rely solely on custom filters. This is useful in frameworks that define their own component annotations. Fourth, scanning is not transitive across @Import — if you import a configuration from another JAR, its @ComponentScan is not automatically applied. You must either extend the scan or use Spring Boot's auto-configuration. Finally, in Spring Boot 3.x, the scanning algorithm changed to use a more efficient 'candidate class index' when spring.components is present in META-INF. This file is generated by the spring-context-indexer annotation processor, which can dramatically speed up startup for large projects.

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.FilterType;

@Configuration
@ComponentScan(
    basePackages = "com.acme",
    excludeFilters = @ComponentScan.Filter(
        type = FilterType.REGEX,
        pattern = "com\\.acme\\.legacy\\.*"
    ),
    includeFilters = @ComponentScan.Filter(
        type = FilterType.ASSIGNABLE_TYPE,
        classes = {LegacyService.class}
    )
)
public class AppConfig {
    // Even though LegacyService is in com.acme.legacy, it will NOT be included
    // because exclude filters are evaluated first.
}

Using Filters: Include, Exclude, and Custom Types

Filters give you fine-grained control over which classes are registered as beans. There are five filter types: ANNOTATION, ASSIGNABLE_TYPE, ASPECTJ, REGEX, and CUSTOM. ANNOTATION filters match classes annotated with a specific annotation (e.g., @DevProfileOnly). ASSIGNABLE_TYPE matches classes that are assignable to a given type (class or interface). REGEX and ASPECTJ use pattern matching on the fully qualified class name. CUSTOM requires you to implement TypeFilter and is useful for complex logic like checking class metadata or environment variables. In practice, ANNOTATION and REGEX are the most common. For example, in a multi-tenant SaaS application, you might exclude all classes annotated with @TenantSpecific and include them later based on the active tenant. Filters are also used in testing: you can exclude production beans from a test context. Remember that filters are applied during scanning, not at runtime. If you want conditional bean registration based on runtime conditions, use @Conditional instead.

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.FilterType;

@Configuration
@ComponentScan(
    basePackages = "com.acme",
    includeFilters = @ComponentScan.Filter(
        type = FilterType.ANNOTATION,
        classes = {DevOnly.class}
    ),
    excludeFilters = @ComponentScan.Filter(
        type = FilterType.REGEX,
        pattern = "com\\.acme\\.test\\.*"
    ),
    useDefaultFilters = false  // Only include classes with @DevOnly
)
public class AppConfig {
}

// Custom TypeFilter example
public class EnvironmentTypeFilter implements TypeFilter {
    @Override
    public boolean match(MetadataReader metadataReader, 
                         MetadataReaderFactory metadataReaderFactory) {
        return metadataReader.getClassMetadata().getClassName()
            .contains(System.getProperty("env", "dev"));
    }
}

Base Packages: Best Practices and Pitfalls

Choosing the right base packages is crucial for maintainability and performance. The most common mistake is using a single broad package like "com.mycompany". This works for small projects but becomes a nightmare in large codebases. Instead, use multiple specific packages. For example, in a SaaS billing system, you might scan "com.acme.billing.service", "com.acme.billing.repository", and "com.acme.billing.config". Another best practice is to use basePackageClasses with marker interfaces. This is type-safe and survives refactoring: if you move the marker interface, the scan follows it. Avoid using string-based package names that are hardcoded in multiple places; they rot quickly. Also, be aware that scanning is recursive by default. If you have a package with many subpackages, consider whether you need all of them. You can disable recursion by setting @ComponentScan(scopedProxy = ...) but that's not recommended. Instead, be explicit about which packages to scan. Finally, in a multi-module Maven project, each module should have its own @Configuration class with @ComponentScan for its packages, and the main application should import those configurations.

// Marker interface for type-safe scanning
package com.acme.billing.markers;

public interface BillingServicesMarker {}

// In the billing module
package com.acme.billing.config;

@Configuration
@ComponentScan(basePackageClasses = BillingServicesMarker.class)
public class BillingModuleConfig {
}

// In the main application
@SpringBootApplication
@Import(BillingModuleConfig.class)
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Debugging Component Scanning Issues

When a bean isn't found, the first step is to enable debug logging for Spring's component scanning. Add logging.level.org.springframework.context.annotation=DEBUG to your application.properties. This will show you every class being scanned and whether it was registered or rejected. If you see 'Skipped: not a candidate', check if the class is in a scanned package and has the correct annotation. Another common issue is that Spring Boot's @SpringBootApplication scans the package of the main class. If your main class is in com.acme.app, but your service is in com.acme.app.service, it's fine. But if it's in com.acme.other, you need @ComponentScan("com.acme.other"). Also, check for duplicate bean definitions: if two beans of the same type are found, Spring will throw an exception. Use @Primary or @Qualifier to resolve ambiguity. In production, I've seen cases where a bean was not found because the class was compiled with a different Java version or the JAR wasn't on the classpath. Always verify your build output. Finally, use Spring Boot's actuator /beans endpoint to list all registered beans. This is invaluable for debugging.

# Enable debug logging for component scanning
logging.level.org.springframework.context.annotation=DEBUG
logging.level.org.springframework.beans.factory.support=DEBUG

# Optionally, trace even more
logging.level.org.springframework.core.type=TRACE

Advanced: Custom TypeFilter and Conditional Scanning

Sometimes the built-in filter types aren't enough. You might need to include or exclude beans based on runtime environment, feature flags, or class metadata. That's where custom TypeFilter comes in. Implement the TypeFilter interface and define your logic in the match() method. You have access to MetadataReader, which provides class metadata (annotations, superclass, interfaces) and resource metadata (file path, etc.). For example, you could exclude all classes that have a specific method signature, or include classes based on a custom annotation that has a value attribute. Another advanced technique is to combine @ComponentScan with @Conditional. While @Conditional is evaluated at bean registration time (after scanning), you can use a custom TypeFilter that reads environment properties. This gives you compile-time filtering (during scanning) rather than runtime filtering. However, be careful: TypeFilter runs at application startup, so keep the logic fast. Avoid database calls or heavy I/O in TypeFilter.match().

import org.springframework.core.type.classreading.MetadataReader;
import org.springframework.core.type.classreading.MetadataReaderFactory;
import org.springframework.core.type.filter.TypeFilter;

public class FeatureFlagFilter implements TypeFilter {
    private final String featureFlag;

    public FeatureFlagFilter(String featureFlag) {
        this.featureFlag = featureFlag;
    }

    @Override
    public boolean match(MetadataReader metadataReader,
                         MetadataReaderFactory metadataReaderFactory) {
        // Assume we have a class-level annotation @FeatureFlag("new-payment")
        return metadataReader.getAnnotationMetadata()
            .hasAnnotation(FeatureFlag.class.getName()) &&
            Boolean.parseBoolean(
                System.getProperty(featureFlag, "false")
            );
    }
}

// Usage in @ComponentScan
@ComponentScan(
    basePackages = "com.acme",
    includeFilters = @ComponentScan.Filter(
        type = FilterType.CUSTOM,
        classes = FeatureFlagFilter.class
    ),
    useDefaultFilters = false
)

Performance Optimization: Lazy Initialization and Indexing

Component scanning can be a startup bottleneck. In Spring Boot 3.x, there are two main performance levers: lazy initialization and the spring-context-indexer. Lazy initialization (@Lazy at the configuration level) delays bean creation until they're first requested. This can reduce startup time significantly but can also mask dependency issues. Use it judiciously — for example, in a SaaS billing system, you might lazily initialize report generation beans that aren't needed immediately. The spring-context-indexer is a more robust solution. Add the spring-context-indexer dependency and it generates META-INF/spring.components at compile time. Spring then reads this index instead of scanning the classpath, which is much faster. The index includes all candidate classes (those with @Component, etc.) and their stereotypes. Note that if you use custom filters, the indexer might not capture them correctly — you may need to use @Indexed on custom stereotype annotations. Also, for large projects, consider using Spring Boot's 'startup' actuator endpoint to measure where time is spent.

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

<!-- For Gradle -->
// annotationProcessor "org.springframework:spring-context-indexer"

Testing Component Scanning Configuration

Testing your scanning configuration prevents the 'missing bean' incidents that plague production. The simplest test is to use Spring Boot's @SpringBootTest with a narrow context that only loads your configuration. Assert that all expected beans are present using @Autowired fields or ApplicationContext.getBean(). For more granular tests, use @ContextConfiguration with your @Configuration class and @TestPropertySource to override properties. You can also test filters by creating a test configuration with @ComponentScan and verifying that only the expected classes are registered. For example, if you have an exclude filter for test classes, write a test that confirms no test classes are in the context. Another advanced technique is to use the Spring Boot testing library's OutputCapture to verify scan logs. This is useful for debugging why a bean was excluded. Finally, consider using ArchUnit to enforce package scanning rules. ArchUnit can check that no @Service exists outside your scanned packages, preventing future misconfigurations.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.ApplicationContext;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest(classes = AppConfig.class)
class ComponentScanTest {

    @Autowired
    private ApplicationContext context;

    @Test
    void shouldContainExpectedBeans() {
        assertThat(context.containsBean("paymentService")).isTrue();
        assertThat(context.containsBean("legacyService")).isFalse(); // excluded
    }

    @Test
    void shouldNotContainTestBeans() {
        assertThat(context.getBeansWithAnnotation(DevOnly.class)).isEmpty();
    }
}