开发你的第一个 Spring Boot 应用程序

本文介绍如何开发一个小型的 “Hello World!” Web 应用程序，该程序将突显 Spring Boot 的一些关键特性。你可以选择 Maven 或 Gradle 作为构建系统。

提示：spring.io (opens new window) 网站上有许多使用 Spring Boot 的 “入门指南”(点击查看 (opens new window))。如果你需要解决特定问题，可先到该网站查找。

你可以通过访问 start.spring.io (opens new window) 并从依赖项搜索器中选择 “Web” 启动器来简化以下步骤。这样做会生成一个新的项目结构，以便你可以立即开始编码。更多详细信息请查看 start.spring.io 用户指南 (opens new window)。

# 前提条件

在开始之前，打开终端并运行以下命令，以确保你安装了有效版本的 Java：

$ java -version
openjdk version "17.0.4.1" 2022-08-12 LTS
OpenJDK Runtime Environment (build 17.0.4.1+1-LTS)
OpenJDK 64-Bit Server VM (build 17.0.4.1+1-LTS, mixed mode, sharing)

注意：本示例需要在一个独立的目录中创建。后续说明假设你已经创建了一个合适的目录，并且该目录为当前目录。

# Maven

如果你想使用 Maven，请确保已安装 Maven：

$ mvn -v
Apache Maven 3.8.5 (3599d3414f046de2324203b78ddcf9b5e4388aa0)
Maven home: usr/Users/developer/tools/maven/3.8.5
Java version: 17.0.4.1, vendor: BellSoft, runtime: /Users/developer/sdkman/candidates/java/17.0.4.1-librca

# Gradle

如果你想使用 Gradle，请确保已安装 Gradle：

$ gradle --version

------------------------------------------------------------
Gradle 8.1.1
------------------------------------------------------------

Build time:   2023-04-21 12:31:26 UTC
Revision:     1cf537a851c635c364a4214885f8b9798051175b

Kotlin:       1.8.10
Groovy:       3.0.15
Ant:          Apache Ant(TM) version 1.10.11 compiled on July 10 2021
JVM:          17.0.7 (BellSoft 17.0.7+7-LTS)
OS:           Linux 6.2.12-200.fc37.aarch64 aarch64

# 使用 Maven 设置项目

我们需要先创建一个 Maven 的 pom.xml 文件。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>

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

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

    <!-- 这里将添加额外的行... -->

</project>

上述配置可以让你开始正常构建项目。

你可以通过运行 mvn package 来进行测试（目前，你可以忽略 “jar 将为空 - 没有内容被标记为包含在内！” 的警告）。

注意：此时，你可以将项目导入到 IDE 中（大多数现代 Java IDE 都内置了对 Maven 的支持）。为简单起见，本示例继续使用纯文本编辑器。

# 使用 Gradle 设置项目

我们需要先创建一个 Gradle 的 build.gradle 文件。build.gradle 是用于构建项目的脚本。打开你喜欢的文本编辑器并添加以下内容：

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.4.4'
}

apply plugin: 'io.spring.dependency-management'

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

dependencies {
}

上述配置可以让你开始正常构建项目。你可以通过运行 gradle classes 来进行测试。

注意：此时，你可以将项目导入到 IDE 中（大多数现代 Java IDE 都内置了对 Gradle 的支持）。为简单起见，本示例继续使用纯文本编辑器。

# 添加类路径依赖项

Spring Boot 提供了许多启动器，可让你将 JAR 文件添加到类路径中。启动器提供了你在开发特定类型应用程序时可能需要的依赖项。

# Maven

大多数 Spring Boot 应用程序在 POM 的 parent 部分使用 spring-boot-starter-parent。spring-boot-starter-parent 是一个特殊的启动器，它提供了有用的 Maven 默认配置。它还提供了一个依赖管理 (opens new window) 部分，这样你就可以省略 “可靠” 依赖项的 version 标签。

由于我们正在开发一个 Web 应用程序，所以我们添加一个 spring-boot-starter-web 依赖项。在此之前，我们可以通过运行以下命令查看当前项目的依赖情况：

$ mvn dependency:tree

[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT

mvn dependency:tree 命令会打印出项目依赖的树形结构。你可以看到，spring-boot-starter-parent 本身并不提供任何依赖项。为了添加必要的依赖项，编辑你的 pom.xml 文件，并在 parent 部分之后立即添加 spring-boot-starter-web 依赖项：

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

如果你再次运行 mvn dependency:tree，你会发现现在有了许多额外的依赖项，包括 Tomcat Web 服务器和 Spring Boot 本身。

# Gradle

大多数 Spring Boot 应用程序使用 org.springframework.boot Gradle 插件。该插件提供了实用的默认配置和 Gradle 任务。io.spring.dependency - management Gradle 插件提供了依赖管理 (opens new window)功能，这样你就可以省略 “受支持的” 依赖项的 version 标签。

由于我们正在开发一个 Web 应用程序，因此需要添加 spring - boot - starter - web 依赖项。在添加之前，我们可以通过运行以下命令查看当前项目的依赖情况：

$ gradle dependencies
> Task :dependencies

------------------------------------------------------------
Root project 'myproject'
------------------------------------------------------------

gradle dependencies 命令会打印出项目依赖项的树形结构。目前，该项目没有任何依赖项。要添加必要的依赖项，请编辑 build.gradle 文件，并在 dependencies 部分添加 spring - boot - starter - web 依赖项：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

如果你再次运行 gradle dependencies 命令，就会发现现在有了许多额外的依赖项，其中包括 Tomcat Web 服务器和 Spring Boot 本身。

# 编写代码

为了完成我们的应用程序，我们需要创建一个 Java 文件。默认情况下，Maven 和 Gradle 会从 src/main/java 目录编译源代码，因此你需要创建该目录结构，然后添加一个名为 src/main/java/com/example/MyApplication.java 的文件，并包含以下代码：

package com.example;

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

@RestController
@SpringBootApplication
public class MyApplication {

    @RequestMapping("/")
    String home() {
        return "Hello World!";
    }

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

}

虽然这里的代码不多，但实际上发生了很多事情。我们将在接下来的几节中逐步介绍重要的部分。

# `@RestController` 和 `@RequestMapping` 注解

MyApplication 类上的第一个注解是 @RestController (opens new window)。这是一种所谓的 “原型” 注解。它为阅读代码的人和 Spring 框架提供了提示，表明该类扮演着特定的角色。在这种情况下，我们的类是一个 Web @Controller (opens new window)，因此 Spring 在处理传入的 Web 请求时会考虑到它。

@RequestMapping (opens new window) 注解提供了 “路由” 信息。它告诉 Spring，任何路径为 / 的 HTTP 请求都应该映射到 home 方法。@RestController (opens new window) 注解则告诉 Spring 直接将结果字符串返回给调用者。

提示：@RestController (opens new window) 和 @RequestMapping (opens new window) 注解是 Spring MVC 注解（它们并非 Spring Boot 所特有）。更多详细信息，请参阅 Spring 参考文档中的 MVC 部分 (opens new window)。

# `@SpringBootApplication` 注解

第二个类级注解是 @SpringBootApplication (opens new window)。这是一个 “元注解”，它结合了 @SpringBootConfiguration (opens new window)、@EnableAutoConfiguration (opens new window) 和 @ComponentScan (opens new window)。

在这些注解中，我们最感兴趣的是 @EnableAutoConfiguration (opens new window)。@EnableAutoConfiguration (opens new window) 告诉 Spring Boot 根据你添加的 JAR 依赖项 “猜测” 你希望如何配置 Spring。由于 spring-boot-starter-web 添加了 Tomcat 和 Spring MVC，自动配置会假设你正在开发一个 Web 应用程序，并相应地设置 Spring。

启动器与自动配置：自动配置旨在与启动器配合使用，但这两个概念并非直接相关。你可以自由选择启动器之外的 JAR 依赖项，Spring Boot 仍然会尽力自动配置你的应用程序。

# `main` 方法

应用程序的最后一部分是 main 方法。这是遵循 Java 应用程序入口点约定的标准方法。我们的 main 方法通过调用 run 方法委托给 Spring Boot 的 SpringApplication (opens new window) 类。SpringApplication (opens new window) 会引导我们的应用程序，启动 Spring，进而启动自动配置的 Tomcat Web 服务器。我们需要将 MyApplication.class 作为参数传递给 run 方法，以告知 SpringApplication (opens new window) 哪个是主要的 Spring 组件。args 数组也会被传递，以便公开任何命令行参数。

# 运行示例

# Maven

此时，你的应用程序应该可以正常工作了。由于你使用了 spring-boot-starter-parent POM，你可以使用一个有用的 run 目标来启动应用程序。在项目根目录下，键入 mvn spring-boot:run 以启动应用程序。你应该会看到类似于以下的输出：

$ mvn spring-boot:run

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.4.4)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.906 seconds (process running for 6.514)

如果你打开一个 Web 浏览器，访问 localhost:8080，你应该会看到以下输出：

Hello World!

若要优雅地退出应用程序，请按 ctrl-c。

# Gradle

此时，你的应用程序应该可以正常工作了。由于你使用了 org.springframework.boot Gradle 插件，你可以使用一个有用的 bootRun 目标来启动应用程序。在项目根目录下，键入 gradle bootRun 以启动应用程序。你应该会看到类似于以下的输出：

$ gradle bootRun

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.4.4)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.906 seconds (process running for 6.514)

如果你打开一个 Web 浏览器，访问 localhost:8080，你应该会看到以下输出：

Hello World!

若要优雅地退出应用程序，请按 ctrl-c。

# 创建可执行 JAR 文件

最后，我们将创建一个完全自包含的可执行 JAR 文件，以便在生产环境中运行。可执行 JAR 文件（有时也称为 “uber JAR” 或 “fat JAR”）是一种包含你编译后的类以及代码运行所需的所有 JAR 依赖项的存档文件。

可执行 JAR 与 Java：Java 并未提供一种标准方式来加载嵌套的 JAR 文件（即本身包含在 JAR 文件中的 JAR 文件）。如果你想分发一个自包含的应用程序，这可能会成为一个问题。

为了解决这个问题，许多开发者会使用 “uber JAR”。uber JAR 会将应用程序所有依赖项中的类打包到一个存档文件中。这种方法的问题在于，很难看清应用程序中包含了哪些库。此外，如果多个 JAR 文件中使用了相同的文件名（但内容不同），也会出现问题。

Spring Boot 采用了不同的方法 (opens new window)，允许你直接嵌套 JAR 文件。

# Maven

要创建可执行 JAR 文件，我们需要在 pom.xml 中添加 spring-boot-maven-plugin。为此，在 dependencies 部分之后插入以下行：

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

注意：spring-boot-starter-parent POM 包含了 <executions> 配置，用于绑定 repackage 目标。如果你没有使用父 POM，则需要自己声明此配置。详细信息请参阅插件文档 (opens new window)。

保存 pom.xml 文件，并从命令行运行 mvn package，如下所示：

$ mvn package

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myproject 0.0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] .... ..
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ myproject ---
[INFO] Building jar: /Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- spring-boot-maven-plugin:3.4.4:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

如果你查看 target 目录，应该会看到 myproject-0.0.1-SNAPSHOT.jar 文件。该文件大小约为 18 MB。如果你想查看其内部内容，可以使用 jar tvf 命令，如下所示：

$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar

你还会在 target 目录中看到一个更小的文件，名为 myproject-0.0.1-SNAPSHOT.jar.original。这是 Maven 在被 Spring Boot 重新打包之前创建的原始 JAR 文件。

要运行该应用程序，请使用 java -jar 命令，如下所示：

$ java -jar target/myproject-0.0.1-SNAPSHOT.jar

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.4.4)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.999 seconds (process running for 1.253)

和之前一样，若要退出应用程序，请按 ctrl-c。

# Gradle

要创建可执行 JAR 文件，从命令行运行 gradle bootJar，如下所示：

$ gradle bootJar

BUILD SUCCESSFUL in 639ms
3 actionable tasks: 3 executed

如果你查看 build/libs 目录，应该会看到 myproject-0.0.1-SNAPSHOT.jar 文件。该文件大小约为 18 MB。如果你想查看其内部内容，可以使用 jar tvf 命令，如下所示：

$ jar tvf build/libs/myproject-0.0.1-SNAPSHOT.jar

要运行该应用程序，请使用 java -jar 命令，如下所示：

$ java -jar build/libs/myproject-0.0.1-SNAPSHOT.jar

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.4.4)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.999 seconds (process running for 1.253)

和之前一样，若要退出应用程序，请按 ctrl-c。

祝你变得更强!

编辑

上次更新: 2025/04/01

← Spring框架版本新特性 Spring Boot开发初体验→

开发你的第一个 Spring Boot 应用程序

# 前提条件

# Maven

# Gradle

# 使用 Maven 设置项目

# 使用 Gradle 设置项目

# 添加类路径依赖项

# Maven

# Gradle

# 编写代码

# @RestController 和 @RequestMapping 注解

# @SpringBootApplication 注解

# main 方法

# 运行示例

# Maven

# Gradle

# 创建可执行 JAR 文件

# Maven

# Gradle

# `@RestController` 和 `@RequestMapping` 注解

# `@SpringBootApplication` 注解

# `main` 方法