5 min read

How to structure a spring boot project?

January 26, 2018

Spring boot has no restrictions in structuring your code. as long as you know what you do. But the framework always encourages a conventional code structure for the ease of developers. In this article we will see about the important folders and files in a spring boot project .

Basic Structure

A typical project downloaded from Spring Initializer will look something like below.

+--- src/
|   +--- main/
|   |   +--- java/
|   |   |   +--- com/
|   |   |   |   +--- springhow/
|   |   |   |   |   +--- example/
|   |   |   |   |   |   +--- helloworld/
|   |   |   |   |   |   |   +--- HelloWorldApplication.java
|   |   +--- resources/
|   |   |   +--- application.properties
|   |   |   +--- static/
|   |   |   +--- templates/
|   +--- test/
|   |   +--- java/
|   |   |   +--- com/
|   |   |   |   +--- springhow/
|   |   |   |   |   +--- example/
|   |   |   |   |   |   +--- helloworld/
|   |   |   |   |   |   |   +--- HelloWorldApplicationTest.java
+--- pom.xml

On a higher level, spring follows and encourages basic maven directory structure. Lets see in detail how these folders play out.

Java Source directories.

By default the the java classes should go under src/main/java. This is a maven default and this can be configured using project.build.sourceDirectory .

There are few conventions to follow in order to keep the project clean and maintainable.

Your base package should be in relevance to the groupId and artifactId of your project definition in pom.xml

For example, If the project is defined like this,


Then your root package can be com.springhow.example.helloworld. This way the classes are more organized in a multi module project.

Test sources

Test sources are not different from application source files. These Test classes ( Usually Junit) are created under src/test/java.

Configuration files

The configuration files go under src/main/resources. This is src/test/resources if you need different configuration files in test phase.

By default, SpringApplication will check and load properties from application.properties files in the following locations and add them to the Spring Environment.

  • A /config subdirectory of the current directory.
  • current directory
  • A classpath /config package
  • The classpath root

If the application.properties file is available in multiple places at once, Spring applies precedence exactly in the above order.

spring-boot-maven-plugin moves all the files under src/main/resources to classpath root. So the basic strategy is to keep the file exactly at src/main/resources/application.properties

YAML Support

You can also use application.yml file as an alternative for application.properties.

If the application.properties look like this,


the equivalent application.yml will look something like this.

	path: '/path'
		username: 'user'
		password: 'pass'

Basically its just another way of representing configuration properties. But in a readable way.

Profile specific properties

Environment properties can be activated with per profile basis by creating properties files with pattern application-{profile}.properties.

This way you can have application-dev.properties activated when the application is started wth dev profile.

Static web content

In a spring boot web application, static files like HTML, CSS, JS and IMAGE files can be served directly from any of the following classpath localtions out of the box. No configuration required.

  • /META-INF/resources/
  • /resources/
  • /static/
  • /public/

Note that these are classpath locations not the actual folders. The ideal way of placing your content in these class path is to place them under src/main/resources. Any files kept here are automatically added to the classpath with the exact folder structure.

In simple terms, The file test.html in any of the following paths in project can be accessed using http://localhost:8080/test.html.

  • src/main/java/META-INF/resources/test.html
  • src/main/java/resources/test.html
  • src/main/java/resources/resources/test.html
  • src/main/java/resources/static/test.html
  • src/main/java/resources/public/test.html

If security is enabled, all places except /public/ will go through security filter by default. So if you want any static resources excluded from security, they can simply be placed under src/main/java/resources/public/.

Dynamic web content (Templates)

Spring supports the following template engines by default. These templates can be activated using appropriate spring boot starters.

  • FreeMarker - spring-boot-starter-freemarker
  • Groovy - spring-boot-starter-groovy
  • Thymeleaf - spring-boot-starter-thymeleaf
  • Mustache - spring-boot-starter-mustache

All these template engines will resolve their template files from the path src/main/resources/template .

For Thymeleaf engine, a straight forward code sample would be,

  public String greeting(
      @RequestParam(value = "user") String useName, Model model) {
    model.addAttribute("user", useName);
    return "hello";

This wil use the template file src/main/resources/template/hello.html to render the request http://localhost:8080/hello?user=World.


In a spring boot project, most of modules can be enabled or disabled just by adding a set of starters. For a maintainable code,

  • Only add needed starters. This keeps the application lighter. Unwanted starter may lead to extra autowired beans.
  • Most of the starters ship with their own transitive dependencies. So you may never need to specify versions. Most of the IDE’s already highlight this unwanted version tags.
  • Know your starter dependencies. This way, You may never need to write configurations.

This article mainly concentrates on a maven project structure of a spring boot project. But in most of the cases it is the same for gradle.

In addition to this, You may not need maven or gradle to build and run a spring boot application. Basic java compilation knowledge and enough time and patience to download and manage the dependencies will do.

Raja Anbazhagan

About the author

Raja is a Software Engineer with over 7 years of experience in working with Enterprise Java applications. Lately, He is focused in cloud-based Java applications and serverless technologies. He spends his spare time in stackoverflow.

Browse Categories