Spring Boot application bootstrap: package boundaries and startup failures

This lesson uses the downloadable source kit: Java 21, Spring Boot 4.0.8 and its managed Spring Framework 7 dependencies. The version is pinned for repeatable builds.

Place the root class deliberately

ReceiptApplication lives in in.aitrove.learning with the controller, service and configuration classes in that package. The application annotation uses that location as a default scan boundary. Moving one class outside it can leave a dependency missing even though the source compiles.

The kit declares the main class in the Maven Boot plugin because several standalone teaching programs also contain main methods. An ambiguous entrypoint should fail packaging visibly rather than choose an unrelated example class.

Read the first failure

Configuration binding, missing collaborators or server binding can stop startup. Do not diagnose the final wrapper exception alone; find the causal failure and the component it names. The integration tests start the server on port zero and read the assigned local port, avoiding a guessed fixed port.

Boot supplies assembly defaults around Spring Framework. It does not replace Java’s type, thread or exception contracts. Follow the context lesson before treating auto-configuration as an unexplained source of objects.

Checked source

package in.aitrove.learning;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
@SpringBootApplication
@EnableConfigurationProperties(ImportConfiguration.class)
public class ReceiptApplication {
    public static void main(String[] args) { SpringApplication.run(ReceiptApplication.class, args); }
}

Test the boundary

Run mvn test in the source-kit directory. HttpSecurityBoundaryTest checks the behavior described here. Java excerpts belong to the named source-kit classes; they are not independent source files unless the complete class is shown.

Costs and boundaries

Starting the application initializes the web stack, security, validation and datasource. Startup and shutdown are integration concerns; a direct report unit test does not need that cost.

Common Mistakes

• Keep the scan boundary intentional.
• Declare the correct entrypoint when a kit contains multiple main classes.
• Read causal failures before changing unrelated properties.

Read next

Auto configuration, Configuration properties, Java Maven builds: compiler release and dependency scope.