Developing Your First Spring Boot Application

本部分介绍如何开发一个小型 “Hello World!” Web 应用程序，其中突出显示了 Spring Boot 的一些主要功能。您可以选择 Maven 或 Gradle 作为构建系统。

This section describes how to develop a small “Hello World!” web application that highlights some of Spring Boot’s key features. You can choose between Maven or Gradle as the build system.

spring.io 网站包含许多使用 Spring Boot 的 “Getting Started” guides。如果您需要解决特定问题，请首先查看此处。

The spring.io website contains many “Getting Started” guides that use Spring Boot. If you need to solve a specific problem, check there first.

您可以通过访问 [role="bare"][role="bare"]https://start.spring.io 并从依赖关系搜索器中选择“Web”启动器来简化以下步骤。这样做会生成一个新的项目结构，以便您可以 start coding right away。查看 start.spring.io user guide 以了解更多详情。

You can shortcut the steps below by going to [role="bare"]https://start.spring.io and choosing the "Web" starter from the dependencies searcher. Doing so generates a new project structure so that you can start coding right away. Check the start.spring.io user guide for more details.

Prerequisites

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

Before we begin, open a terminal and run the following commands to ensure that you have a valid version of Java installed:

$ 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)

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

This sample needs to be created in its own directory. Subsequent instructions assume that you have created a suitable directory and that it is your current directory.

Maven

如果您想使用 Maven，请确保您已经安装了 Maven：

If you want to use Maven, ensure that you have Maven installed:

$ 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：

If you want to use Gradle, ensure that you have Gradle installed:

$ 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

Setting up the project with Maven

首先，我们需要创建Maven `pom.xml`文件。`pom.xml`是用于构建项目的配方。打开您偏好的文本编辑器，并添加以下内容：

We need to start by creating a Maven pom.xml file. The pom.xml is the recipe that is used to build your project. Open your favorite text editor and add the following:

<?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>{version-spring-boot}</version>
	</parent>

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

	<!-- (you only need this if you are using a milestone or snapshot version) -->
	<repositories>
		<repository>
			<id>spring-snapshots</id>
			<url>https://repo.spring.io/snapshot</url>
			<snapshots><enabled>true</enabled></snapshots>
		</repository>
		<repository>
			<id>spring-milestones</id>
			<url>https://repo.spring.io/milestone</url>
		</repository>
	</repositories>
	<pluginRepositories>
		<pluginRepository>
			<id>spring-snapshots</id>
			<url>https://repo.spring.io/snapshot</url>
		</pluginRepository>
		<pluginRepository>
			<id>spring-milestones</id>
			<url>https://repo.spring.io/milestone</url>
		</pluginRepository>
	</pluginRepositories>
</project>

前面的清单应该能给你一个可用的构建。你可以通过运行`mvn package`来测试它（暂时，你可以忽略"`jar will be empty - no content was marked for inclusion!`"警告）。

The preceding listing should give you a working build. You can test it by running mvn package (for now, you can ignore the “jar will be empty - no content was marked for inclusion!” warning).

此时，你可以将项目导入IDE（大多数现代Java IDE包含对Maven的内置支持）。为简单起见，我们继续在这个例子中使用一个纯文本编辑器。

At this point, you could import the project into an IDE (most modern Java IDEs include built-in support for Maven). For simplicity, we continue to use a plain text editor for this example.

Setting up the project with Gradle

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

We need to start by creating a Gradle build.gradle file. The build.gradle is the build script that is used to build your project. Open your favorite text editor and add the following:

plugins {
	id 'java'
	id 'org.springframework.boot' version '{version-spring-boot}'
}

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

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

repositories {
	mavenCentral()
	maven { url 'https://repo.spring.io/milestone' }
	maven { url 'https://repo.spring.io/snapshot' }
}

dependencies {
}

前面的清单应该能给你一个可用的构建。你可以通过运行`gradle classes`来测试它。

The preceding listing should give you a working build. You can test it by running gradle classes.

此时，你可以将项目导入IDE（大多数现代Java IDE包含对Gradle的内置支持）。为简单起见，我们继续在这个例子中使用一个纯文本编辑器。

At this point, you could import the project into an IDE (most modern Java IDEs include built-in support for Gradle). For simplicity, we continue to use a plain text editor for this example.

Adding Classpath Dependencies

Spring Boot提供了一些"`Starters`"，使你可以将jar添加到你的类路径。"`Starters`"提供当你开发某种类型应用程序时可能需要的依赖关系。

Spring Boot provides a number of “Starters” that let you add jars to your classpath. “Starters” provide dependencies that you are likely to need when developing a specific type of application.

Maven

大多数Spring Boot应用程序在POM的`parent`部分使用`spring-boot-starter-parent`。spring-boot-starter-parent`是一个特殊的启动器，提供了有用的Maven默认设置。它还提供一个`dependency-management部分，以使你可以省略`version`标签以获取"`blessed`"依赖关系。

Most Spring Boot applications use the spring-boot-starter-parent in the parent section of the POM. The spring-boot-starter-parent is a special starter that provides useful Maven defaults. It also provides a dependency-management section so that you can omit version tags for “blessed” dependencies.

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

Since we are developing a web application, we add a spring-boot-starter-web dependency. Before that, we can look at what we currently have by running the following command:

$ 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`依赖关系：

The mvn dependency:tree command prints a tree representation of your project dependencies. You can see that spring-boot-starter-parent provides no dependencies by itself. To add the necessary dependencies, edit your pom.xml and add the spring-boot-starter-web dependency immediately below the parent section:

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

如果你再次运行`mvn dependency:tree`，你将看到现在增加了一些其他依赖关系，包括Tomcat web服务器和Spring Boot本身。

If you run mvn dependency:tree again, you see that there are now a number of additional dependencies, including the Tomcat web server and Spring Boot itself.

Gradle

大多数Spring Boot应用程序使用`org.springframework.boot`Gradle插件。此插件提供有用的默认配置和Gradle任务。`io.spring.dependency-management`Gradle插件提供dependency management，以使你可以省略`version`标签以获取"`blessed`"依赖关系。

Most Spring Boot applications use the org.springframework.boot Gradle plugin. This plugin provides useful defaults and Gradle tasks. The io.spring.dependency-management Gradle plugin provides dependency management so that you can omit version tags for “blessed” dependencies.

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

Since we are developing a web application, we add a spring-boot-starter-web dependency. Before that, we can look at what we currently have by running the following command:

$ gradle dependencies

> Task :dependencies

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

`gradle dependencies`命令打印出项目依赖关系的树表示。现在，此项目没有依赖关系。要添加必要的依赖关系，编辑你的`build.gradle`并在`dependencies`部分添加`spring-boot-starter-web`依赖关系：

The gradle dependencies command prints a tree representation of your project dependencies. Right now, the project has no dependencies. To add the necessary dependencies, edit your build.gradle and add the spring-boot-starter-web dependency in the dependencies section:

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

如果你再次运行`gradle dependencies`，你将看到现在增加了一些其他依赖关系，包括Tomcat web服务器和Spring Boot本身。

If you run gradle dependencies again, you see that there are now a number of additional dependencies, including the Tomcat web server and Spring Boot itself.

Writing the Code

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

To finish our application, we need to create a single Java file. By default, Maven and Gradle compile sources from src/main/java, so you need to create that directory structure and then add a file named src/main/java/MyApplication.java to contain the following code:

尽管这里的代码不多，但进行了很多处理。我们将在接下来的几部分中逐步了解重要部分。

Although there is not much code here, quite a lot is going on. We step through the important parts in the next few sections.

The @RestController and @RequestMapping Annotations

MyApplication`类中的第一个注释是@RestController`。这被称为_stereotype_注释。它为阅读代码的人员和Spring提示该类扮演一个特定角色。在本例中，我们的类是一个web`@Controller`，因此Spring会在处理传入web请求时考虑它。

The first annotation on our MyApplication class is @RestController. This is known as a stereotype annotation. It provides hints for people reading the code and for Spring that the class plays a specific role. In this case, our class is a web @Controller, so Spring considers it when handling incoming web requests.

@RequestMapping`注释提供"`routing`"信息。它告诉Spring任何具有/路径的HTTP请求都应映射到`home`方法。@RestController`注释告诉Spring直接将结果字符串呈现回调用方。

The @RequestMapping annotation provides “routing” information. It tells Spring that any HTTP request with the / path should be mapped to the home method. The @RestController annotation tells Spring to render the resulting string directly back to the caller.

@RestController`和@RequestMapping`注释是Spring MVC注释（它们不特定于Spring Boot）。有关详细信息，请参阅Spring参考文档中的{url-spring-framework-docs}/web/webmvc.html[MVC部分]。

The @RestController and @RequestMapping annotations are Spring MVC annotations (they are not specific to Spring Boot). See the {url-spring-framework-docs}/web/webmvc.html[MVC section] in the Spring Reference Documentation for more details.

The @SpringBootApplication Annotation

第二个类级注解是 @SpringBootApplication。此注解称为 meta-annotation，它组合了 @SpringBootConfiguration、@EnableAutoConfiguration 和 @ComponentScan。

The second class-level annotation is @SpringBootApplication. This annotation is known as a meta-annotation, it combines @SpringBootConfiguration, @EnableAutoConfiguration and @ComponentScan.

在这些注解中，我们最感兴趣的注解是 @EnableAutoConfiguration。@EnableAutoConfiguration 告诉 Spring Boot 如何 “guess” 配置 Spring，基于已添加的 jar 依赖项。由于 spring-boot-starter-web 添加了 Tomcat 和 Spring MVC，自动配置会假定您正在开发 Web 应用程序并相应地设置 Spring。

Of those, the annotation we’re most interested in here is @EnableAutoConfiguration. @EnableAutoConfiguration tells Spring Boot to “guess” how you want to configure Spring, based on the jar dependencies that you have added. Since spring-boot-starter-web added Tomcat and Spring MVC, the auto-configuration assumes that you are developing a web application and sets up Spring accordingly.

Starters and Auto-configuration

自动配置旨在与 “Starters” 搭配使用，但这两个概念没有直接关联。您可以自由地选择 starter 以外的 jar 依赖项。Spring Boot 仍然会尽力自动配置您的应用程序。

Auto-configuration is designed to work well with “Starters”, but the two concepts are not directly tied. You are free to pick and choose jar dependencies outside of the starters. Spring Boot still does its best to auto-configure your application.

The “main” Method

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

The final part of our application is the main method. This is a standard method that follows the Java convention for an application entry point. Our main method delegates to Spring Boot’s SpringApplication class by calling run. SpringApplication bootstraps our application, starting Spring, which, in turn, starts the auto-configured Tomcat web server. We need to pass MyApplication.class as an argument to the run method to tell SpringApplication which is the primary Spring component. The args array is also passed through to expose any command-line arguments.

Running the Example

Maven

现在，您的应用程序应该可以运行。由于您使用了 spring-boot-starter-parent POM，因此您有一个有用的 run 目标，可用于启动应用程序。从根项目目录键入 mvn spring-boot:run 以启动应用程序。您应该看到类似以下内容的输出：

At this point, your application should work. Since you used the spring-boot-starter-parent POM, you have a useful run goal that you can use to start the application. Type mvn spring-boot:run from the root project directory to start the application. You should see output similar to the following:

$ mvn spring-boot:run

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v{version-spring-boot})
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.906 seconds (process running for 6.514)

如果你用网络浏览器打开 http://localhost:8080，你应该会看到以下输出：

If you open a web browser to http://localhost:8080, you should see the following output:

Hello World!

要正常退出应用程序，请按 ctrl-c。

To gracefully exit the application, press ctrl-c.

Gradle

现在，您的应用程序应该可以运行。由于您使用了 org.springframework.boot Gradle 插件，因此您有一个有用的 bootRun 目标，可用于启动应用程序。从根项目目录键入 gradle bootRun 以启动应用程序。您应该看到类似以下内容的输出：

At this point, your application should work. Since you used the org.springframework.boot Gradle plugin, you have a useful bootRun goal that you can use to start the application. Type gradle bootRun from the root project directory to start the application. You should see output similar to the following:

$ gradle bootRun

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v{version-spring-boot})
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.906 seconds (process running for 6.514)

如果你用网络浏览器打开 http://localhost:8080，你应该会看到以下输出：

If you open a web browser to http://localhost:8080, you should see the following output:

Hello World!

要正常退出应用程序，请按 ctrl-c。

To gracefully exit the application, press ctrl-c.

Creating an Executable Jar

我们通过创建一个完全独立的可执行 jar 文件来完成我们的示例，我们可以在生产环境中运行此文件。可执行 jar（有时称为 “uber jars” 或 “fat jars”）是存档文件，其中包含已编译的类以及代码运行所需的所有 jar 依赖项。

We finish our example by creating a completely self-contained executable jar file that we could run in production. Executable jars (sometimes called “uber jars” or “fat jars”) are archives containing your compiled classes along with all of the jar dependencies that your code needs to run.

Executable jars and Java

Java 不提供加载嵌套 jar 文件（jar 文件本身包含在 jar 中的 jar 文件）的标准方法。如果您希望分发独立的应用程序，这可能会带来问题。

Java does not provide a standard way to load nested jar files (jar files that are themselves contained within a jar). This can be problematic if you are looking to distribute a self-contained application.

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

To solve this problem, many developers use “uber” jars. An uber jar packages all the classes from all the application’s dependencies into a single archive. The problem with this approach is that it becomes hard to see which libraries are in your application. It can also be problematic if the same filename is used (but with different content) in multiple jars.

Spring Boot 采用了 different approach，可以让您实际直接嵌套 jar。

Spring Boot takes a different approach and lets you actually nest jars directly.

Maven

要创建可执行 jar，我们需要将 spring-boot-maven-plugin 添加到我们的 pom.xml。为此，请将以下几行插入在 dependencies 部分的正下方：

To create an executable jar, we need to add the spring-boot-maven-plugin to our pom.xml. To do so, insert the following lines just below the dependencies section:

<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，则需要自己声明此配置。请参阅 plugin documentation 了解详情。

The spring-boot-starter-parent POM includes <executions> configuration to bind the repackage goal. If you do not use the parent POM, you need to declare this configuration yourself. See the plugin documentation for details.

保存 pom.xml 并按照如下方式从命令行运行 mvn package：

Save your pom.xml and run mvn package from the command line, as follows:

$ 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:{version-spring-boot}:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

如果您在 target 目录中查找，则应看到 myproject-0.0.1-SNAPSHOT.jar。文件大小应约为 18 MB。如果您想预览内部，可以使用 jar tvf，如下所示：

If you look in the target directory, you should see myproject-0.0.1-SNAPSHOT.jar. The file should be around 18 MB in size. If you want to peek inside, you can use jar tvf, as follows:

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

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

You should also see a much smaller file named myproject-0.0.1-SNAPSHOT.jar.original in the target directory. This is the original jar file that Maven created before it was repackaged by Spring Boot.

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

To run that application, use the java -jar command, as follows:

$ java -jar target/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。

As before, to exit the application, press ctrl-c.

Gradle

要创建可执行 jar，我们需要按照如下方式从命令行运行 gradle bootJar：

To create an executable jar, we need to run gradle bootJar from the command line, as follows:

$ gradle bootJar

BUILD SUCCESSFUL in 639ms
3 actionable tasks: 3 executed

如果您在 build/libs 目录中查找，则应看到 myproject-0.0.1-SNAPSHOT.jar。文件大小应约为 18 MB。如果您想预览内部，可以使用 jar tvf，如下所示：

If you look in the build/libs directory, you should see myproject-0.0.1-SNAPSHOT.jar. The file should be around 18 MB in size. If you want to peek inside, you can use jar tvf, as follows:

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

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

To run that application, use the java -jar command, as follows:

$ 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。

As before, to exit the application, press ctrl-c.