How do I use component scanning in Spring?

By I Wayan Saryada in Spring, Spring Core 0 Comment

Component scanning is how Spring automatically finds your classes and registers them as beans.

Instead of manually creating every bean, you annotate classes with Spring stereotypes like:

@Component
@Service
@Repository
@Controller
@RestController

Then Spring scans selected packages, finds those classes, creates bean instances, and makes them available for dependency injection.

1. Basic Example

import org.springframework.stereotype.Service;

@Service
public class UserService {

    public String getUserName() {
        return "Alice";
    }
}

Because UserService is annotated with @Service, Spring can discover it during component scanning.

You can inject it into another bean:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/user")
    public String getUser() {
        return userService.getUserName();
    }
}

Spring automatically:

  1. finds UserService
  2. creates a UserService bean
  3. finds UserController
  4. creates a UserController bean
  5. injects UserService into UserController

2. Component Scanning in Spring Boot

In Spring Boot, component scanning is usually enabled automatically by @SpringBootApplication.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

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

@SpringBootApplication includes @ComponentScan.

By default, Spring Boot scans:

  • the package containing the main application class
  • all subpackages under it

For example:

com.example.demo
├── MyApplication.java
├── controller
│   └── UserController.java
├── service
│   └── UserService.java
└── repository
    └── UserRepository.java

If MyApplication is in com.example.demo, Spring scans:

com.example.demo
com.example.demo.controller
com.example.demo.service
com.example.demo.repository

This is the recommended structure.

3. Important Package Rule

Your main application class should usually be in the root package.

Good:

com.example.app
├── Application.java
├── user
│   ├── UserController.java
│   └── UserService.java
└── order
    ├── OrderController.java
    └── OrderService.java

Less ideal:

com.example.app.web
└── Application.java

com.example.app.service
└── UserService.java

If Application is inside com.example.app.web, Spring Boot scans com.example.app.web and its subpackages, but not sibling packages like com.example.app.service.

4. Manually Configure Component Scanning

If needed, you can specify packages explicitly with @ComponentScan.

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

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

Or with multiple packages:

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

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

In Spring Boot, you can also place it on your main class:

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

@SpringBootApplication
@ComponentScan(basePackages = {
        "com.example.app",
        "com.example.shared"
})
public class MyApplication {

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

5. Prefer basePackageClasses for Type Safety

Instead of using package names as strings, you can use classes as package markers.

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

@Configuration
@ComponentScan(basePackageClasses = {
        UserService.class,
        SharedComponent.class
})
public class AppConfig {
}

Spring scans the packages where those classes are located.

This is safer than string package names because refactoring tools can update class references.

6. Common Component Annotations

@Component

Generic Spring-managed bean.

import org.springframework.stereotype.Component;

@Component
public class FileStorage {
}

Use this when no more specific annotation fits.

@Service

Business logic or service layer.

import org.springframework.stereotype.Service;

@Service
public class PaymentService {
}

@Repository

Persistence or data access layer.

import org.springframework.stereotype.Repository;

@Repository
public class JdbcUserRepository {
}

For Spring Data JPA, repository interfaces are often detected separately by repository scanning:

import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
}

You usually do not need to add @Repository to Spring Data JPA interfaces.

@Controller

Spring MVC controller that usually returns views.

import org.springframework.stereotype.Controller;

@Controller
public class PageController {
}

@RestController

REST API controller.

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HealthController {

    @GetMapping("/health")
    public String health() {
        return "OK";
    }
}

@RestController is equivalent to @Controller plus @ResponseBody.

7. Injecting Scanned Components

Once a class is discovered by component scanning, inject it using constructor injection.

import org.springframework.stereotype.Service;

@Service
public class OrderService {

    private final PaymentService paymentService;

    public OrderService(PaymentService paymentService) {
        this.paymentService = paymentService;
    }

    public void placeOrder() {
        paymentService.charge();
    }
}

With Lombok:

import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class OrderService {

    private final PaymentService paymentService;

    public void placeOrder() {
        paymentService.charge();
    }
}

8. Excluding Classes from Component Scanning

You can exclude specific classes or patterns.

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

@Configuration
@ComponentScan(
        basePackages = "com.example.app",
        excludeFilters = @ComponentScan.Filter(
                type = FilterType.ASSIGNABLE_TYPE,
                classes = ExperimentalService.class
        )
)
public class AppConfig {
}

You can also exclude by annotation:

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

@Configuration
@ComponentScan(
        basePackages = "com.example.app",
        excludeFilters = @ComponentScan.Filter(
                type = FilterType.ANNOTATION,
                classes = DeprecatedComponent.class
        )
)
public class AppConfig {
}

9. Common Problems

Problem: Bean Not Found

Example error:

No qualifying bean of type 'com.example.UserService' available

Common causes:

  • the class is not annotated with @Component, @Service, etc.
  • the class is outside the scanned package
  • the class is abstract
  • the class has a failing constructor dependency
  • a required profile is not active
  • the bean is excluded by a scan filter

Problem: Controller Endpoint Not Working

Check that:

  • the controller has @Controller or @RestController
  • it is inside a scanned package
  • request mappings are correct
  • Spring MVC is enabled/configured
  • the application started without bean creation errors

Problem: Multiple Beans Found

If multiple scanned classes implement the same interface:

public interface PaymentProcessor {
    void process();
}

import org.springframework.stereotype.Service;

@Service
public class StripePaymentProcessor implements PaymentProcessor {

    @Override
    public void process() {
        // process with Stripe
    }
}

import org.springframework.stereotype.Service;

@Service
public class PaypalPaymentProcessor implements PaymentProcessor {

    @Override
    public void process() {
        // process with PayPal
    }
}

Injection by interface becomes ambiguous:

import org.springframework.stereotype.Service;

@Service
public class CheckoutService {

    public CheckoutService(PaymentProcessor paymentProcessor) {
    }
}

Fix it with @Primary:

import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Service;

@Service
@Primary
public class StripePaymentProcessor implements PaymentProcessor {

    @Override
    public void process() {
        // process with Stripe
    }
}

Or with @Qualifier:

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;

@Service
public class CheckoutService {

    private final PaymentProcessor paymentProcessor;

    public CheckoutService(
            @Qualifier("paypalPaymentProcessor") PaymentProcessor paymentProcessor
    ) {
        this.paymentProcessor = paymentProcessor;
    }
}

10. Quick Rule of Thumb

For most Spring Boot applications:

  1. Put your main application class in the root package.
  2. Put controllers, services, repositories, and components in subpackages.
  3. Annotate classes with the right stereotype annotation.
  4. Use constructor injection.
  5. Avoid custom @ComponentScan unless you really need it.

A typical structure:

com.example.app
├── Application.java
├── controller
│   └── UserController.java
├── service
│   └── UserService.java
├── repository
│   └── UserRepository.java
└── config
    └── AppConfig.java

With this structure, Spring Boot component scanning usually works with no extra configuration.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.