Spring Boot Project Setup: Maven, Gradle & Best Practices

A well-structured Spring Boot project saves months of pain later.
In Week 1, you learned what Spring Boot is.
Now in Week 2, we’ll set up a real-world Spring Boot project the way professionals do.

This article focuses on clean structure, configuration management, and build tools — not toy examples.

Why Project Setup Matters

Bad project setup leads to:
❌ Messy codebase
❌ Configuration chaos
❌ Hard deployments
❌ Painful scaling

Good setup gives you:
✅ Clean architecture
✅ Easy environment switching
✅ Faster onboarding
✅ Production readiness

Maven vs Gradle (Which One Should You Use?)

Maven Overview

Maven is the most widely used build tool in Spring Boot projects.

Pros:

• Simple XML configuration
• Huge ecosystem
• Easy to learn
• Enterprise standard

Cons:

• Slower builds
• Less flexible than Gradle

Gradle Overview

Gradle is modern and faster, especially for large projects.

Pros:

• Faster build performance
• Groovy/Kotlin DSL
• Highly customizable

Cons:

• Steeper learning curve
• Slightly less beginner-friendly

✅ Recommendation

Use Case

| Use Case               | Tool           |
| ---------------------- | -------------- |
| Beginner / Blog series | **Maven**      |
| Large microservices    | Gradle         |
| Enterprise teams       | Maven / Gradle |

👉 We’ll use Maven in this series.

Creating a Spring Boot Project (Professional Way)

Use Spring Initializr with these settings:

• Project: Maven
• Language: Java
• Spring Boot: Latest stable
• Packaging: Jar
• Java: 17+

Dependencies:

• Spring Web
• Spring Data JPA
• Validation
• Lombok (optional)

Understanding pom.xml (Important Parts)

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.x.x</version>
</parent>

Starter Dependencies Example:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

👉 Starters manage versions, conflicts, and compatibility automatically.

application.properties vs application.yml

application.properties

server.port=8080
spring.datasource.url=jdbc:mysql://localhost:3306/app_db

application.yml (Recommended)

server:
  port: 8080

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/app_db

✅ Why YAML?

• Cleaner
• Hierarchical
• Easier to read
• Less duplication

👉 Use application.yml in production projects.

Environment Profiles (dev, test, prod)

Spring Boot supports environment-based configuration.

Profile Files:

application-dev.yml
application-test.yml
application-prod.yml

Activate Profile:

java -jar app.jar --spring.profiles.active=prod

Or in config:

spring:
  profiles:
    active: dev

Recommended Folder Structure (Clean Architecture)

com.example.app
 ├── config
 ├── controller
 ├── dto
 ├── entity
 ├── repository
 ├── service
 │    └── impl
 ├── exception
 └── util

Why This Structure Works

• Separation of concerns
• Test-friendly
• Scales well
• Easy to onboard developers

Configuration Best Practices 🔐

❌ Don’t Do This

spring:
  datasource:
    password: root123

✅ Do This

spring:
  datasource:
    password: ${DB_PASSWORD}

Set env variable:

export DB_PASSWORD=secret

Logging Configuration (Basic Setup)

Add in application.yml:

logging:
  level:
    root: INFO
    org.springframework.web: DEBUG

This helps during development and debugging.

Running the Application

Using Maven:

mvn spring-boot:run

Packaging:

mvn clean package
java -jar target/app.jar

Common Project Setup Mistakes ❌

• One config file for all environments
• No DTO layer
• No profiles
• Hardcoded secrets
• Mixing controller & service logic

What You Learned in Week 2

✅ Maven vs Gradle
✅ pom.xml essentials
✅ YAML configuration
✅ Profiles (dev/test/prod)
✅ Clean project structure

What’s in Next Week?

👉 Building REST APIs with Spring Boot

We’ll cover:

• Controllers
• DTOs
• Validation
• CRUD APIs
• ResponseEntity best practices

📌 Action Items

✔ Create a clean Spring Boot project
✔ Add environment profiles
✔ Push to GitHub