Component Scanning

Analogy categoryAnalogies

How Component Scanning Works

Component scanning is the process by which Spring inspects the classpath for classes annotated with @Component (or one of its specializations like @Service, @Repository, @Controller) and automatically registers them as bean definitions without requiring explicit XML or Java configuration for each one. A Spring Boot application enables this implicitly through @SpringBootApplication, which bundles @ComponentScan and defaults its scan base to the package containing the main application class and all sub-packages beneath it.

🏏

Cricket analogy: A national selection committee scours domestic Ranji Trophy matches for standout performances rather than requiring each player to individually apply for selection, similar to how component scanning automatically discovers annotated classes rather than requiring manual registration.

@ComponentScan and Base Packages

@ComponentScan accepts a basePackages (or the type-safe basePackageClasses) attribute that defines the root package(s) to scan; if omitted, it defaults to the package of the annotated configuration class itself. Because @SpringBootApplication is typically placed on a class in the application's root package (e.g., com.example.myapp.MyAppApplication), and package structure convention places feature packages beneath that root (com.example.myapp.orders, com.example.myapp.customers), the default scan reliably picks up the entire application without extra configuration — but classes outside that package tree, such as shared libraries in a different root package, must be explicitly included.

🏏

Cricket analogy: A regional cricket academy's scouts only cover grounds within their assigned state, so a promising player training in a different state's academy won't be spotted unless scouts are explicitly sent there, mirroring how @ComponentScan only finds classes within its configured base package.

java

package com.example.myapp;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

// @SpringBootApplication already includes @ComponentScan defaulting to this package
@SpringBootApplication
// Explicitly include a shared library package outside com.example.myapp
@ComponentScan(basePackages = {
    "com.example.myapp",
    "com.example.sharedlib.audit"
})
public class MyAppApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyAppApplication.class, args);
    }
}

Filtering What Gets Scanned

@ComponentScan supports includeFilters and excludeFilters to precisely control which classes are registered, using filter types such as FilterType.ANNOTATION (match by a custom marker annotation), FilterType.ASSIGNABLE_TYPE (match a specific class or its subtypes), or FilterType.REGEX (match by fully-qualified class name pattern). This is especially useful for excluding test-only stub implementations from a production scan, or for separating a module into scan-enabled 'production' beans versus manually-wired 'legacy' beans that should never be auto-registered.

🏏

Cricket analogy: A domestic T20 league's draft explicitly excludes centrally contracted international players from the auction pool, using an exclusion rule just as excludeFilters removes specific classes from being auto-registered.

By default, @ComponentScan's built-in filters already exclude classes annotated with @Configuration that are themselves discovered as regular components in certain edge cases, and Spring Boot's test slices (like @WebMvcTest) use their own scan restrictions to load only the beans relevant to that test slice, keeping test contexts fast to start.

Component scanning automatically discovers annotated classes on the classpath and registers them as beans without manual configuration.
@SpringBootApplication implicitly includes @ComponentScan, defaulting its base package to the package of the main application class.
Classes outside the default base package tree must be explicitly included via basePackages or basePackageClasses.
includeFilters and excludeFilters give fine-grained control over which classes are scanned, using annotation, type, or regex matching.
Excluding test doubles or legacy manually-wired classes from scanning prevents accidental duplicate or unwanted bean registration.
Spring Boot test slices apply their own narrower scan scope to keep test application contexts fast to start.