Developing Your First Spring Boot Application

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

spring.io 网站包含许多使用 Spring Boot 的 “Getting Started” guides。如果您需要解决特定问题，请首先查看此处。您可以通过访问 [role="bare"][role="bare"]https://start.spring.io 并从依赖关系搜索器中选择“Web”启动器来简化以下步骤。这样做会生成一个新的项目结构，以便您可以 start coding right away。查看 start.spring.io user guide 以了解更多详情。

Prerequisites

在开始之前，打开一个终端并运行以下命令以确保安装了有效的 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

Setting up the project with 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>{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!`"警告）。

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

Setting up the project with Gradle

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

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`来测试它。

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

Adding Classpath Dependencies

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

Maven

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

由于我们正在开发一个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插件提供dependency management，以使你可以省略`version`标签以获取"`blessed`"依赖关系。

由于我们正在开发一个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本身。

Writing the Code

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

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

The @RestController and @RequestMapping Annotations

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

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

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

The @SpringBootApplication Annotation

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

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

Starters and Auto-configuration

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

The “main” Method

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

Running the Example

Maven

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

$ 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，你应该会看到以下输出：

Hello World!

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

Gradle

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

$ 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，你应该会看到以下输出：

Hello World!

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

Creating an Executable Jar

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

Executable jars and Java

Java 不提供加载嵌套 jar 文件（jar 文件本身包含在 jar 中的 jar 文件）的标准方法。如果您希望分发独立的应用程序，这可能会带来问题。为了解决此问题，许多开发人员使用 “uber” jar。一个 uber jar 将应用程序所有依赖项中的所有类打包到单个存档中。这种方法的问题在于，很难看出您的应用程序中有哪些库。如果在多个 jar 中使用相同的文件名（但内容不同），也可能会出现问题。 Spring Boot 采用了 different approach，可以让您实际直接嵌套 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 包含 <executions> 配置，以绑定 repackage 目标。如果您不使用父 POM，则需要自己声明此配置。请参阅 plugin documentation 了解详情。

保存 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:{version-spring-boot}: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 ::  (v{version-spring-boot})
....... . . .
....... . . . (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。