EasySpring Boot#107 min readJul 11, 2026
Explain Spring Boot project structure.
practice
Question: Explain Spring Boot project structure.
Answer: Spring Boot projects usually follow a simple folder layout: application code in src/main/java, configuration and static files in src/main/resources, and tests in src/test/java. Inside the Java code, we usually group classes by role, such as controller, service, repository, and model, so each part has one clear job.
Interview-Ready Answer: “I organize a Spring Boot project around the standard Maven or Gradle structure. My main application class sits in the root package, and under that I keep controllers, services, repositories, and domain classes in subpackages. I put configuration like application.properties in src/main/resources and tests in src/test/java. The key idea is that Spring scans the root package and its children, so the package layout directly affects which beans are discovered.”
%22%20stroke%3D%22%234f46e5%22%20stroke-width%3D%221.5%22%2F%3E%3Ctext%20x%3D%22500%22%20y%3D%22308%22%20text-anchor%3D%22middle%22%20font-size%3D%2215%22%20font-weight%3D%22bold%22%20fill%3D%22%23ffffff%22%20font-family%3D%22Segoe%20UI%2C%20Arial%2C%20sans-serif%22%3EProject%20Structure%3C%2Ftext%3E%3C%2Fsvg%3E)
What the structure means
Detailed Explanation: A Spring Boot project structure is the way your code and files are arranged so Spring can find classes, load configuration, and keep the app easy to maintain. Think of it as the “floor plan” of the application: not just where files live, but how responsibilities are separated.
- Start with the standard folders. In a Maven or Gradle project,
src/main/javaholds production code,src/main/resourcesholds non-code resources, andsrc/test/javaholds tests. This is the default layout most Spring Boot tools expect. - Place the main class at the root package. The class with
@SpringBootApplicationshould usually be in a top-level package likecom.example.demo. That matters because@SpringBootApplicationperforms component scanning (searching for Spring-managed classes such as@Component,@Service, and@RestController) in its package and subpackages. - Split code by responsibility. A common beginner-friendly layout is
controllerfor HTTP endpoints,servicefor business rules,repositoryfor data access, andmodelordomainfor business objects. This keeps each class focused and easier to test. - Use resources for application settings and UI assets. Files like
application.propertiesorapplication.ymllive insrc/main/resources. Static assets such as CSS, JavaScript, and images go instatic, while server-side templates go intemplates. - Keep tests close to the same package structure. A test class for
ProductServiceshould usually live under the matching package insrc/test/java. This makes it easier to find tests and helps Spring test slices work cleanly.
Why this layout matters
Good structure reduces accidental coupling. If controllers know too much about database code, changes become risky. If packages are organized well, you can replace a repository implementation, add a new endpoint, or test a service without touching unrelated code.
Layered vs feature-based packages
| Style | Best for | Pros | Watch out |
|---|---|---|---|
| Layered | Small to medium apps | Simple, easy to explain | Can spread one feature across many folders |
| Feature-based | Larger apps | Everything for one feature stays together | Can feel unfamiliar at first |
In a layered structure, you might have controller, service, and repository packages. In a feature-based structure, you might have product, order, and customer packages, and each feature contains its own controller/service/repository classes. Feature-based structure often scales better because changes stay localized.
Under the hood: how Spring Boot uses the structure
- The application starts from the class marked with
@SpringBootApplication. - Spring scans the package containing that class and all subpackages for annotations like
@Serviceand@RestController. - Discovered classes become beans (objects managed by Spring’s container).
- Spring reads
application.propertiesorapplication.ymlto configure ports, database URLs, logging, and more. - Tests under
src/test/javarun with the same package conventions, which helps Spring load only what the test needs.
Performance and edge cases
There is no real algorithmic complexity to memorize here, but package scanning cost grows with the number of classes in scanned packages. In a small app that cost is tiny; in a large app, poor package layout can make startup slower and create accidental bean conflicts. A very common mistake is putting the main class in a nested package such as com.example.demo.app while controllers live in com.example.demo.web; in that case, web is a sibling package, not a child, so it may not be scanned.
Version note: Spring Boot 3 moved from javax.* to jakarta.* for Jakarta EE APIs, and it requires Java 17+. The project structure is the same idea, but older Boot 2 code may use older package names in imports.
Memory Hook: Think of the project as a house: the main class is the front door, subpackages are the rooms, resources are the utilities and furniture, and tests are the smoke detectors. If the front door is in the wrong place, Spring may not “see” the other rooms.
Real-world story
Real-World Example: Imagine a checkout service for an online store. The team keeps CheckoutController in com.shop.checkout.web, CheckoutService in com.shop.checkout.service, and a database repository in com.shop.checkout.repo. During a release, someone moves the main application class to com.shop to “clean up the package,” but forgets to move a new payment controller that lives in com.other.payment.
What happens? The app starts, but the payment endpoint never appears. Users get 404 errors, and logs may show that the controller bean was never created. In a worse case, a service bean is missing and startup fails with an error like UnsatisfiedDependencyException, which means Spring could not inject a required object. This is why package layout is not cosmetic: it directly controls what Spring loads.
Spring Boot
package com.example.demo;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.stereotype.Repository;
import org.springframework.stereotype.Service;
@SpringBootApplication
public class ProjectStructureApplication {
public static void main(String[] args) {
SpringApplication.run(ProjectStructureApplication.class, args);
}
// In real projects this seed logic often lives in a separate configuration class.
// It shows that startup code can sit near the root while business code lives in feature packages.
@org.springframework.context.annotation.Bean
CommandLineRunner seedData(ProductRepository repository) {
return args -> {
repository.save(new Product(null, "Keyboard", 49.99));
repository.save(new Product(null, "Mouse", 19.99));
};
}
}
// Domain object: keeps the business data simple and focused.
record Product(Long id, String name, double price) {}
// Request object: what the API accepts from clients.
record CreateProductRequest(String name, double price) {}
@RestController
@RequestMapping("/products")
class ProductController {
private final ProductService productService;
ProductController(ProductService productService) {
this.productService = productService;
}
@GetMapping
List<Product> all() {
return productService.findAll();
}
@GetMapping("/{id}")
Product one(@PathVariable Long id) {
return productService.findById(id);
}
@PostMapping
ResponseEntity<Product> create(@RequestBody CreateProductRequest request) {
// A small guardrail: reject clearly invalid input instead of saving bad data.
if (request.name() == null || request.name().isBlank()) {
return ResponseEntity.badRequest().build();
}
if (request.price() < 0) {
return ResponseEntity.badRequest().build();
}
Product created = productService.create(request);
return ResponseEntity.status(HttpStatus.CREATED).body(created);
}
}
@Service
class ProductService {
private final ProductRepository productRepository;
ProductService(ProductRepository productRepository) {
this.productRepository = productRepository;
}
List<Product> findAll() {
return productRepository.findAll();
}
Product findById(Long id) {
return productRepository.findById(id)
.orElseThrow(() -> new ProductNotFoundException(id));
}
Product create(CreateProductRequest request) {
return productRepository.save(new Product(null, request.name(), request.price()));
}
}
@Repository
class ProductRepository {
private final Map<Long, Product> store = new ConcurrentHashMap<>();
private final AtomicLong sequence = new AtomicLong(0);
List<Product> findAll() {
return List.copyOf(store.values());
}
java.util.Optional<Product> findById(Long id) {
return java.util.Optional.ofNullable(store.get(id));
}
Product save(Product product) {
long id = product.id() == null ? sequence.incrementAndGet() : product.id();
Product saved = new Product(id, product.name(), product.price());
store.put(id, saved);
return saved;
}
}
class ProductNotFoundException extends RuntimeException {
ProductNotFoundException(Long id) {
super("Product not found: " + id);
}
}
record ApiError(String message) {}
@RestControllerAdvice
class GlobalErrorHandler {
@ExceptionHandler(ProductNotFoundException.class)
ResponseEntity<ApiError> handleNotFound(ProductNotFoundException ex) {
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(new ApiError(ex.getMessage()));
}
}Follow-up & Tricky Questions:
- Q: Why should the
@SpringBootApplicationclass be in the root package? A: Because Spring scans that package and its subpackages for beans. If it sits too deep or in the wrong branch, some controllers or services may not be discovered. - Q: What is the difference between layered and feature-based structure? A: Layered groups by technical role, while feature-based groups by business capability. Feature-based usually scales better for large systems because related code stays together.
- Q: What belongs in
src/main/resources? A: Configuration likeapplication.properties, static files like CSS and images, and templates for server-side rendering. It is not for Java classes. - Q: Why do we keep tests in
src/test/java? A: So test code is separated from production code and can be run independently by the build tool. The package structure usually mirrors the main code to keep tests easy to navigate. - Q: What happens if two beans of the same type exist? A: Spring can fail with a bean ambiguity error unless you mark one as primary or use a qualifier. That is a structure and wiring problem, not just a coding problem.
- Tricky: Can I put the main class in the default package? A: You should not. The default package causes scanning and import problems, and it makes the app harder to maintain and test.
- Tricky: Does Spring scan every package on the classpath? A: No, it scans the package of the main application class and below, unless you explicitly change the scan configuration. That is why package location matters so much.
- Tricky: If
application.propertiesis missing, does the app fail? A: Usually no; Spring Boot has defaults. The file is only needed when you want to override defaults such as the port, datasource URL, or logging level.
Common Mistakes:
- Putting the main class too deep: This can stop Spring from scanning sibling packages. Correction: keep the main class in the top root package.
- Mixing all code in one package: It works at first, but becomes messy fast. Correction: separate controller, service, repository, and domain code, or switch to feature-based packages.
- Storing Java code in
resources: That breaks conventions and confuses the build. Correction: keep Java insrc/main/javaand non-code files insrc/main/resources. - Forgetting test structure: Tests become hard to find and maintain. Correction: mirror the main package structure under
src/test/java.
Memory Hook: “Door, rooms, utilities, detectors.” The main class is the door, packages are rooms, resources are utilities, and tests are the detectors that protect the house.
Cheat Sheet:
src/main/java= app codesrc/main/resources= config, static files, templatessrc/test/java= tests- Main class should be in the root package
- Spring scans the main package and subpackages
- Feature-based structure is often best for larger apps
Practice Tasks:
- Create a tiny Boot app with
controller/service/repositorypackages. - Move the main class to a sibling package and observe which beans stop loading.
- Refactor the same app into feature-based packages like
orderandcustomer.