Spring Boot main class in deep sub-package

ID

java.spring_main_class_in_root_package

Severity

info

Remediation Complexity

trivial

Remediation Risk

low

Remediation Effort

low

Resource

Reliability

Language

Java

Tags

best-practice, reliability, spring

Description

Reports @SpringBootApplication classes located in a deep sub-package (more than 3 segments by default). Spring Boot’s component scanning starts from the main class’s package, so placing the entry point in a deep sub-package causes it to miss beans in sibling or parent packages.

Rationale

Spring Boot’s @SpringBootApplication implicitly applies @ComponentScan starting from the package of the annotated class. If the main class is in com.example.web.controller.deep, beans in com.example.service will not be discovered, leading to NoSuchBeanDefinitionException at startup.

// Bad - main class too deep; misses sibling packages
package com.example.web.controller.deep;

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

Remediation

Move the main class to the project root package so that component scanning covers all sub-packages.

// Good - root package covers all sub-packages
package com.example;

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

Configuration

The maximum allowed package depth is configurable via the maxPackageDepth property (default: 3).

References