译者注: 本文翻译自Spring Boot 1.4.2.RELEASE 官方参考指南,译者第一次尝试翻译技术文档,如有不当之处还请诸君多多斧正,谢谢!
另:由于翻译工作尚未全部完成,目前译文中的链接均指向原英文文档;后续全部翻译工作完成后将统一替换为译文链接地址。
第二部分 入门
如果您初次接触Spring Boot,甚至初始”Spring”,请由此开始!
本节,笔者将解答“是什么”“怎么样”和“为什么”的问题。在介绍安装过程的同时,笔者将为您详细地讲解Spring Boot。稍后,笔者将指导您创建第一个Spring Boot应用程序,并在此过程中介绍一些Spring Boot的核心原则(core principles)。
第8章 Spring Boot简介
Spring Boot使读者可以很容易地创建一个独立的、可生产部署的、基于Spring的应用程序,并且这个应用程序可以“直接运行”。为了能够尽可能减少用户的工作量,设计者们为Spring平台以及第三方库创建了一些约定视图(opinionated view),大多数Spring Boot应用程序仅需要非常少量的Spring配置。
用户可以使用Spring Boot创建一个可以通过java -jar
直接运行或者传统地以War包形式部署的java应用程序。Spring Boot还提供了一个可以执行“Spring Script”的命令行工具。
Spring Boot的主要目标是:
- 提供一个普遍适用于各种Spring开发的快速启动范本;
- 基于约定(opinionated)实现开箱即用(out of box),并且能够快速修正默认值与实际需求之间的偏差;
- 提供一系列非功能性特性(如嵌入式服务器、安全、度量、健康检查、外部配置等),这些特性对于项目中的大多是类而言都是有必要的;
- 杜绝代码生成,并且无须使用XML配置。
第9章 系统要求
默认情况下,Spring Boot1.4.2.release需要Java 7和Spring Framework 4.3.4.release以上版本。你可以通过一些额外的配置在Java 6环境下使用Spring Boot。参见80.11 如何使用java 6了解更多内容。支持使用Maven(3.2+)和Gradle(1.12或者2.x)进行构建。不再支持Gradle2.8及更早版本。不支持Gradle3。
提示
虽然可以在java 6或7的环境中使用Spring Boot,但允许的情况下笔者通常推荐使用java 8。
9. 1 Servlet容器
以下嵌入式servlet容器均支持开箱即用:
名称 | Servlet版本 | Java版本 |
---|---|---|
Tomcat 8 | 3.1 | java 7 + |
Tomcat 7 | 3.0 | java 6 + |
Jetty9.3 | 3.1 | java 8 + |
Jetty9.2 | 3.1 | java 7 + |
Jetty8 | 3.0 | java 6 + |
Undertow1.3 | 3.1 | java 7 + |
您也可以在任何兼容Servlet 3.0 +的容器中部署Spring Boot应用程序。
第10章 安装Spring Boot
可以通过“传统的”Java开发工具开发Spring Boot,也可以将其安装为一个命令行工具。无论那种情况都需要Java SDK V1.6或更高版本。开始前,最好检查一下当前安装的java版本:
$java -version
除非您是Java开发的初学者或者只是想体验一下Spring Boot,您可以优先考虑使用Spring Boot CLI;否则,请阅读“传统的”安装说明。
提示
虽然Spring Boot兼容Java1.6,在允许的情况下您应该考虑使用最新版本的java。
10.1 Java开发者安装说明
使用Spring Boot的方式与使用标准Java库完全相同。只需要在classpath中加入适当的spring-boot-*.jar
。Spring Boot不需要集成任何特殊的工具,因此您可以使用任何文本编辑器或者IDE;并且Spring Boot应用程序毫无特异之处,所以您可以和其他Java程序一样地进行运行和调试。
尽管仅仅是拷贝Jar包便可以使用Spring Boot,但通常笔者建议您使用一个支持依赖管理的构建工具(如Maven或Gradle)。
10.1.1 Maven安装
Spring Boot兼容Apache Maven 3.2或以上版本。如果您尚未安装Maven,请参考maven.apache.org的手册操作。
提示
在许多操作系统中,可以通过包管理器(package manager)安装Maven。如果您使用的是OSX Homebrew,请尝试brew install maven
。Ubuntu用户可以执行命令sudo apt-get install maven
。
Spring Boot依赖以org.springframework.boot
为GroupID
。通常Maven POM文件继承自spring-boot-starter-parent
项目并声明对于一个或几个“启动器(Starter)”的依赖。Spring Boot还提供一个可选的Maven插件用以创建可执行Jar包。
以下是一个典型的pom.xml
文件:
<?xml version=“1”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 /波姆/ 4.0.0 HTTP:/ / 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>
<!-- Inherit defaults from Spring Boot -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.4.2.RELEASE</version>
</parent>
<!-- Add typical dependencies for a web application -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<!-- Package as an executable jar -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
提示
spring-boot-starter-parent
是使用Spring Boot的主要方式,但这并非唯一方式。有时候,可能需要继承不同的父POM;或者Spring Boot的默认设置对用户而言并不适用。13.2.2 不基于父POM使用Spring Boot一节提供了另一种导入(import)
的解决方案。
10.1.2 Gradle安装
Spring Boot兼容Gradle 1.12或2.x,但不再支持2.8及更早版本。推荐使用Gradle 2.14.1。不支持Gradle 3。如果您尚未安装Gradle,请参阅www.gradle.org/上的手册。
Spring Boot依赖使用org.springframework.boot
作为group
。通常需要声明对于一个或几个“启动器(Starter)”的依赖。Spring Boot提供了一个便捷的Gradle 插件,该插件可以简化依赖的声明和可执行Jar包的创建。
Gradle包装器(Wrapper)
当准备创建一个项目的时候,Gradle包装器提供了一个很好的“获得”Gradle的方式。它是一个帮助用户提交代码来引导构建过程的小型脚本和库。详见docs.gradle.org/2.14.1/userguide/gradle_wrapper.html。
以下是一个典型的build.gradle
文件:
buildscript {
repositories {
jcenter()
maven { url "http://repo.spring.io/snapshot" }
maven { url "http://repo.spring.io/milestone" }
}
dependencies {
classpath("org.springframework.boot:spring-boot-gradle-plugin:1.4.2.RELEASE")
}
}
apply plugin: 'java'
apply plugin: 'org.springframework.boot'
jar {
baseName = 'myproject'
version = '0.0.1-SNAPSHOT'
}
repositories {
jcenter()
maven { url "http://repo.spring.io/snapshot" }
maven { url "http://repo.spring.io/milestone" }
}
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile("org.springframework.boot:spring-boot-starter-test")
}
10.2 安装 Spring Boot CLI
Spring Boot CLI是一个用以构建Spring快速原型(quickly prototype)的命令行工具。它使用户得以运行Groovy脚本,这意味着不需要过多的样板代码(boilerplate code)就能够获得与Java相似的语法风格。
虽然CLI并不是必须的,但它无疑是落地Spring应用的最快途径。
10.2.1 手动安装
您可以从Spring的软件库获取Spring CLI的安装包:
也可以获取到最新的快照。
下载后,按照解压文件中的install.txt说明操作即可。总之:在.zip
文件的bin/
目录下有一个spring
的脚本(Windows操作系统为spring.bat
),或者你也可以使用java -jar
启动其中的.jar
文件(脚本可以帮助用户确保classpath设置正确)。
10.2.2 使用SDKMAN!安装
SDKMAN!(软件开发工具包管理器)被用来管理各种各样的、不同版本的二进制SDK,包括Groovy和Spring Boot CLI。通过sdkman.io获得SDKMAN!并通过以下命令安装Spring Boot:
$ sdk install springboot
$ spring --version
Spring Boot v1.4.2.release
如果你希望尝试CLI并且希望能够快速地访问刚刚构建的版本,请参考以下说明:
$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-1.4.2.RELEASE-bin/spring-1.4.2.RELEASE/
$ sdk default springboot dev
$ spring --version
Spring CLI v1.4.2.RELEASE
这样便可以安装一个被称作dev实例
的Spring
实例。它指向你的目标构建位置,所以每次你重建Spring Boot时,Spring
将会更新。
可以通过以下操作查看该实例:
$ sdk ls springboot
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 1.4.2.RELEASE
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
10.2.3 OSX Homebrew安装
如果您在Mac上使用Homebrew,安装Spring Boot CLI仅需要以下操作:
$ brew tap pivotal/tap
$ brew install springboot
Homebrew会将spring
安装在/usr/local/bin
目录。
注
如果该公式不存在,则说明当前安装版本过低。请执行brew updat
,并再试一次。
10.2.4 MacPorts安装
如果您在Mac上使用MacPorts,安装Spring Boot CLI仅需要执行以下操作:
$ sudo port install spring-boot-cli
10.2.5 Command-line completion
Spring Boot CLI ships with scripts that provide command completion for BASH and zsh shells. You can source
the script (also named spring
) in any shell, or put it in your personal or system-wide bash completion initialization. On a Debian system the system-wide scripts are in /shell-completion/bash
and all scripts in that directory are executed when a new shell starts. To run the script manually, e.g. if you have installed using SDKMAN!
$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$ spring <HIT TAB HERE>
grab help jar run test versionNote
Tips
If you install Spring Boot CLI using Homebrew or MacPorts, the command-line completion scripts are automatically registered with your shell.
10.2.6 快速启动Spring CLI的例子
以下是一个非常简单的Web应用程序,可用以测试是否安装成功。创建一个为app.groovy
的文件:
@RestController
class ThisWillActuallyRun {
@RequestMapping("/")
String home() {
"Hello World!"
}
}
然后通过Shell简单地运行它:
$ spring run app.groovyNote
提示
因为需要下载依赖,首次启动时可能会需要一些时间。随后的运行将更快。
使用您喜欢的浏览器打开localhost:8080,您将看到如下输出:
Hello World!
10.3 从早期版本的Spring Boot升级
如果从一个早期的发布版本升级Spring Boot,请查阅项目wiki上的“发布说明”。你会发现升级手册以及每一个版本的“新的和值得注意的”功能列表。
使用适当的保管理命令(如brew upgrade
)来升级当前安装的现有的CLI;如果CLI是手动安装的,请按照标准说明操作,应注意更新PATH
环境变量来移除旧的版本。
第11章 开发您的第一个Spring Boot应用
笔者将开发一个简单的“Hello World!“ Java Web应用,来演示Spring Boot的一些关键特征。因为大多数IDE支持Maven,笔者将使用其构建这个项目。
提示
spring.io网站上有很多Spring Boot的“入门”指南。当您想获取一个特定问题的解决方式时可以先检索这个网站。
你通过在start.spring.io依赖搜索器中选择web
启动器的方式简化创建步骤。如此将自动生成一个新的项目结构,便可以直接开始编码。更多详情请参见该文档。
开始前,请先通过终端检查已经找的有效Java和Maven版本。
$ java -version
java version "1.7.0_51"
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)
$ mvn -v
Apache Maven 3.2.3 (33f8c3e1027c3ddde99d3cdebad2656a31e8fdf4; 2014-08-11T13:58:10-07:00)
Maven home: /Users/user/tools/apache-maven-3.1.1
Java version: 1.7.0_51, vendor: Oracle CorporationNote
提示
此示例需要在其自己的文件夹中创建。下文将假定您已经创建了适当的文件夹,并且是“当前目录”。
11.1 创建POM
首先,创建一个Mavenpom.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 http://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>1.4.2.RELEASE</version>
</parent>
<!-- Additional lines to be added here... -->
</project>
至此,已经可以进行构建了,可以执行mvn package
进行测试(有可能会出现“jar将会是空的——未检测到需要包含的内容”警告)。
注
可以将该项目导入到一个IDE(主流的java IDE均提供了Maven的内置支持)。为了简单起见,笔者将继续使用一个简单的文本编辑器来演示这个例子。
11.2 添加classpath依赖
Spring Boot提供了大量的“启动器(Starter)”,可以很容易地添加Jar包到类路径。示例应用中已经在POM文件的parent
一节使用了spring-boot-starter-parent
。spring-boot-starter-parent
是一个提供了常用Maven默认配置的特殊的启动器。它还提供dependency-management
节点,从而可以方便地省略掉依赖的version
标签。
其他“起动器”可以方便地为特定类型的应用提供所需的依赖。比如开发Web应用,可以添加spring-boot-starter-web
依赖——但在那之前,先来看看我们目前有哪些依赖:
$ mvn dependency:tree
[INFO] com.example:myproject:jar:0.0.1-SNAPSHOTThe mvn
mav 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本身。
11.3 编写代码
创建一个java文件来完成当前的应用。Maven默认编译src /main/ java
,所以需要创建对应的文件夹结构,然后创建一个名为src/mian/java / example.java
的文件:
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.stereotype.*;
import org.springframework.web.bind.annotation.*;
@RestController
@EnableAutoConfiguration
public class Example {
@RequestMapping("/")
String home() {
return "Hello World!";
}
public static void main(String[] args) throws Exception {
SpringApplication.run(Example.class, args);
}
}
虽然代码并不多,但有很多内容值得关注。下面,笔者讨论一些重点。
11.3.1 @RestController和@RequestMapping注解
Example
类中的第一个注释是@RestController
,它是一个构造型注释(stereotype annotation,也被译为“版型注解”)。它为阅读代码的人提供了一些提示,而对Spring而言该类扮演着一个特殊的角色。对本例而言,这个类是一个Web @Controller
,所以Spring将使用该类来响应网络请求。
@RequestMapping
注解提供“路由”信息。它使Spring将所有对于“/”路径的HTTP请求映射到home
方法。@RestController
注释表示Spring会将结果字符串直接返回给调用者。
提示
@RestController
和@RequestMapping
注释是Spring MVC的注释(他们并不是Spring Boot独有的)。详情请参见Spring参考文档MVC一节。
11.3.2 @EnableAutoConfiguration注释
第二个类注释是@EnableAutoConfiguration
。此注释使Spring Boot根据所添加的Jar依赖“推测”应该如何配置Spring。因为spring-boot-startr-web
包含了Tomcat和Spring MVC,auto-configuration会假设正在开发一个Web应用程序,并据此配置Spring。
起动器(Starter)和自动配置(Auto-Configuration)
自动配置的设计要求之一是为了能够更好地与“启动器”协作,但这两个概念并没有直接的联系。用户可以自由地选用启动器中没有的Jar依赖,Spring Boot仍然会尽可能地实现应用程序的自动配置。
11.3.3 “mian”方法
示例程序的最后一部分是main
方法。它是一个作为应用程序入口的、符合Java规范的静态方法。这个main方法通过调用SpringApplication
类的run
方法将程序委托给Spring Boot。SpringApplication
将引导应用程序,启动Spring,Spring将启动自动配置的Tomcat Web服务器。为了使SpringApplication
能够确定Spring主应用组件,需要将Example.class
作为参数传递给run
方法。传递args
数组是为了接收命令行参数。
11.4 运行示例
至此,实例代码已经可以运行了。继承自spring-boot-starter-parent
POM使得应用程序已经获得了足以run
的所有信息。在根目录执行mvn spring-boot:run
启动程序:
$ mvn spring-boot:run
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v1.4.2.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)
通过浏览器访问localhost:8080将看到以下内容:
Hello World!
Ctrl+C
组合键便可以优雅地终止应用程序。
11.5 创建可执行Jar包
在本示例的最后,笔者将创建一个可以在生产环境运行的、完全独立的Jar包。可执行Jar包(有时被称为“胖Jar包”)是包括已编译的类和程序执行所需Jar包依赖的归档文件。
可执行的Jar和Java
Java不提供任何标准的方式来加载嵌套的Jar文件(即Jar文件本身是包含在一个Jar里的)。这使得难以通过Jar包发布一个独立的应用程序。
为了解决这个问题,许多开发者选择使用“高级”Jar。一个高级Jar只是简单将所有Jar包的类都打包在一个唯一的归档文件中。这种方法的问题在于很难识别应用程序实际使用到的库。同时,如果不同Jar中包含文件名相同的文件(但是内容不同),这种方式也会存在问题。
Spring Boot以另一种方式)真正实现直接嵌套Jar包。
创建一个可执行Jar,需要在pom.xml
中加入spring-boot-maven-plugin
。在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,便需要手动声明该配置。详情请参见插件文档。
保存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:1.4.2.RELEASE:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
在target
文件夹中将看到Jar包myproject-0.0.1-SNAPSHOT.jar
。该文件应在10MB左右。以使用jar TVF
命令查看文件内部:
$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar
在target
文件夹中还会存在一个较小的名为myproject-0.0.1-snapshot.jar.original
的文件。这是Spring Boot重打包之前Maven创建的原始Jar文件。
执行java -jar
命令即可运行应用程序:
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v1.4.2.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.536 seconds (JVM running for 2.864)
和先前一样,Ctrl+C
组合键便可以优雅地终止应用程序。
第12章 后续
希望本节使您了解了Spring Boot的基本知识,并且让您可以编写自己的应用程序。如果您是面向任务的开发者,您可能希望跳转到spring.io检索一些解决”如何使用Spring”等特定问题的入门指导手册。同时,笔者也有专门针对Spring Boot的How-to参考文档。
Spring Boot仓库有很多可以执行的示例。这些示例是独立于代码的其余部分的(不需要构建其他部分即可运行或使用这些示例)。
无论如何,理论上下面应该阅读“第三部分 使用Spring Boot”。也可以直接阅读关于Spring Boot特性的内容。