Your First Spring Boot App: Hello World in Three Minutes

In the previous module you stood up a web app with plain Spring: web.xml, applicationContext.xml, an external Tomcat — none optional. Spring Boot does exactly one thing: it moves all that "ceremony to make the framework run" into jars where someone already wrote it. You create a project, add one dependency, write one class with a main method, and everything else is handled. So this article is not a tour of Boot's features; it is about the eight things that line of SpringApplication.run(...) does for you on your very first run, and how to confirm it really happened.

After this article you should be able to answer three questions:

• Why is there no web.xml in a Boot project? Which dependency does embedded Tomcat actually come out of?
• What are the eight steps behind that single SpringApplication.run() line, and which log line proves "I can browse it now"?
• Why does the fat jar from mvn package run with just java -jar? What must the target machine have preinstalled?

Before writing the first line of Boot code, look back at the "configuration burden checklist" the previous module left behind. To stand up an ordinary web app with plain Spring, you had to prepare all of this:

• A web.xml registering the DispatcherServlet and its init-param
• An applicationContext.xml declaring component scanning, the data source and the transaction manager
• A spring-mvc.xml registering the view resolver and message converters
• Dropping the resulting war into an external Tomcat, installing it, starting it and watching the logs

None of those four is your business. They are all ceremony to make the framework run. Spring Boot removes exactly that ceremony — its official one-liner is Convention over Configuration. In practice it means three things:

The official scaffold start.spring.io is the standard entry point (IDEA's New Project → Spring Initializr hits the same service). Fill in the options by copying this table:

Click Generate, download the zip, extract and open it in IDEA. Note that the Artifact decides the main class name: enter demo and you get DemoApplication.

Those checkboxes on Initializr are nothing more than entries appended to <dependencies>. The generator below follows the exact same assembly rules as this lesson: tick one, the pom changes immediately, and under the output it states why that line exists and what breaks without it.

Suggested path: tick Spring Web only → notice that not a single version number appears outside <parent>; add Data JPA and MySQL driver → count which three entries show up and why the driver is <scope>runtime</scope>; add Lombok → see why its scope is provided.

Open the project and the tree looks like this (the standard Boot skeleton):

Look first at the two key blocks in pom.xml — the parent and the starter:

Of the whole project, the main class is the only one you must write. It is absurdly short, yet every line deserves explanation:

@SpringBootApplication is a "three-in-one" annotation; unwrapped, it is three things:

• The return value of SpringApplication.run(DemoApplication.class, args) is an ApplicationContext — the IoC container itself. You can capture it, e.g. ConfigurableApplicationContext ctx = SpringApplication.run(...), then ctx.getBean(...) to verify wiring
• The main method holds only that one line, yet far more than one line happens: creating the container, loading auto-configuration, starting embedded Tomcat and publishing the ready event are all a chain reaction from it

Create a class under the com.example.demo.controller package:

The @RestController vs @Controller distinction is worth one line on its own: use @Controller to return a view (HTML), use @RestController to return JSON or plain text. Mixing them makes "I returned an object but the browser shows 404, page not found".

This difference is not something you memorise — it is something you press. The kernel experiment below runs all four cases: view shows what happens when @Controller returns hello and Spring goes looking for a template by that name, failing into a whitelabel page; json shows what the very same method writes into the body once the annotation is swapped; missing shows which stage actually pronounces the 404; and string shows how return "ok" is interpreted differently under the two annotations — the real answer to "my endpoint returns a string but the browser says 404".

Run DemoApplication and the console prints something like this (simplified to the real format):

Where does embedded Tomcat come from? It hides in the transitive dependencies of spring-boot-starter-web. Run mvn dependency:tree and you see this tree:

That explains why web.xml is gone: in an external-Tomcat setup the servlet container starts first, then loads your war and reads web.xml; Boot reverses the order — your main starts first and starts Tomcat itself (TomcatServletWebServerFactory does it inside auto-configuration), so servlet registration becomes Java code and no XML descriptor is needed.

That figure squashes the road between "one checkbox ticked" and "port 8080 answers" into two columns. To see how the work is handed along, click through the path below — box 3 is the throat of the whole chain: if the condition fails, the four boxes after it never happen.

The same main class can run three ways, each suited to a different situation:

First package from the project root:

The reason those three steps come in this order is that each one rules out a whole class of cause: a wrong URL means "you knocked on the wrong door"; a package outside the subtree means "the container never saw this class"; a wrong annotation means "your return value was thrown away as a view name". Walk the six frames below and you get the reflex, not the rhyme:

Boot’s failure analyser lays the root cause out as a banner in the middle of the log. The beginner instinct is to read every line top-to-bottom, or to start scrolling the stack trace below it. Both are slow. Only three lines in that banner carry information — click the one that matters:

By default Boot does not restart when you edit code, because the running JVM has already loaded the classes into memory. To get "changes take effect immediately", add spring-boot-devtools:

"Nothing changed" is worth ten explanations, but you only believe it once you have stepped through it. The debug desk below spreads six lines out and refreshes two things on the right as you go: how many HelloController class objects exist in memory, and who loaded them. Watch steps 3 and 6 — one of those numbers never moves, the other resets to zero.

The demo below turns Boot's bean wiring at startup into something interactive. Toggle the conditions and watch the "chain reaction of wiring" — which bean gets skipped because a condition is unmet:

That demo answers "what happens when a condition fails". Step back one question first: how did your HelloController get into the container at all? The beanin scenario plays each of the four entrances — component scanning (the @Component family), @Bean methods, @Import, and whatever auto-configuration registers on your behalf. Its last mode, "when it is not found", is precisely the required a bean that could not be found you will meet in the Section 15 sandbox and the Section 16 error table: the package sits outside the main class's subtree, so the scan never laid eyes on it.

The sandbox above exposes the three condition switches as buttons. Below is the same container with a command line — you type, and the Java kernel running inside your browser answers for real: beans reports the container’s actual state right now, the wiring log after cond is recomputed from scratch, and curl hits the virtual 8080 living in kernel memory.

Walk it in this order and you will watch an unmet condition infect a chain, layer by layer:

1. boot — build the container, read the wiring log and the condition evaluation record
2. beans — all five beans present, every status “已创建 / created”
3. cond jdbcOnClasspath false — pretend JDBC is not on the classpath
4. beans — ask again: which ones now say skipped, which say failed, and why those?
5. curl /api/kernel/query — send the request that reaches the Repository and see what comes back
6. cond jdbcOnClasspath true, then beans once more to confirm the container recovered

The timeline above is what should happen. The kernel demo below actually runs it — the bootrun scenario simulates the whole flow of SpringApplication.run(), and its four buttons each follow one thread:

• The eight steps (full): bootstrapper → banner → create context → prepare environment → post-process → refresh() → start Tomcat → call runners, printing what each step produces
• Events (event): ApplicationStartingEvent → EnvironmentPreparedEvent → ApplicationPreparedEvent → ApplicationStartedEvent → ApplicationReadyEvent. That Started DemoApplication in 1.234 seconds line in your log is the product of ApplicationStartedEvent, which is also the correct hook point for "warm something up once startup finishes"
• Runners (runners): both ApplicationRunner and CommandLineRunner execute after the container is ready and before ApplicationReadyEvent; the former gets an ApplicationArguments wrapper (it can tell option arguments from plain ones), the latter a bare String[]
• Reading a failed start (fail): Boot turns the exception into a boxed report that opens with APPLICATION FAILED TO START, then splits into Description: and Action: blocks. Open this one — it maps directly onto the error table in Section 16

One more thing worth confirming: run() returns a value. The previous module covered the twelve steps of refresh(); Boot simply folds them into step 6 here. To see the container with your own eyes, change main by three lines:

The first time you print that number it will be far larger than you expected — auto-configuration has quietly registered dozens of beans. That exact phenomenon is what the next two articles take apart.

Section 8 said mvn package yields "a fat jar with everything embedded". Why can java -jar run it at all? A plain jar's META-INF/MANIFEST.MF has no Main-Class, so the JVM does not know where to start; and third-party dependencies are invisible to the system class loader anyway — they are packed inside the jar, not sitting in directories on disk. Boot fixes both problems with two moves:

Five of those paths each own one job, and a directory tree is not how that sticks. Play a round instead: pick a location or manifest attribute on the left, then its duty on the right — a wrong pair explains itself immediately.

The fatjar scenario plays each of the four parts: layout walks the directory tree and the two key manifest attributes; loader shows the LaunchedClassLoader lookup order (parent delegation → BOOT-INF/classes → BOOT-INF/lib); run traces the whole sequence from java -jar to the first line of your main; war contrasts a war deployment — you get an extra WEB-INF/lib-provided, where devtools and the container-provided Tomcat land so they never clash with the external container's version.

Your first Boot run most likely trips on one of these two: a port clash, or a bean in the wrong package causing a 404. Change one line on the left, and the right shows you the exact startup log lines:

Every phrase below can be pasted verbatim into a search box — do not abbreviate or paraphrase:

Goal: run a Hello World from scratch and confirm with your own eyes what it did. Three moves: generate, run, verify.

Step one, the complete pom.xml (compare it against what Initializr generated for you):

Step two, the main class must carry this name and live in this package (src/main/java/com/example/demo/DemoApplication.java):

Step three, run mvn spring-boot:run. The expected startup log looks like this (timestamps and versions vary with your machine):

Then verify from a second terminal:

Checklist: ① in the log you can point at which line means "the port is bound" and which means "it is browsable now"; ② both curls return 200; ③ after mvn package, jar tf target/demo-0.0.1-SNAPSHOT.jar shows BOOT-INF/lib/ and META-INF/MANIFEST.MF.

Each variant changes exactly one thing. Afterwards say in your own words what you observed:

1. Three port values: try server.port=8081, then server.port=0, then server.port=abc. You will observe the first two switching ports successfully while the third aborts startup with Failed to bind properties under 'server.port' to int. Do this and Section 15's sandbox suddenly feels real.
2. Deliberately move the main class into a subpackage: relocate DemoApplication to com.example.demo.web, add a com.example.demo.service.HelloService annotated @Service, and @Autowired it from the main class. You will observe immediate failure whose Description: reads required a bean of type 'com.example.demo.service.HelloService' that could not be found — row two of the error table.
3. Kill the banner and count the lost lines: add spring.main.banner-mode=off. You will observe the ASCII art gone and every other log line unchanged — proof the banner participates in no startup step.
4. Add devtools, then edit code: after adding the dependency, change the return value of hello() and save. You will observe a restartedMain thread in the logs — the restart happens on a fresh thread, which is precisely the container rebuild from article #9.

Build yourself a "first Boot workbench" called workbench, using every idea in this article.

• The only dependency is spring-boot-starter-web; pin parent to a real Boot 3 release and set java.version to 17
• Packages: WorkbenchApplication in the root com.example.workbench, subpackages controller / service / common
• Three endpoints: GET /ping returns pong; GET /time returns the current time as a string; GET /echo/{msg} returns the path variable unchanged
• A custom banner.txt containing at least your name and one number
• A CommandLineRunner (declare it as a @Bean on the main class) printing the total bean count once startup completes

Checklist: ① mvn clean package succeeds and java -jar starts; ② all three endpoints return 200 from both browser and curl; ③ your bean-count line appears at the end of the startup log; ④ temporarily moving WorkbenchApplication into controller produces an APPLICATION FAILED TO START report you can paste and explain, then revert; ⑤ your README states the three things this machine needs to run it (JDK, Maven or mvnw, network).