Project Structure and Configuration

Spring Boot follows the standard Gradle and Maven directory layout and keeps configuration in one place: application.properties or application.yml. This chapter tours a generated project: its layout, the build file, configuration files and profiles.

Directory layout

A Gradle project generated by Initializr looks like this. A Maven project differs only in having pom.xml instead of build.gradle.kts, mvnw instead of gradlew, and build output in target/ instead of build/.

demo/
├── build.gradle.kts          # build settings and dependencies
├── settings.gradle.kts       # project name
├── gradlew, gradlew.bat      # Gradle wrapper
└── src/
    ├── main/
    │   ├── java/com/example/demo/
    │   │   ├── DemoApplication.java   # entry point
    │   │   └── todo/                  # one package per feature
    │   │       ├── TodoController.java
    │   │       ├── TodoService.java
    │   │       └── TodoRepository.java
    │   └── resources/
    │       ├── application.properties # configuration
    │       ├── static/                # static files (CSS, JS, images)
    │       ├── templates/             # server-side templates
    │       └── db/migration/          # Flyway migrations
    └── test/java/com/example/demo/    # tests

The build file

The build file declares the Spring Boot plugin and your dependencies. The Spring Boot and dependency-management plugins (or spring-boot-starter-parent in Maven) pin library versions that are known to work with your Spring Boot release, so individual dependencies carry no version.

// build.gradle.kts (Initializr fills in the plugin versions)
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-webmvc")
    implementation("org.springframework.boot:spring-boot-starter-validation")
    developmentOnly("org.springframework.boot:spring-boot-devtools")
    testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

In the previous generation the web starter was called spring-boot-starter-web and a single spring-boot-starter-test covered testing. The current generation pairs each technology with its own ...-test starter.

The entry point and package rules

Put the class annotated with @SpringBootApplication in your root package. The annotation scans its own package and every subpackage for components, so a class outside com.example.demo is never registered as a bean. Packaging by feature (todo, user) rather than by layer (controller, service) tends to scale better as the codebase grows.

application.properties and application.yml

Configuration lives in src/main/resources/application.properties as key=value pairs. If you prefer YAML, use application.yml instead:

spring:
  application:
    name: demo
  datasource:
    url: jdbc:postgresql://localhost:5432/demo
    username: demo
    password: ${DB_PASSWORD}

server:
  port: 8080

logging:
  level:
    com.example.demo: debug

Placeholders such as ${DB_PASSWORD} pull in other properties or environment variables. Keep secrets like passwords out of the file and pass them as environment variables.

Externalized configuration order

When the same key appears in several places, the more external source wins. The common sources, from lowest to highest priority:

1. application.properties inside the jar
2. Profile-specific files inside the jar (application-prod.properties)
3. Config files outside the jar, in the working directory
4. Environment variables (SERVER_PORT=9090)
5. Command-line arguments (--server.port=9090)

Environment variables follow relaxed binding: upper case with underscores, so spring.datasource.url becomes SPRING_DATASOURCE_URL.

Profiles

Profiles select configuration per environment. Either add the profile to the file name (application-dev.yml, application-prod.yml) or split one file into documents with ---:

spring:
  jpa:
    show-sql: false
---
spring:
  config:
    activate:
      on-profile: dev
  jpa:
    show-sql: true

Choose the active profiles at launch:

./gradlew bootRun --args='--spring.profiles.active=dev'
SPRING_PROFILES_ACTIVE=prod java -jar build/libs/demo-0.0.1-SNAPSHOT.jar

A bean annotated with @Profile("dev") is registered only when that profile is active.

Summary

• Sources go in src/main/java, configuration and static files in src/main/resources, tests in src/test.
• Keep the entry-point class in the root package and organize the rest by feature beneath it.
• Collect settings in application.properties or application.yml, and override them with environment variables and command-line arguments.
• Use profiles for differences between environments.