Spring Boot @ComponentScan Annotation | Customizing Component Scanning

🚀 Introduction: What is @ComponentScan in Spring Boot?

The @ComponentScan annotation in Spring Boot is used to define which packages should be scanned for Spring components such as @Component, @Service, @Repository, and @Controller. It ensures that Spring Boot automatically detects and registers beans in the specified packages.

✅ Key Features of @ComponentScan:
✔ Enables automatic bean detection in specified packages.
✔ Allows including or excluding specific classes and annotations.
✔ Works with custom configurations for selective scanning.
✔ Helps in modularizing large Spring applications.

📌 In this guide, you’ll learn:
✅ How @ComponentScan works in Spring Boot.
✅ How to include or exclude specific packages and classes.
✅ Best practices for organizing component scanning.

1️⃣ How @ComponentScan Works in Spring Boot

By default, Spring Boot scans for components in the package where the main application class is located and its sub-packages.

📌 Example: Default Component Scanning Behavior

1. Spring Boot Main Class (SpringBootApp.java)

@SpringBootApplication
public class SpringBootApp {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootApp.class, args);
    }
}

✅ Spring Boot automatically scans:

• The package where SpringBootApp is located.
• Any sub-packages inside that package.

2️⃣ Customizing Component Scanning Using @ComponentScan

Use @ComponentScan(basePackages = "...") to scan specific packages manually.

📌 Example: Scanning Multiple Packages

@SpringBootApplication
@ComponentScan(basePackages = {"com.example.service", "com.example.repository"})
public class SpringBootApp {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootApp.class, args);
    }
}

✅ Only components inside com.example.service and com.example.repository will be scanned.

3️⃣ Excluding Specific Components from Scanning

Use @ComponentScan(excludeFilters = ...) to prevent certain components from being registered.

📌 Example: Excluding a Specific Class

@SpringBootApplication
@ComponentScan(
    basePackages = "com.example",
    excludeFilters = @ComponentScan.Filter(type = FilterType.ASSIGNABLE_TYPE, value = UserService.class)
)
public class SpringBootApp {
}

✅ UserService will not be registered as a Spring bean.

📌 Example: Excluding an Entire Annotation Type

@ComponentScan(
    basePackages = "com.example",
    excludeFilters = @ComponentScan.Filter(type = FilterType.ANNOTATION, value = Repository.class)
)

✅ All @Repository components will be ignored during scanning.

4️⃣ Using @ComponentScan with @Configuration for Custom Scanning

Instead of placing @ComponentScan in the main class, you can define it inside a @Configuration class.

📌 Example: Custom Configuration for Component Scanning

@Configuration
@ComponentScan(basePackages = {"com.example.service", "com.example.repository"})
public class AppConfig {
}

✅ Keeps scanning logic separate from the main application class.

5️⃣ Using @ComponentScan.Filter to Include Specific Components

Use @ComponentScan(includeFilters = ...) to scan only specific classes or annotations.

📌 Example: Scanning Only @Service Components

@ComponentScan(
    basePackages = "com.example",
    includeFilters = @ComponentScan.Filter(type = FilterType.ANNOTATION, value = Service.class)
)

✅ Only @Service components will be registered.

📌 Example: Scanning Components That Implement an Interface

@ComponentScan(
    basePackages = "com.example",
    includeFilters = @ComponentScan.Filter(type = FilterType.ASSIGNABLE_TYPE, value = CustomService.class)
)

✅ Only beans of type CustomService will be scanned.

6️⃣ @ComponentScan vs Default Scanning in @SpringBootApplication

By default, @SpringBootApplication already includes @ComponentScan, scanning its package and sub-packages.

📌 Example: Default Behavior (No Need for @ComponentScan)

@SpringBootApplication // Includes implicit @ComponentScan
public class SpringBootApp {
}

✅ No need for @ComponentScan unless scanning additional packages.

📌 When to Use @ComponentScan Explicitly?
✔ When components are outside the default package.
✔ When you want to exclude or include specific beans.
✔ When defining custom scanning logic in a configuration class.

7️⃣ Best Practices for Using @ComponentScan

✅ Keep related components in the same package (avoid unnecessary scanning).
✅ Use basePackages only when components are in different packages.
✅ Exclude unnecessary components using excludeFilters to improve performance.
✅ Define @ComponentScan inside a @Configuration class for better separation.
✅ Avoid excessive filters—only filter components when necessary.

🚀 Following these best practices ensures efficient and maintainable component scanning in Spring Boot!

🎯 Summary: When to Use @ComponentScan?

Use Case	When to Use @ComponentScan?
Default scanning	No need—Spring Boot scans from the main class’s package automatically.
Scanning additional packages	Use @ComponentScan(basePackages = "...") to include more packages.
Excluding specific components	Use excludeFilters to ignore unwanted classes or annotations.
Scanning only selected components	Use includeFilters to register only specific components.
Better code organization	Define @ComponentScan in a @Configuration class.

---

📢 Share this guide with developers to help them master @ComponentScan in Spring Boot! 🚀