Spring Boot参考指南

翻译自docs.spring.io，有删减。

1.5.6.RELEASE

Copyright © 2012-2017

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.（不能收取任何费用）

一、Spring Boot简介

Spring Boot可以轻松的创建一个独立的，产品级的基于Spring的应用程序。大多数Spring Boot应用程序只需要很少的一点Spring配置。

默认的, Spring Boot 1.5.6.RELEASE需要Java 7+和Spring Framework 4.3.10.RELEASE+。你可以通过一些额外的配置来使用Java 6。构建支持Maven3.2+, Gradle2.9。

这里是一个典型的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>

    <!-- 从Spring Boot继承默认父项目 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.6.RELEASE</version>
    </parent>

    <!-- 一个典型的web应用程序依赖 -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>

    <!-- 当作一个可执行jar打包 -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

1.1 构建系统

1.1.1 Maven

Maven用户可以继承自spring-boot-starter-parent项目来获得合理的默认配置。父项目提供如下特性：

• Java 1.6 作为默认的compiler level
• UTF-8 source 编码
• 允许你忽略一般依赖的<version>标签，从spring-boot-dependencies POM继承
• 合理的resource过滤
• 合理的插件配置(exec plugin, surefire, Git commit ID, shade)
• 合理的application.properties和application.yml resource过滤，包括application-foo.properties和application-foo.yml等等

1.1.2 Starters

Starters是一系列的依赖“描述”。你可以一站式获得所有Spring和相关技术而不用去粘贴大量的依赖配置。例如，如果你想开始使用Spring 和 JPA来进行数据库访问，只需要添加：

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

下面是一些例子：

名称	描述
spring-boot-starter-activemq	使用Apache ActiveMQ的starter
spring-boot-starter-amqp	使用Spring AMQP 和 Rabbit MQ的starter
spring-boot-starter-aop	使用Spring AOP 和 AspectJ的starter
spring-boot-starter-web	构建web应用程序的starter，包含了RESTful，Spring MVC。使用Tomcat作为默认的嵌入式容器

1.2 结构化你的代码

Spring Boot并不要求任何特殊的代码布局，但是这里列出了一些最佳实践。

1.2.1 使用默认包

当一个class没有包含包声明，它被认为在默认包中。使用默认包通常是被劝阻的，应该避免这样。它会引起一些特别的问题，如果你使用了@ComponentScan, @EntityScan 或者 @SpringBootApplication注解，因为每个jar中所有的class都会被读取。

1.2.2 放置main class

我们推荐你将main class放在最顶层的包中。@EnableAutoConfiguration注解通常就放在main class，它暗示着定义一个基本“search package”。例如，如果你你用了JPA，那么@EnableAutoConfiguration注解的类所在的包将会被用来搜索@Entity。

这样做还允许使用@ComponentScan而不用指定basePackage属性。如果你的main class放在了最顶层的包中，你还可以使用@SpringBootApplication注解。

这里是一个典型的结构：

com
 +- example
     +- myproject
         +- Application.java
         |
         +- domain
         |   +- Customer.java
         |   +- CustomerRepository.java
         |
         +- service
         |   +- CustomerService.java
         |
         +- web
             +- CustomerController.java

Application.java 声明了main方法。

package com.example.myproject;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableAutoConfiguration
@ComponentScan
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

1.3 Spring Beans和依赖注入

你可以自由的使用任何标准的Spring Framework技术来定义你的bean并且将它们注入。简单的讲，我们通常使用@ComponentScan查询beans，与@Autowired组合使用也会正常工作。

如果你像上面推荐那样构建代码（将main class放在最顶层的包中），你可以添加@ComponentScan并且不带任何参数。你应用程序里的所有组件（@Component, @Service, @Repository, @Controller等等）将会自动被注册为Spring Beans。

下面是一个例子：

package com.example.service;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class DatabaseAccountService implements AccountService {

    private final RiskAssessor riskAssessor;

    @Autowired
    public DatabaseAccountService(RiskAssessor riskAssessor) {
        this.riskAssessor = riskAssessor;
    }

    // ...

}

如果一个bean有一个构造器，那么@Autowired这个也是能省略的。

1.4 使用@SpringBootApplication

许多Spring Boot开发者总是在他们的main class里添加@Configuration, @EnableAutoConfiguration 和 @ComponentScan注解。既然这些注解经常被一起使用，Spring Boot提供了一个更方便的@SpringBootApplication注解作为替代。

@SpringBootApplication相当于使用@Configuration, @EnableAutoConfiguration 和 @ComponentScan这些注解并且它们都是默认属性：

package com.example.myproject;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication // same as @Configuration @EnableAutoConfiguration @ComponentScan
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

二、Spring Boot特性

2.1 SpringApplication

SpringApplication类提供了一个方便的途径来启动一个Spring应用程序。在许多场景你可以只使用SpringApplication.run：

public static void main(String[] args) {
    SpringApplication.run(MySpringConfiguration.class, args);
}

默认的控制台将会输出INFO级别的日志，包括了一些启动相信信息。

2.1.1 启动失败

如果你的应用程序启动失败，FailureAnalyzers将会提供一个专门的错误信息和一个具体的解决方案，例如8080端口被占用的错误：

***************************
APPLICATION FAILED TO START
***************************

Description:

Embedded servlet container failed to start. Port 8080 was already in use.

Action:

Identify and stop the process that's listening on port 8080 or configure this application to listen on another port.

你也可以轻松的添加你自己的FailureAnalyzer。

2.1.2 自定义Banner

Banner就是启动时打印的图形字母：

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::   v1.5.6.RELEASE

可以通过在classpath下添加banner.txt或者设置banner.location指定这个文件的位置来更改。默认是UTF-8编码。你也可以添加一个banner.gif,banner.jpg,banner.png到你的classpath或者设置banner.image.location指定这个图片的位置。图片将会被转换成一个ASCII组成的字符画而且会覆盖任何文字banner。

在你的banner.txt你你可以使用下列的占位符：

${application.version},${spring-boot.version},${application.title}等等。

设置spring.main.banner-mode为off关闭banner输出。

2.1.3 应用程序事件和监听器

应用程序启动时事件的运行顺序为：

1. ApplicationStartingEvent在启动时被触发， 除了监听器注册，初始化，它早于任何别的处理方法。
2. ApplicationEnvironmentPreparedEvent当Environment准备好时触发， 但是在上下文被创建之前。
3. ApplicationPreparedEvent在刷新开始前，但是在bean定义被加载之后被触发。
4. ApplicationReadyEvent在刷新后被触发，所有相关的回调都已经被处理，表明应用程序已经准备去服务请求。
5. ApplicationFailedEvent当启动时有异常产生时被触发。

2.2 Logging

Spring Boot使用Commons Logging来记录所有的内部日志，但是保持底层日志实现开放。默认的配置提供了针对Java Util Logging, Log4J2 and Logback的配置。每个配置中都预先配置了控制台输出。

默认的，如果你使用‘Starters’，那么将会使用Logback来记录日志。合适的Logback路由也在其中来确保使用Java Util Logging, Commons Logging, Log4J或者SLF4J依赖的类库都会正常工作。

2.2.1 控制台输出

默认的日志配置会将ERROR, WARN 和 INFO级别的信息输出到控制台。你也可以在application.properties文件中指定debug=true启用debug模式。

当启用debug模式后，一些核心日志记录器（嵌入式容器, Hibernate 和 Spring Boot）会输出更详细的信息。但是这并不会将你的应用程序中所有的DEBUG级别日志输出。类似的可以设置trace=true启动trace模式。

2.2.2 文件输出

默认的，Spring Boot只会将日志输出到控制台，不会写入日志文件。如果你还想写入日志文件中，你需要在application.properties文件中设置logging.file 或者 logging.path属性。

• logging.file可以是一个绝对路径的文件，也可以只是文件名，使用当前文件夹。
• logging.path是一个指定的目录，生成的日志文件为spring.log

当日志文件达到10MB时将会生成新的文件。

这些配置在application.properties中的属性是独立于实际用到的日志框架。当指定配置关键项后（例如为Logback指定logback.configurationFile）将不再被Spring Boot管理。

2.2.3 日志级别

所有支持的日志系统都可以在application.properties文件中使用logging.level.*=LEVEL，下面是个例子：

logging.level.root=WARN
logging.level.org.springframework.web=DEBUG
logging.level.org.hibernate=ERROR

2.2.4 自定义日志配置

你可以使用不同的日志系统，并且可以通过指定响应的配置文件进一步自定义，这个配置文件一般被放在classpath的跟路径，或者通过application.properties文件中logging.config属性指定的路径。

你可以强制Spring Boot只用特定的日志系统，通过设置org.springframework.boot.logging.LoggingSystem系统属性。它的值应该是特定日志系统实现类的完全限定名。你也可以指定它的值为none来完全禁止Spring Boot的日志配置。

需要注意的是日志系统的初始化要早于ApplicationContext被创建。所以不可能在@Configuration文件里控制日志。

根据不同的日志系统，下面的配置文件将会被加载：

日志系统名称	配置文件名称
Logback	logback-spring.xml或者logback.xml
Log4j2	log4j2-spring.xml或log4j2.xml

我们建议你使用带-spring这种方式的命名，如果使用标准方式命名配置文件，Spring并不能完全控制日志初始化。

未完，待续...