Why Your SpringBoot Components Aren’t Initialized and How to Fix It

Problem Cause

Spring Boot scans the package of the main application class and its sub‑packages. When the main class resides in com.abc but a common library defines beans in com.def, those beans are invisible to the container, causing initialization failure.

Extended Scenarios

If the main class is placed in a deeper package, components in its parent packages are not scanned, which often leads to startup errors for beginners.

Conversely, you may deliberately keep certain classes outside the scan path; in such cases you can use @ComponentScan with exclusion filters.

Using @ComponentScan

The simplest fix is to declare the packages to scan explicitly. @SpringBootApplication already includes @ComponentScan, so you can provide the desired base packages directly.

@SpringBootApplication
@ComponentScan({"com.abc.xx", "com.def.xx"})
public class SpringBootMainApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootMainApplication.class, args);
    }
}

List the business package first, then the common package. Omit the second entry if the common beans are not required.

Custom Enable Annotation

To avoid hard‑coding package names, create a meta‑annotation that imports a configuration class scanning the common package.

@Component
@ComponentScan("com.def.xx")
public class CommonConfig {
}

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Import(CommonConfig.class)
public @interface EnableCommon {
}

@EnableCommon
@SpringBootApplication
public class SpringBootMainApplication {
    // ...
}

If CommonConfig is already reachable by Spring Boot’s default scan, the custom annotation is unnecessary.

Custom Starter Overview

Spring Boot’s auto‑configuration starters can be packaged as a custom starter to encapsulate the common module’s setup.

Add the auto‑configuration dependency in the starter’s pom.xml:

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-autoconfigure</artifactId>
  </dependency>
</dependencies>

Implement a service (e.g., HelloWorldService) and a properties class annotated with @ConfigurationProperties. Provide an auto‑configuration class that is conditional on the presence of the service.

Register the auto‑configuration in META-INF/spring.factories:

# Auto Configure
org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.secbro.HelloWorldAutoConfiguration

When other projects include this starter, Spring Boot automatically configures and exposes HelloWorldService without additional code.

Conclusion

Use @ComponentScan to resolve package‑visibility problems; a custom meta‑annotation offers a reusable way to group scan settings; and a custom starter provides a higher‑level, automated configuration mechanism. Keep the scan path simple by avoiding multiple top‑level packages in the same project.