跳到主要内容
版本:3.5.10

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

QWen Max 中英对照 Developing Your First Spring Boot Application

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

提示

spring.io 网站包含许多使用 Spring Boot 的“入门”指南。如果你需要解决某个具体问题,请先在那里查看。

你可以通过访问 start.spring.io 并从依赖项搜索器中选择 “Web” starter 来跳过以下步骤。这样会生成一个新的项目结构,让你可以立即开始编码。更多详细信息,请参阅 start.spring.io 用户指南。

先决条件​

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

$ java -version
openjdk version "17.0.16" 2025-07-15 LTS
OpenJDK Runtime Environment (build 17.0.16+12-LTS)
OpenJDK 64-Bit Server VM (build 17.0.16+12-LTS, mixed mode, sharing)
备注

此示例需要在它自己的目录中创建。后续的说明假定您已创建了一个合适的目录,并且该目录是您的当前目录。

Maven​

如果你想使用 Maven,请确保你已安装 Maven:

$ mvn -v
Apache Maven 3.9.11 (3e54c93a704957b63ee3494413a2b544fd3d825b)
Maven home: /Users/developer/.sdkman/candidates/maven/current
Java version: 17.0.16, vendor: BellSoft, runtime: /Users/developer/.sdkman/candidates/java/17.0.16-librca

Gradle​

如果你想使用 Gradle,请确保已安装 Gradle:

$ gradle --version

------------------------------------------------------------
Gradle 8.14.3
------------------------------------------------------------

Build time: 2025-07-04 13:15:44 UTC
Revision: e5ee1df3d88b8ca3a8074787a94f373e3090e1db

Kotlin: 2.0.21
Groovy: 3.0.24
Ant: Apache Ant(TM) version 1.10.15 compiled on August 25 2024
Launcher JVM: 17.0.16 (BellSoft 17.0.16+12-LTS)
Daemon JVM: /Users/developer/.sdkman/candidates/java/17.0.16-librca (no JDK specified, using current Java home)
OS: Mac OS X 15.7.1 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.5.10</version>
</parent>

<!-- Additional lines to be added here... -->

</project>

前面的清单应该能为你提供一个可工作的构建。

你可以通过运行 mvn package 来测试它(目前,你可以忽略 “jar will be empty - no content was marked for inclusion!” 警告)。

备注

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

使用 Gradle 设置项目​

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

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

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

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

java {
sourceCompatibility = '17'
}

repositories {
mavenCentral()
}

dependencies {
}

前面的清单应该能让你得到一个可工作的构建。你可以通过运行 gradle classes 来测试它。

备注

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

添加 Classpath 依赖​

Spring Boot 提供了许多 starter,可让你将 JAR 添加到 classpath 中。这些 starter 提供了在开发特定类型应用时可能需要的依赖项。

Maven​

大多数 Spring Boot 应用程序在 POM 的 parent 部分使用 spring-boot-starter-parent。spring-boot-starter-parent 是一个特殊的 starter,它提供了有用的 Maven 默认配置。它还提供了一个 dependency-management 部分,这样你就可以省略“受支持”依赖项的 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 插件提供了依赖管理,因此你可以省略“受支持”依赖项的 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。这被称为一种 stereotype(构造型)注解。它为阅读代码的人以及 Spring 框架提供了提示,表明该类扮演着特定的角色。在本例中,我们的类是一个 Web @Controller,因此 Spring 在处理传入的 Web 请求时会考虑这个类。

[@RequestMapping](https://docs.spring.io/spring-framework/docs/6.2.x/javadoc-api/org/springframework/web/bind/annotation/RequestMapping.html) 注解提供了 “路由” 信息。它告诉 Spring,任何路径为 / 的 HTTP 请求都应该映射到 home 方法。[@RestController](https://docs.spring.io/spring-framework/docs/6.2.x/javadoc-api/org/springframework/web/bind/annotation/RestController.html) 注解则告诉 Spring 将方法返回的字符串直接渲染并返回给调用方。

提示

@RestController 和 @RequestMapping 注解是 Spring MVC 的注解(它们并非 Spring Boot 特有)。更多详细信息,请参阅 Spring 参考文档中的 MVC 章节。

@SpringBootApplication 注解​

第二个类级别的注解是 @SpringBootApplication。该注解被称为 元注解(meta-annotation),它组合了 @SpringBootConfiguration、@EnableAutoConfiguration 和 @ComponentScan。

其中,我们在这里最感兴趣的是 @EnableAutoConfiguration 注解。@EnableAutoConfiguration 告诉 Spring Boot 根据你添加的 jar 依赖“猜测”你希望如何配置 Spring。由于 spring-boot-starter-web 引入了 Tomcat 和 Spring MVC,自动配置会假定你正在开发一个 Web 应用程序,并据此对 Spring 进行相应的设置。

Starters 与自动配置

自动配置旨在与 Starters 配合良好,但这两个概念并没有直接绑定。你可以自由地选择和使用 Starters 之外的 jar 依赖。Spring Boot 仍会尽最大努力为你的应用程序进行自动配置。

“main” 方法​

我们应用程序的最后一部分是 main 方法。这是一个遵循 Java 应用程序入口点约定的标准方法。我们的 main 方法通过调用 run 方法,将控制权委托给 Spring Boot 的 SpringApplication 类。SpringApplication 会引导我们的应用程序,启动 Spring,而 Spring 又会启动自动配置的 Tomcat Web 服务器。我们需要将 MyApplication.class 作为参数传递给 run 方法,以告知 SpringApplication 哪个是主 Spring 组件。同时,args 数组也会被传入,以暴露所有命令行参数。

运行示例​

Maven​

此时,你的应用程序应该可以正常运行了。由于你使用了 spring-boot-starter-parent POM,因此拥有一个实用的 run 目标,可用于启动应用程序。从项目根目录下运行 mvn spring-boot:run 来启动应用程序。你应该会看到类似如下的输出:

$ mvn spring-boot:run

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

如果你在 Web 浏览器中打开 [localhost:8080](http://localhost:8080),你应该会看到以下输出:

Hello World!

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

Gradle​

此时,你的应用程序应该可以正常运行了。由于你使用了 org.springframework.boot Gradle 插件,因此拥有一个非常实用的 bootRun 任务,可用于启动应用程序。在项目根目录下执行 gradle bootRun 命令来启动应用。你应该会看到类似如下的输出:

$ gradle bootRun

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

如果你在 Web 浏览器中打开 [localhost:8080](http://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 采用了不同的方法,允许你直接嵌套 JAR 文件。

Maven​

要创建一个可执行的 jar,我们需要将 spring-boot-maven-plugin 添加到 pom.xml 中。为此,请在 dependencies 部分下方插入以下内容:

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

spring-boot-starter-parent POM 包含了用于绑定 repackage 目标的 <executions> 配置。如果你不使用该父 POM,则需要自己声明此配置。详见 插件文档。

保存你的 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.5.10: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.5.10)
....... . . .
....... . . . (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 :: (v{version-spring-boot})
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.999 seconds (process running for 1.253)

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