开始 - xiaoyuqinA/doc-spring-boot GitHub Wiki
如果你想从Spring Boot或者通用的"Spring" 开始,可以阅读本章节。本文档会回答基础的问题,如”是什么?“,”怎么样?“ 或 ”为什么?“。
本文包括Spring Boot简介,安装,也会讨论到构建第一个Spring Boot 应用程序,以及核心的原理。
Spring Boot帮助你创建基于Spring独立运行,生产级别的应用。我们对Spring 平台和第三方库持保留意见,这样您可以最小化开始。大多数的
Spring Boot 应用只需要很少的Spring 配置。
你可以使用Spring Boot 创建以 java -jar
或者更加传统的war部署的Java 应用。我们提供了如下命令行来运行”Spring 脚本“
我们的目标是:
- 为广大的Spring 开发者提供一个快速且广泛可用的开始教程
- 开箱即用,随着需求快速修改默认值
- 提供一系列大型项目通用而非功能性的功能(例如内置服务器,安全性,指标,健康检查和外部化配置)
- 绝对没有代码和必须的xml配置
Spring Boot 2.2.5需要java 8 和 兼容了 java 16。需要 Spring Framework 5.3.6 , 下面罗列出可用的构建工具:
构建工具 | 版本 |
---|---|
Maven | 3.3+ |
Gradel | 6(6.3或更高版本),6.5也支持,但已弃用 |
Spring Boot支持如下容器
容器名 | 容器版本 |
---|---|
Tomcat 9.0 | 4.0 |
Jetty 9.4 | 3.1 |
Undertow 2.0 | 4.0 |
你也可以部署Spring Boot 应用 到任何兼容Servlet 3.1+的容器中。
Spring Boot 可以作为传统的java 开发工具或者作为命令行工具,但是都需要java SDK v1.8或更高。使用下面的命令检查你当前的java版本
java -version
如果你不熟悉java开发,但是仍旧希望尝试Spring Boot,则可以先尝试Spring Boot CLI。否则,请继续阅读传统的安装说明。
Spring Boot兼容Apache Maven 3.3 或更高,如果你还未安装Maven,那么可以遵循安装文档maven.apache.org.
许多开放系统,maven可以使用包管理工具安装。
如果你是OSX Homebrew,则尝试 brew install maven .
如果你是Ubuntu ,则尝试 sudo apg-get install maven.
如果是window用户配合 h Chocolatey可以使用 choco install maven 安装
Spring Boot 依赖 的groupId
都使用org.springframework.boot
。典型的,如果你的Maven POM 文件 继承自 spring-boot-starter-parent
项目,且声明了多个 “Starters”.
Spring Boot 也提供了一个可选的 Maven plugin 来创建可执行的jar包。
关于Spring Boot 和 Maven入门的更多细节,请查询Maven插件文档Getting Started section。
Spring Boot 兼容Gradel 6 或者6.3更高。Gradel 5.6.x 也支持,但是已经弃用,且之后会移除。 如果你还未安装Gradel,则可以按照文档按照 gradle.org.
Spring Boot 依赖 的groupId
都使用org.springframework.boot
。典型的,如果你的Maven POM 文件 继承自 spring-boot-starter-parent
项目,且声明了多个 “Starters”.
Spring Boot 也提供了一个可选的 Gradle plugin来创建可执行的jar包。
Gradel包装器提供了一种获取Gradel的好方法,它是一个小脚本,你可以直接提交到代码仓库 以引导构建过程。详情请看docs.gradle.org/current/userguide/gradle_wrapper.html
Spring Boot CLI 是一个命令行工具,它可以让你快速的使用Spring 进行原型设计。它运行和java语法类似Groov脚本而无需过多模板。
你可以从Spring CLI 仓库中下载源码包安装。下载地址:
也可以下载最新版快照snapshot distributions地址
一旦下载成功,根据 INSTALL.txt 的指引进行安装。简而言之,在Zip包内bin目录下包含spring
脚本,(spring.bat是windows使用的),你可以使用java -jar
运行.jar
文件来保证设置正确的classpath。
SDKMAN( Software Development Kit Manager) 可以管理多个不同版本的二进制SDK,包括Groovy 和 the Spring Boot CLI。从sdkman.io 获取SDKMAN 并使用下面的命令安装Spring Boot CLI
$ sdk install springboot
$ spring --version
Spring Boot v2.4.5
如果你为Spring Boot CLI 的开发功能,并希望访问所构建的版本,可以使用下面的命令
$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.4.5-bin/spring-2.4.5/
$ sdk default springboot dev
$ spring --version
Spring CLI v2.4.5
上面的命令会安装一个spring本地实例,名称为dev。它指向你的目标构建位置。所有每次你构建Spring Boot,spring都会是最新的。
你可以运行下面的命令来查看输出
$ sdk ls springboot
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 2.4.5
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
如果你是Mac系统,可以使用Homebrew,运行下面的命令来安装Spring Boot CLI
$ brew tap spring-io/tap
$ brew install spring-boot
Homebrew 会将spring
安装在/usr/local/bin
如果你没有看到包,说明Homebrew已经过期,需要更新brew update
然后再重试上述命令。
如果你是Mac系统,可以使用MacPorts安装,运行下面的命令
$ sudo port install spring-boot-cli
Spring Boot CLI 包括为BASH 和 zsh shell 提供命令补全的脚本。你可以将此脚本(也叫spring)放置在你个人的shell或者系统的shell中。在Debian系统中,系统范围的脚本是在/shell-completion/bash
,启动一个shell外壳时,在这个目录下的所有的命令都会先运行。例如,收到运行此脚本,运行如下命令:
$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$ spring <HIT TAB HERE>
grab help jar run test version
如果你是使用Homebrew 或者MacPorts安装Spring Boot CLI,命令补全脚本会自动注册在shell中。
如果你是windows系统,且使用 Scoop,可以运行如下命令安装:
> scoop bucket add extras
> scoop install springboot
scoop会将script
安装 ~/scoop/apps/springboot/current/bin
如果你没有看到包名,你需要更新你的scoop,运行scoop update
,然后在运行上述命令。
你可以使用下面的web示例来测试你的安装。首先,创建一个文件名为app.groovy,内容如下:
@RestController
class ThisWillActuallyRun {
@RequestMapping("/")
String home() {
"Hello World!"
}
}
然后在shell命令行运行:
$ spring run app.groovy
首次运行会很慢,因为需要下载很多依赖,之后就会快很多。
打开浏览器输入:localhist:808
,你会看到如下输出
Hello World!
如果你想从早期的1.x版本升级,可以查看项目wiki上的 迁移至南,迁移指南提供了详细的升级指导,你也可以查看发行说明,来获知每个发行版的新功能和注意事项。
当升级新版本时,会遇到一些属性也许已经重命名或者被删除了。Spring Boot 提供了一个方法来检查你的应用并在应用启动时打印出诊断方法,而且还会在运行时迁移属性,要使用此功能
需要安装下面的依赖
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-properties-migrator</artifactId>
<scope>runtime</scope>
</dependency>
新添加的属性,不会考虑。如@PropertySource
。
一旦你迁移完成,请确保删除此依赖。
如果希望升级已存在的Spring Boot CLI,使用包管理器进行升级,如brew update
。如果你希望手动升级CLI,查看文档,请别忘了,更新path移除旧的引用。
本章节讲述如何快速的创建小型的hello World!
web应用来尝试新特性,我们使用Maven来构建项目,许多IDE都支持Maven。
Spring.io包含了许多开始
指南,如果你想解决特殊问题,可以查阅。
你可以省略步骤通过start.spring.io ,选择Web starter 依赖,这样子可以让你正确的开始一个新项目,Spring Initializr documentation 查阅更多文档。
在开始之前,打开命令行,运行如下命令,确保Java版本
$ java -version
java version "1.8.0_102"
Java(TM) SE Runtime Environment (build 1.8.0_102-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.102-b14, mixed mode)
$ mvn -v
Apache Maven 3.5.4 (1edded0938998edf8bf061f1ceb3cfdeccf443fe; 2018-06-17T14:33:14-04:00)
Maven home: /usr/local/Cellar/maven/3.3.9/libexec
Java version: 1.8.0_102, vendor: Oracle Corporation
首先创建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>2.4.5</version>
</parent>
<description/>
<developers>
<developer/>
</developers>
<licenses>
<license/>
</licenses>
<scm>
<url/>
</scm>
<url/>
<!-- Additional lines to be added here... -->
</project>
上面的pom.xml已经可以让你正确构建一个项目了,你也可以通过mvn package
来测试。
Spring Boot 提供了很多starter包让你可以加入到Classpath中,我们的项目在pom中使用spring-boot-starter-parent
作为parent来作为冒烟测试。spring-boot-starter-parent
是一个特殊的starter,因为它内置了很多有用的maven包,它还提供了dependency-management
,所以你可以添加依赖,而无需填写version
字段。
其他的starters
提供了你开发特殊需求时的依赖,因为我们要开发一个web应用,所以我们需要添加spring-boot-starter-web
依赖。在此之前,让我们看一下当前所拥有的依赖,运行如下命令:
$ mvn dependency:treee
[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 Servcer和Spring Boot 。
为了完成我们的代码,我们需要创建一个简单的java文件。默认的,maven编译时会以src/main/java
为代码源目录,所以你可以创建这样结构的目录,然后创建一个文件Example.java.代码如下:
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.web.bind.annotation.*;
@RestController
@EnableAutoConfiguration
public class Example {
@RequestMapping("/")
String home() {
return "Hello World!";
}
public static void main(String[] args) {
SpringApplication.run(Example.class, args);
}
}
尽管代码不多,但是也可以正常运行,我们将要在接下来的章节中介绍重要的部分。
在我们的示例代码中,第一个注解是@RestController。这是很常用的构造型的注解。它给阅读代码的人和Spring,这个类扮演着很重要的角色。在这个例子中,我们的类扮演着Web @Controller,所以Spring任务额它可以处理请求。
@RequestMapping注解提供了路由信息,它告诉Spring任何以/
作为path的http请求应该匹配到home
方法来处理,@RestController注解告诉Spring将结果直接渲染成字符串返回给请求者。
@RestController和@RequestMapping是Spring MVC的注解,并不是Spring Boot特有的,查看MVC section 文档了解更多详情
第二个类级别的注解是@EnableAutoConfiguration,这个注解告诉Spring Boot 去猜测你如何配置Spring,基于你添加的jar依赖。因为spring-boot-starter-web
添加了Tomcat和Spring MVC ,自动装配假定你正在开发web应用,并相应的设置Spring。
自动装配是设计来适配starter启动器,但是这2者并非耦合在一起,你可以随意选择starter以外的jar依赖,Spring Boot 会尽最大的努力来自动装配你的应用。
最后的部分是main
方法,这是遵循java约定的标准入口方法,我们的main方法委托Spring Boot SpringApplication
类来启动。
SpringApplication启动我们的程序,启动Spring,Spring 则会自动装配Tomcat web服务器,我们需要给SpringApplication
传递Example.class
参数来告诉SpringApplication
基础的Spring 组件,
将命令行参数数组args
传递至SpringApplication。
此刻,你的应用程序应该可以正常工作,因为你使用了spring-boot-starter-parent
的pom,所以你可以使用run
目标来启动你的应用,在代码根目录,执行 命令mvn spring-boot:run
,你会看到如下的输出
$ mvn spring-boot:run
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.4.5)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)
然后在浏览器打开localhost:8080
,你会看到浏览器呈现如下的输出
Hello World!
ctrl-c
停止程序。
我们完成了一个可在生产使用的独立应用程序,可执行的jar包是包含了你的class文件和运行时所需的第三方jar包依赖打包在一起。
java并没有提供单独的程序来运行嵌套的jar包。如果你想分发独立的程序,可能会是一个问题
为了解决这个问题,许多开放者使用'uber'jar包,一个uber包将所有依赖打包至一个文件。问题是,这样就很难得知有哪些第三方依赖,不同jar包下出现相同的文件的使用也成了问题。
Spring Boot提供了另一种方法来让你直接运行嵌套jar包。
为了创建一个可执行的jar包,我们可以添加spring-boot-maven-plugin
,在pom.xml文件中添加如下依赖:
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
spring-boot-starter-parent
包含了<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:2.4.5:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
如果你查看target
目录,你会看到文件myproject-0.0.1-SNAPSHOT.jar
,这个文件大概10MB,你如果想看一下包内部,可以使用下面的命令:
$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar
你还可以看到文件myproject-0.0.1-SNAPSHOT.jar.original
,这个是maven自己打包的原始文件。
运行这个jar包,使用如下命令:
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
按下ctr+c可以退出。
本章节提供了spring boot 基础的知识,让你可以使用正确的方式编写你的应用代码。如果你是面向任务的开发者,你可以到 spring.io来检出一些开始手册。