Pick an app type and Maven or Gradle, see the folder tree, get a starter zip.
Make a project skeleton
Choose what to build and a build tool; the folder tree, file notes and layer picture follow. Click a file to see its starter code, then download the zip and build it right away.
Build a
Build tool
Tests
Folder tree 7 files
src/
main/
java/com/example/hello/
service/
resources/
test/java/com/example/hello/service/
src/main/java/com/example/hello/App.java
The entry point. It reads the settings, passes the command-line argument to the service and prints the result. No rules live here.
package com.example.hello;import com.example.hello.service.GreetingService;import java.io.IOException;import java.io.InputStream;import java.util.Properties;publicclassApp {publicstaticvoidmain(String[] args) throwsIOException {Properties config = newProperties();try (InputStream in = App.class.getResourceAsStream("/app.properties")) {if (in != null) { config.load(in); } }GreetingService service = newGreetingService(config.getProperty("greeting", "Hello"));String name = args.length > 0 ? args[0] : "world";System.out.println(service.greet(name)); }}
Layers
Versions written in the files Java 17 · JUnit 5.11.3 · maven-surefire-plugin 3.5.2 · Gradle 8 or newer. Library files are not inside the zip. Your build tool downloads them on the first build.
Maven and Gradle standard folders
Path
What goes there
src/main/java
The program code. Folders follow the package name (com/example/hello/App.java).
src/main/resources
Files that are not code: settings, messages, images. They end up next to the class files after a build.
src/test/java
Test code. It never goes into the jar you ship.
src/test/resources
Settings and data used only by tests.
pom.xml · build.gradle
The build file: Java version, libraries (dependencies), the class to run, the test tool.
target/ · build/
Where build output appears (Maven uses target, Gradle uses build). Keep it out of git.
Both tools use the same layout, so moving from Maven to Gradle leaves your sources where they are.
Splitting into layers
Separate the part that takes requests, the part that decides rules and the part that stores data. In a web API, api (the controller) calls service, which calls repository, never the other way round.
With that split you can move storage from a file to a database without touching the service, and you can test service rules without a web server.
api reads the request and builds the response; it does no calculations.
service decides the rules and knows nothing about the web or the database.
repository saves and loads. As an interface, it lets you swap a memory version for a database one.
Naming packages
Package names start with a domain you own, written backwards: example.com becomes com.example, followed by the project name.
Use lowercase only. - is not allowed, so my-app becomes myapp or my_app.
No domain? Use an address you control, such as io.github.yourname.
Split by layer (api, service, repository) while small; once it grows, split by feature first (order, member) and by layer inside each.
Four common design patterns and dependency injection
Knowing when to use each matters more than the name. All of this code was run with javac and java 17.
Singleton · when there must be exactly one
For objects like settings that must exist once in the whole program. The constructor is private; you get the object only through get().
Used everywhere for convenience, it turns into a hidden global variable and makes testing hard. Use it only when one is truly required.
Pull a calculation with several variants, like discounts, into an interface and choose one when creating the object. An interface with a single method also accepts a lambda (price -> price - 5000).
When an event such as a restock happens, every registered listener hears about it. The sender does not care whether a listener sends mail or writes a log.
Dependency injection · receiving what you need through the constructor
GreetingService does not create its repository with new; it receives one in the constructor. The real program passes the memory repository, and a test passes a fake written as a lambda.
Frameworks such as Spring do the same job at scale: they find the right object and pass it to this constructor.
Where does test code go in a Maven or Gradle project?
Show the answer
Answer: 2. src/test/java Test code lives in src/test/java. It is compiled only for tests and never ends up in the jar you ship.
Question 2
What do you gain when GreetingService takes its repository in the constructor?
Show the answer
Answer: 2. Tests can pass in a fake repository Because the repository comes from outside, a test can pass a fake (a lambda) and check the service rules without any database.
Questions people ask
Should I pick Maven or Gradle?
Both use the same folder layout. Pick Maven if you like a fixed XML format, Gradle if you prefer short, code-like build files. Following what your team uses is fine.
How do I build the zip I downloaded?
Run mvn package for Maven or gradle build for Gradle inside the project folder. README.md in the zip lists the exact commands.
Why are the libraries not in the zip?
Your build tool downloads libraries such as JUnit on the first build. Their versions are written in the build file.