This guide provides a sampling of how Spring Boot helps you accelerate application development. As you read more Spring Getting Started guides, you will see more use cases for Spring Boot. This guide is meant to give you a quick taste of Spring Boot. If you want to create your own Spring Boot-based project, visit Spring Initializr, fill in your project details, pick your options, and download a bundled up project as a zip file.
What You Will build
You will build a simple web application with Spring Boot and add some useful services to it.
What You Need
About 15 minutes
A favorite text editor or IDE
JDK 1.8 or later
Gradle 4+ or Maven 3.2+
You can also import the code straight into your IDE:
Spring Tool Suite (STS)
IntelliJ IDEA
How to complete this guide
Like most Spring Getting Started guides, you can start from scratch and complete each step or you can bypass basic setup steps that are already familiar to you. Either way, you end up with working code.
To start from scratch, move on to Starting with Spring Initializr.
To skip the basics, do the following:
Download and unzip the source repository for this guide, or clone it using Git: git clone https://github.com/spring-guides/gs-spring-boot.git
cd into gs-spring-boot/initial
Jump ahead to Create a Simple Web Application.
When you finish, you can check your results against the code in gs-spring-boot/complete.
Learn What You Can Do with Spring Boot
Spring Boot offers a fast way to build applications. It looks at your classpath and at the beans you have configured, makes reasonable assumptions about what you are missing, and adds those items. With Spring Boot, you can focus more on business features and less on infrastructure.
The following examples show what Spring Boot can do for you:
Is Spring MVC on the classpath? There are several specific beans you almost always need, and Spring Boot adds them automatically. A Spring MVC application also needs a servlet container, so Spring Boot automatically configures embedded Tomcat.
Is Jetty on the classpath? If so, you probably do NOT want Tomcat but instead want embedded Jetty. Spring Boot handles that for you.
Is Thymeleaf on the classpath? If so, there are a few beans that must always be added to your application context. Spring Boot adds them for you.
These are just a few examples of the automatic configuration Spring Boot provides. At the same time, Spring Boot does not get in your way. For example, if Thymeleaf is on your path, Spring Boot automatically adds a SpringTemplateEngine to your application context. But if you define your own SpringTemplateEngine with your own settings, Spring Boot does not add one. This leaves you in control with little effort on your part.
Spring Boot does not generate code or make edits to your files. Instead, when you start your application, Spring Boot dynamically wires up beans and settings and applies them to your application context.
Starting with Spring Initializr
For all Spring applications, you should start with the Spring Initializr. The Initializr offers a fast way to pull in all the dependencies you need for an application and does a lot of the setup for you. This example needs only the Spring Web dependency. The following image shows the Initializr set up for this sample project:
initializr
The preceding image shows the Initializr with Maven chosen as the build tool. You can also use Gradle. It also shows values of com.example and spring-boot as the Group and Artifact, respectively. You will use those values throughout the rest of this sample.
The following listing shows the pom.xml file that is created when you choose Maven:
<?xml version="1.0" encoding="UTF-8"?>
4.0.0
org.springframework.boot
spring-boot-starter-parent
2.2.2.RELEASE
com.example
spring-boot
0.0.1-SNAPSHOT
spring-boot
Demo project for Spring Boot
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
The following listing shows the build.gradle file that is created when you choose Gradle:
plugins {
id ‘org.springframework.boot’ version ‘2.2.2.RELEASE’
id ‘io.spring.dependency-management’ version ‘1.0.8.RELEASE’
id ‘java’
}
group = ‘com.example’
version = ‘0.0.1-SNAPSHOT’
sourceCompatibility = ‘1.8’
repositories {
mavenCentral()
}
dependencies {
implementation ‘org.springframework.boot:spring-boot-starter-web’
testImplementation(‘org.springframework.boot:spring-boot-starter-test’) {
exclude group: ‘org.junit.vintage’, module: ‘junit-vintage-engine’
}
}
test {
useJUnitPlatform()
}
Create a Simple Web Application
Now you can create a web controller for a simple web application, as the following listing (from src/main/java/com/example/springboot/HelloController.java) shows:
package com.example.springboot;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;
@RestController
public class HelloController {
@RequestMapping("/")
public String index() {
return "Greetings from Spring Boot!";
}
}
The class is flagged as a @RestController, meaning it is ready for use by Spring MVC to handle web requests. @RequestMapping maps / to the index() method. When invoked from a browser or by using curl on the command line, the method returns pure text. That is because @RestController combines @Controller and @ResponseBody, two annotations that results in web requests returning data rather than a view.
Create an Application class
The Spring Initializr creates a simple application class for you. However, in this case, it is too simple. You need to modify the application class to match the following listing (from src/main/java/com/example/springboot/Application.java):
package com.example.springboot;
import java.util.Arrays;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
@Bean
public CommandLineRunner commandLineRunner(ApplicationContext ctx) {
return args -> {
System.out.println("Let's inspect the beans provided by Spring Boot:");
String[] beanNames = ctx.getBeanDefinitionNames();
Arrays.sort(beanNames);
for (String beanName : beanNames) {
System.out.println(beanName);
}
};
}
}
@SpringBootApplication is a convenience annotation that adds all of the following:
@Configuration: Tags the class as a source of bean definitions for the application context.
@EnableAutoConfiguration: Tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings. For example, if spring-webmvc is on the classpath, this annotation flags the application as a web application and activates key behaviors, such as setting up a DispatcherServlet.
@ComponentScan: Tells Spring to look for other components, configurations, and services in the com/example package, letting it find the controllers.
The main() method uses Spring Boot’s SpringApplication.run() method to launch an application. Did you notice that there was not a single line of XML? There is no web.xml file, either. This web application is 100% pure Java and you did not have to deal with configuring any plumbing or infrastructure.
There is also a CommandLineRunner method marked as a @Bean, and this runs on start up. It retrieves all the beans that were created by your application or that were automatically added by Spring Boot. It sorts them and prints them out.
Run the Application
To run the application, run the following command in a terminal window (in the complete) directory:
./gradlew bootRun
If you use Maven, run the following command in a terminal window (in the complete) directory:
./mvnw spring-boot:run
You should see output similar to the following:
Let’s inspect the beans provided by Spring Boot:
application
beanNameHandlerMapping
defaultServletHandlerMapping
dispatcherServlet
embeddedServletContainerCustomizerBeanPostProcessor
handlerExceptionResolver
helloController
httpRequestHandlerAdapter
messageSource
mvcContentNegotiationManager
mvcConversionService
mvcValidator
org.springframework.boot.autoconfigure.MessageSourceAutoConfiguration
org.springframework.boot.autoconfigure.PropertyPlaceholderAutoConfiguration
org.springframework.boot.autoconfigure.web.EmbeddedServletContainerAutoConfiguration
org.springframework.boot.autoconfigure.web.EmbeddedServletContainerAutoConfiguration
EmbeddedTomcat
org.springframework.boot.autoconfigure.web.ServerPropertiesAutoConfiguration
org.springframework.boot.context.embedded.properties.ServerProperties
org.springframework.context.annotation.ConfigurationClassPostProcessor.enhancedConfigurationProcessor
org.springframework.context.annotation.ConfigurationClassPostProcessor.importAwareProcessor
org.springframework.context.annotation.internalAutowiredAnnotationProcessor
org.springframework.context.annotation.internalCommonAnnotationProcessor
org.springframework.context.annotation.internalConfigurationAnnotationProcessor
org.springframework.context.annotation.internalRequiredAnnotationProcessor
org.springframework.web.servlet.config.annotation.DelegatingWebMvcConfiguration
propertySourcesBinder
propertySourcesPlaceholderConfigurer
requestMappingHandlerAdapter
requestMappingHandlerMapping
resourceHandlerMapping
simpleControllerHandlerAdapter
tomcatEmbeddedServletContainerFactory
viewControllerHandlerMapping
You can clearly see org.springframework.boot.autoconfigure beans. There is also a tomcatEmbeddedServletContainerFactory.
Now run the service with curl (in a separate terminal window), by running the following command (shown with its output):
$ curl localhost:8080
Greetings from Spring Boot!
Add Unit Tests
You will want to add a test for the endpoint you added, and Spring Test provides some machinery for that.
If you use Gradle, add the following dependency to your build.gradle file:
testImplementation(‘org.springframework.boot:spring-boot-starter-test’) {
exclude group: ‘org.junit.vintage’, module: ‘junit-vintage-engine’
}
If you use Maven, add the following to your pom.xml file:
org.springframework.boot spring-boot-starter-test test org.junit.vintage junit-vintage-engineNow write a simple unit test that mocks the servlet request and response through your endpoint, as the following listing (from src/test/java/com/example/springboot/HelloControllerTest.java) shows:
package com.example.springboot;
import static org.hamcrest.Matchers.equalTo;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;
@SpringBootTest
@AutoConfigureMockMvc
public class HelloControllerTest {
@Autowired
private MockMvc mvc;
@Test
public void getHello() throws Exception {
mvc.perform(MockMvcRequestBuilders.get("/").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andExpect(content().string(equalTo("Greetings from Spring Boot!")));
}
}
MockMvc comes from Spring Test and lets you, through a set of convenient builder classes, send HTTP requests into the DispatcherServlet and make assertions about the result. Note the use of @AutoConfigureMockMvc and @SpringBootTest to inject a MockMvc instance. Having used @SpringBootTest, we are asking for the whole application context to be created. An alternative would be to ask Spring Boot to create only the web layers of the context by using @WebMvcTest. In either case, Spring Boot automatically tries to locate the main application class of your application, but you can override it or narrow it down if you want to build something different.
As well as mocking the HTTP request cycle, you can also use Spring Boot to write a simple full-stack integration test. For example, instead of (or as well as) the mock test shown earlier, we could create the following test (from src/test/java/com/example/springboot/HelloControllerIT.java):
package com.example.springboot;
import static org.assertj.core.api.Assertions.*;
import java.net.URL;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.boot.web.server.LocalServerPort;
import org.springframework.http.ResponseEntity;
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class HelloControllerIT {
@LocalServerPort
private int port;
private URL base;
@Autowired
private TestRestTemplate template;
@BeforeEach
public void setUp() throws Exception {
this.base = new URL("http://localhost:" + port + "/");
}
@Test
public void getHello() throws Exception {
ResponseEntity<String> response = template.getForEntity(base.toString(),
String.class);
assertThat(response.getBody()).isEqualTo("Greetings from Spring Boot!");
}
}
The embedded server starts on a random port because of webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT, and the actual port is discovered at runtime with @LocalServerPort.
Add Production-grade Services
If you are building a web site for your business, you probably need to add some management services. Spring Boot provides several such services (such as health, audits, beans, and more) with its actuator module.
If you use Gradle, add the following dependency to your build.gradle file:
implementation ‘org.springframework.boot:spring-boot-starter-actuator’
If you use Maven, add the following dependency to your pom.xml file:
org.springframework.boot spring-boot-starter-actuatorThen restart the application. If you use Gradle, run the following command in a terminal window (in the complete directory):
./gradlew bootRun
If you use Maven, run the following command in a terminal window (in the complete directory):
./mvnw spring-boot:run
You should see that a new set of RESTful end points have been added to the application. These are management services provided by Spring Boot. The following listing shows typical output:
management.endpoint.configprops-org.springframework.boot.actuate.autoconfigure.context.properties.ConfigurationPropertiesReportEndpointProperties
management.endpoint.env-org.springframework.boot.actuate.autoconfigure.env.EnvironmentEndpointProperties
management.endpoint.health-org.springframework.boot.actuate.autoconfigure.health.HealthEndpointProperties
management.endpoint.logfile-org.springframework.boot.actuate.autoconfigure.logging.LogFileWebEndpointProperties
management.endpoints.jmx-org.springframework.boot.actuate.autoconfigure.endpoint.jmx.JmxEndpointProperties
management.endpoints.web-org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointProperties
management.endpoints.web.cors-org.springframework.boot.actuate.autoconfigure.endpoint.web.CorsEndpointProperties
management.health.status-org.springframework.boot.actuate.autoconfigure.health.HealthIndicatorProperties
management.info-org.springframework.boot.actuate.autoconfigure.info.InfoContributorProperties
management.metrics-org.springframework.boot.actuate.autoconfigure.metrics.MetricsProperties
management.metrics.export.simple-org.springframework.boot.actuate.autoconfigure.metrics.export.simple.SimpleProperties
management.server-org.springframework.boot.actuate.autoconfigure.web.server.ManagementServerProperties
management.trace.http-org.springframework.boot.actuate.autoconfigure.trace.http.HttpTraceProperties
The actuator exposes the following:
errors
actuator/health
actuator/info
actuator
There is also an /actuator/shutdown endpoint, but, by default, it is visible only through JMX. To enable it as an HTTP endpoint, add management.endpoints.web.exposure.include=health,info,shutdown to your application.properties file. However, you probably should not enable the shutdown endpoint for a publicly available application.
You can check the health of the application by running the following command:
$ curl localhost:8080/actuator/health
{“status”:“UP”}
You can try also to invoke shutdown through curl, to see what happens when you have not added the necessary line (shown in the preceding note) to application.properties:
$ curl -X POST localhost:8080/actuator/shutdown
{“timestamp”:1401820343710,“error”:“Method Not Allowed”,“status”:405,“message”:“Request method ‘POST’ not supported”}
Because we did not enable it, the request is blocked (because the endpoint does not exist).
For more details about each of these REST endpoints and how you can tune their settings with an application.properties file (in src/main/resources), see the the documentation about the endpoints.
View Spring Boot’s Starters
You have seen some of Spring Boot’s “starters”. You can see them all here in source code.
JAR Support and Groovy Support
The last example showed how Spring Boot lets you wire beans that you may not be aware you need. It also showed how to turn on convenient management services.
However, Spring Boot does more than that. It supports not only traditional WAR file deployments but also lets you put together executable JARs, thanks to Spring Boot’s loader module. The various guides demonstrate this dual support through the spring-boot-gradle-plugin and spring-boot-maven-plugin.
On top of that, Spring Boot also has Groovy support, letting you build Spring MVC web applications with as little as a single file.
Create a new file called app.groovy and put the following code in it:
@RestController
class ThisWillActuallyRun {
@RequestMapping("/")
String home() {
return "Hello, World!"
}
}
It does not matter where the file is. You can even fit an application that small inside a single tweet!
Next, install Spring Boot’s CLI.
Run the Groovy application by running the following command:
$ spring run app.groovy
Shut down the previous application, to avoid a port collision.
From a different terminal window, run the following curl command (shown with its output):
$ curl localhost:8080
Hello, World!
Spring Boot does this by dynamically adding key annotations to your code and using Groovy Grape to pull down the libraries that are needed to make the app run.
Summary
Congratulations! You built a simple web application with Spring Boot and learned how it can ramp up your development pace. You also turned on some handy production services. This is only a small sampling of what Spring Boot can do. See Spring Boot’s online docs for much more information.
See Also
The following guides may also be helpful:
Securing a Web Application
Serving Web Content with Spring MVC
Want to write a new guide or contribute to an existing one? Check out our contribution guidelines.
All guides are released with an ASLv2 license for the code, and an Attribution, NoDerivatives creative commons license for the writing.
translate：
翻译：
本指南将引导您完成使用Spring创建“Hello，World”网站的过程。
你将建造什么
您将构建一个具有静态主页的应用程序，该应用程序还将接受HTTP://localhost:8080/greeting上的HTTP GET请求。
它将用一个显示HTML的网页来响应。HTML的主体将包含一个问候语：“你好，世界！”
可以使用查询字符串中的可选名称参数自定义问候语。URL可能是http://localhost:8080/greeting？name=用户。
name参数值覆盖World的默认值，内容更改为“Hello，User！”！”
你需要什么
如何完成本指南
与大多数Spring入门指南一样，您可以从头开始并完成每个步骤，也可以绕过您已经熟悉的基本设置步骤。不管怎样，你最终都会使用代码。
要从头开始，请继续使用Spring初始化器。
要跳过基本步骤，请执行以下操作：
下载并解压缩此指南的源存储库，或使用Git:Git clone https://github.com/spring-guides/gs-spring-boot.Git进行克隆
cd进入gs弹簧防尘套/初始
继续创建一个简单的Web应用程序。
完成后，可以对照gs spring boot/complete中的代码检查结果。
了解如何使用弹簧靴
Spring Boot提供了一种快速构建应用程序的方法。它查看您的类路径和您配置的bean，对您丢失的内容进行合理的假设，并添加这些项。使用Spring Boot，您可以更多地关注业务特性，而不是基础设施。
以下示例说明了Spring Boot可以为您做些什么：
SpringMVC在类路径上吗？您几乎总是需要几个特定的bean，Spring Boot会自动添加它们。Spring MVC应用程序还需要一个servlet容器，因此Spring Boot会自动配置嵌入式Tomcat。
杰蒂在教室的小路上吗？如果是这样，您可能不需要Tomcat，而是需要嵌入式Jetty。弹簧靴帮你处理。
百里香在课堂上吗？如果是这样，那么必须始终将一些bean添加到应用程序上下文中。弹簧靴为您添加了它们。
这些只是Spring Boot提供的自动配置的几个例子。同时，弹簧靴不会妨碍你。例如，如果Thymeleaf在您的路径上，Spring Boot会自动将SpringTemplateEngine添加到您的应用程序上下文中。但是，如果用自己的设置定义自己的SpringTemplateEngine，Spring Boot不会添加一个。这样你就不用费多大力气就能控制局面。
Spring Boot不会生成代码或对文件进行编辑。相反，当您启动应用程序时，Spring Boot会动态地连接bean和设置，并将它们应用于您的应用程序上下文。
从Spring初始化器开始
对于所有Spring应用程序，都应该从Spring初始化器开始。initializer提供了一种快速的方法来获取应用程序所需的所有依赖项，并为您进行了很多设置。这个例子只需要Spring Web依赖项。下图显示了为此示例项目设置的初始值设定项：
初始化程序
上图显示了选择Maven作为构建工具的初始化器。你也可以用格雷德。它还将com.example和spring boot的值分别显示为组和工件。您将在本示例的其余部分中使用这些值。
还有一个/actuator/shutdown端点，但默认情况下，它只通过JMX可见。要将其启用为HTTP端点，请将management.endpoints.web.exposure.include=health，info，shutdown添加到application.properties文件中。但是，您可能不应该为公共可用的应用程序启用关闭终结点。
可以通过运行以下命令检查应用程序的运行状况：
$curl本地主机：8080/执行器/运行状况
{“status”：“UP”}
您还可以尝试通过curl调用shutdown，以查看在没有向application.properties添加必要的行（如前注所示）时会发生什么：
$curl-X POST localhost:8080/执行器/关闭
{“timestamp”：1401820343710，“error”：“Method Not Allowed”，“status”：405，“message”：“请求方法’POST’不受支持”}
因为我们没有启用它，请求被阻止（因为端点不存在）。
有关每个REST端点的更多详细信息，以及如何使用application.properties文件（在src/main/resources中）优化它们的设置，请参阅有关这些端点的文档。
查看弹簧靴的启动器
你见过一些SpringBoot的“初学者”。你可以在源代码中看到它们。
JAR支持和Groovy支持
最后一个例子展示了Spring Boot如何让您连接可能不知道您需要的bean。它还展示了如何开启便捷的管理服务。
然而，SpringBoot做的不止这些。它不仅支持传统的WAR文件部署，还允许您组合可执行jar，这要感谢Spring Boot的加载模块。各种指南通过spring boot gradle插件和spring boot maven插件演示了这种双重支持。
除此之外，Spring Boot还支持Groovy，让您只需一个文件就可以构建Spring MVC web应用程序。
