第一个 Spring Boot 应用

用 Spring Initializr 生成项目

写 Spring Boot 项目不用从零搭。官方提供了一个在线生成器：Spring Initializr，网址 start.spring.io。

打开页面，按下面的配置填：

选项	填写	说明
Project	Maven	构建工具，本教程默认
Language	Java	我们学 Java
Spring Boot	4.1.0	当前基线版本
Group	com.example	公司域名倒写
Artifact	hello-world	项目名，也是 jar 名
Name	hello-world	应用名，默认跟 Artifact 走
Packaging	Jar	打包方式，默认就是 Jar
Java	21	推荐的 LTS 版本
Dependencies	Spring Web	4.x 生成 spring-boot-starter-webmvc

填完点 Generate，浏览器会下载一个 zip 压缩包。解压后用 IDE 打开，项目就建好了。

认识目录结构

解压后的项目长这样：

hello-world/
├── pom.xml                      # Maven 构建配置，声明依赖
├── mvnw / mvnw.cmd              # Maven 包装器，免装 Maven 也能构建
├── HELP.md                      # 官方帮助说明
└── src
    ├── main
    │   ├── java/com/example/helloworld/
    │   │   └── HelloWorldApplication.java   # 主类，应用入口
    │   └── resources/
    │       ├── application.properties       # 配置文件
    │       ├── static/                      # 静态资源（css/js/图片）
    │       └── templates/                   # 页面模板（Thymeleaf 等）
    └── test/java/com/example/helloworld/
        └── HelloWorldApplicationTests.java  # 测试类

核心就三个：pom.xml 管依赖，src/main/java 放代码，src/main/resources 放配置和资源。

mvnw 是 Maven 包装器（Maven Wrapper）。首次运行它会自动下载项目指定版本的 Maven 到 ~/.m2/wrapper，团队里用它保证所有人构建版本一致。平时用 mvn 还是 ./mvnw 都行，效果一样。

看一眼 pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.0</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>hello-world</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <java.version>21</java.version>
    </properties>

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

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

两个关键点：

• 继承 spring-boot-starter-parent：Spring Boot 帮你锁好所有依赖版本。你在 dependencies 里只写坐标，不用管版本号
• spring-boot-starter-webmvc：一个依赖，打包了 Tomcat 和 Spring MVC 全家桶。4.x 的 Web Starter 就是这个名字，旧教程里的 spring-boot-starter-web 是 3.x 及以前的写法

写 Hello World

打开生成的主类 HelloWorldApplication.java，改成这样：

package com.example.helloworld;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class HelloWorldApplication {

    public static void main(String[] args) {
        SpringApplication.run(HelloWorldApplication.class, args);
    }

    @GetMapping("/")
    public String hello() {
        return "Hello World!";
    }
}

三个注解各司其职：

• @SpringBootApplication：声明这是 Spring Boot 应用入口，管自动配置和组件扫描
• @RestController：这个类里的接口直接返回字符串，不走页面模板
• @GetMapping("/")：浏览器访问根路径 / 时，调用 hello() 方法

main 方法里的 SpringApplication.run(...) 负责启动一切：初始化 Spring 容器，启动内嵌 Tomcat。

再写一个接口练手

一个接口不够，再加一个。在同一个类里补上：

@GetMapping("/hello/{name}")
public String sayHello(@PathVariable String name) {
    return "Hello, " + name + "!";
}

{name} 是路径变量。重启应用，访问 http://localhost:8080/hello/码上学，页面会返回：

Hello, 码上学!

路径参数是 REST 接口的基本功，后面第 20 章会系统讲。这里先感受一下：改代码 → 重启 → 看效果，这个循环就是开发日常。

配置文件初体验

src/main/resources/application.properties 是默认配置文件。把常用的两项写上，文件保持完整可复制：

spring.application.name=hello-world
server.port=8080

• spring.application.name：应用名，日志和监控里会显示
• server.port：服务端口，默认 8080

改成 8081 重启，访问 http://localhost:8081/ 一样能看到 Hello World。配置体系是重头戏，第 10 章开始系统讲。配置文件以后会经常改，养成改完就重启验证的习惯，能省很多排查时间。

运行它

在项目根目录执行：

mvn spring-boot:run

第一次运行要下载依赖，稍等片刻。启动日志长这样，逐行看：

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v4.1.0)

Started HelloWorldApplication in 1.5 seconds (process running for 2.1)

中间的 ASCII 图形是 Spring Boot 的启动横幅（Banner），后面有章节专门讲怎么定制它。关键看最后一行：Started 出现，说明应用启动完成。

打开浏览器，访问 http://localhost:8080/，页面显示：

Hello World!

不想开浏览器，命令行里也能测：

curl http://localhost:8080/

Windows 10+ 自带 curl，macOS 和 Linux 一般也都有。

你的第一个 Spring Boot 应用，跑起来了。

启动日志里藏着什么

再看一眼日志，初学者要学会读这几类信息：

• Tomcat started on port 8080：内嵌服务器起来了，端口在这
• Started HelloWorldApplication in 1.5 seconds：启动耗时，排查性能问题先看它
• Port 8080 was already in use：端口被占，最常见的启动失败原因

日志读得懂，遇到问题就不慌。后面章节还会讲日志级别和格式定制。

停止应用

在命令行按 Ctrl+C，应用会优雅退出。再启动时如果报「Port 8080 was already in use」，说明上一个进程没退干净。找到占用端口的进程关掉，或者换个端口。

页面还是接口

Spring Boot 的 Web 应用有两种返回方式：返回字符串或 JSON 给前端程序调用（接口），或者渲染 HTML 页面给人看（配合 Thymeleaf 等模板引擎）。

本教程主线是接口开发，模板引擎放到第 24 章单独讲。先记住：@RestController 返回的是接口数据，不是页面。判断一个接口是页面还是数据，看注解就行。前后端分离是当前主流，接口开发是后端的基本功。

控制台中文乱码

Windows 下控制台输出中文乱码，多半是编码不一致。两个办法：

• 代码和配置文件都按 UTF-8 保存，这是 Java 项目的默认约定
• Windows 控制台执行 chcp 65001 切到 UTF-8，再跑命令

Maven 侧的编码，spring-boot-starter-parent 已经默认配好 UTF-8，一般不用改。

Gradle 用户怎么跑

如果你用的是 Gradle 版本的项目，运行命令对应是：

gradle bootRun

其余步骤完全一样。本教程主线用 Maven，这里点一句，不再重复。

常见问题

• 端口被占用：报错信息会直接告诉你，换端口或清进程（三步处理见 §15）
• 依赖下载失败：检查网络，或确认 Maven 镜像配置正确
• 浏览器访问不了：看日志里 Tomcat 是否真的 started on port 8080
• 改完代码不生效：mvn spring-boot:run 不会自动热更新，改了代码要重新执行命令

跑通了 Hello World，下一章看看项目结构为什么要这么摆。

小结

本章用 Spring Initializr 生成了第一个应用，跑通了 Hello World。排查问题按顺序来：先看日志，再查端口，最后查依赖，日志永远是最可靠的线索。