Spring Boot Reference Guide
2.0.2.RELEASE
Copyright © 2012-2018
内容表格
I.Spring Boot 文档
1.关于本文档
2.获取帮助
3.第一步
4.使用Spring Boot
5.了解Spring Boot特性
6.迁移到生产
7.高级主题
正文
Spring Boot Documentation
这部分内容提供了一个本文档的简短概览,它作为一个地图为余下的内容服务。
1.关于本文档
Spring Boot 特性
这部分会深入Spring Boot细节。你可以了解到你想要使用过和定制的关键特性。如果你还没做好准备,你可以先阅读XX和YY,以对Spring Boot有个良好的基本认识。
23.SpringApplication
SpringApplication 类提供了一个便捷的方式启动一个Spring应用,这个应用从main()方法开始启动,许多情况下,你可以代理这个静态的SpringApplication.run方法,就像下面的例子:
当你的应用启动后,你应该会看到和下面类似的输出:
- public static void main(String[] args) {
- SpringApplication.run(MySpringConfiguration.class, args);
- }
- :: Spring Boot :: v2.0.2.RELEASE
- 2013-07-31 00:08:16.117 INFO 56603 --- [ main] o.s.b.s.app.SampleApplication :
- Starting SampleApplication v0.1.0 on mycomputer with PID 56603 (/apps/myapp.jar started by pwebb)
- 2013-07-31 00:08:16.166 INFO 56603 --- [ main]
- ationConfigServletWebServerApplicationContext : Refreshing
- org.springframework.boot.web.servlet.context.AnnotationConfigServletWebServerApplicationContext@6e5a8246:
- startup date [Wed Jul 31 00:08:16 PDT 2013]; root of context hierarchy
- 2014-03-04 13:09:54.912 INFO 41370 --- [ main] .t.TomcatServletWebServerFactory : Server
- initialized with port: 8080
- 2014-03-04 13:09:56.501 INFO 41370 --- [ main] o.s.b.s.app.SampleApplication :
- Started SampleApplication in 2.992 seconds (JVM running for 3.658)
默认地,INFO级别的日志信息会被展示,包括一些相关启动细节,如启动应用的用户。如果你需要其他级别的日志信息,你可以设置它,像在26.4节描述的那样。
23.1 启动失败
如果你的应用启动失败,注册的FailureAnalyzers
就有机会提供一个特定的错误信息和一个具体的解决问题的行为。例如,如果你再8080端口启动一个应用,而这端口已经被占用,你应该会看到和下面类似的信息:
- 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.
note:Spring Boot 提供多种不同的FailureAnalyzer
实现,你可以添加自己的实现
如果没有用以处理异常的失败分析器,你仍然可以展示全部的状况报告,来更好的明白哪里出错了。为了这样做,你需要提供debug属性或者为org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener
提供DEBUG级别记录。例如,如果你通过java -jar
运行你的应用,你可以像下面这样提供debug属性:
- $ java -jar myproject-0.0.1-SNAPSHOT.jar --debug
23.2 定制Banner
启动时打印出的横幅(Banner)可以被修改,通过在classpath下添加一个banner.txt
文件或者设置spring.banner.location
属性定位到这样一个文件。如果这个文件的编码不是UTF-8,你可以设置spring.banner.charset
。除了一个txt文件,你也可以添加一个banner.gif
、banner.jpg
或者banner.png
图像文件在classpath下,或者设置spring.banner.image.location
属性。图像被转换成ASCII字符画并在所有文本横幅之上打印。在banner.txt
文件内,你可以使用如下占位符:
Variable | Description |
${application.version} |
The version number of your application, as declared in MANIFEST.MF . For example,Implementation-Version: 1.0 is printed as 1.0 |
${application.formatted-version} | The version number of your application, as declared in MANIFEST.MF and formatted for display (surrounded with brackets and prefixed with v). For example (v1.0). |
${spring-boot.version} |
The Spring Boot version that you are using. For example 2.0.2.RELEASE. |
${spring-boot.formatted-version} |
|
${Ansi.NAME} (or ${AnsiColor.NAME} |
|
${AnsiBackground.NAME}, ${AnsiStyle.NAME} |
|
${application.title} |
note:
SpringApplication.setBanner(…)
方法可以被使用,如果你想自己生成一个banner。使用org.springframework.boot.Banner
接口,实现你自己的printBanner()
方法
你也可以使用
spring.main.banner-mode
属性,以此决定banner是否打印在终端(console),写进日志(log)或者不生成(off)。
23.3 定制SpringApplication
如果默认的SpringApplication不合你的口味,你可以替代的创建一个本地实例定制它。例如,为了关掉banner,你可以写:
- public static void main(String[] args) {
- SpringApplication app = new SpringApplication(MySpringConfiguration.class);
- app.setBannerMode(Banner.Mode.OFF);
- app.run(args);
- }
note:
通过文件application.properties
也可以配置SpringApplication。更多细节查阅24章。一个完整的配置项列表,查阅javadoc。
23.4 Fluent Builder API
23.5 应用事件和监听器
除了通常的Spring Framework事件,如ContextRefreshedEvent
,SpringApplication
发送一些别的应用事件。
note:一些事件在ApplicationContext
创建之前触发,因此你不能以@Bean
的方式在那些事件上注册监听器,你可以使用SpringApplication.addListeners(…)
方法和SpringApplicationBuilder.listeners(…)
方法注册这些监听器。如果你希望这些监听器被自动注册,而不管应用创建的方式,你可以添加一个META-INF/spring.factories
文件在你的工程中,通过使用键org.springframework.context.ApplicationListener
指向你的监听器,就像下面的例子:
- org.springframework.context.ApplicationListener=com.example.project.MyListener
随着你的应用运行,应用事件以下面的顺序被发送:
- 一个
ApplicationStartingEvent
事件被发送,在运行开始,任何执行之前,除了监听器注册和初始化。 - 一个
ApplicationEnvironmentPreparedEvent
事件被发送,当Environment
将在已知上下文中使用,但在创建上下文之前。 - 一个
ApplicationPreparedEvent
事件被发送,在bean定义加载之后,,在refresh开始之前 - 一个
ApplicationStartedEvent
事件被发送,在上下文刷新之后,但在任何应用和命令行执行调用之前 - 一个
ApplicationReadyEvent
事件被发送,在任何应用和命令行执行已经调用之后,它表明应用已经准备服务请求了。 - 一个
ApplicationFailedEvent
事件被发送,如果在启动过程中有异常产生。
note:你常常不需要用到应用事件,但是知道它们的存在是有用的。在内部,Spring Boot使用事件处理各种任务。
应用事件被发送通过使用Spring Framework的事件发布机制。这个机制的一部分是确保被发布到子上下文监听器的事件也会被发布到任何父级上下文的监听器。这样的结果是,如果你的应用使用SpringApplication实例的分层(hierarchy),一个监听器可能会收到多个相同类型的事件的实例。
为了允许你的监听器区分它自身的上下文的事件和派生(descendant)上下文的事件,应该要求它自身的应用上下文被注入然后比较注入的上下文和事件的上下文。上下文可以通过实现ApplicationContextAware
或者如果监听器是一个bean就通过@Autowired
被注入。
23.6 Web 环境
SpringApplication代表你尝试创建正确的ApplicationContext类型,决定WebEnvironmentType
的算法相当地简单:
- 如果Spring MVC出现,使用
AnnotationConfigServletWebServerApplicationContext
- 否则,如果Spring WebFlux出现,使用
AnnotationConfigReactiveWebServerApplicationContext
- 否则,使用
AnnotationConfigApplicationContext
这意味着如果你正在使用Spring MVC并且在相同的应用里从Spring WebFlux新建WebClient
,默认地Spring MVC将被使用,你可以方便地将之重载通过调用setWebApplicationType(WebApplicationType)
通过调用setApplicationContextClass(…)
,完全地控制ApplicationContext
类型也是可能的。
note:当在Junit测试中使用SpringApplication
时,调用setWebApplicationType(WebApplicationType.NONE)
常常是可取的。
23.7 访问应用参数
如果你需要访问那些被传递给SpringApplication.run(…)
的应用参数,你可以注入一个org.springframework.boot.ApplicationArguments
bean。ApplicationArguments
接口不仅提供对原始的(raw,未被处理的)参数的访问也支持解析的option
和no-option
参数,如下面展示的例子:
- import org.springframework.boot.*;
- import org.springframework.beans.factory.annotation.*;
- import org.springframework.stereotype.*;
- @Component
- public class MyBean {
- @Autowired
- public MyBean(ApplicationArguments args) {
- boolean debug = args.containsOption("debug");
- List
files = args.getNonOptionArgs(); // if run with "--debug logfile.txt" debug=true, files=["logfile.txt"] } }
note:Spring Boot也会注册一个含有Spring Environment
的CommandLinePropertySource
。这让你也可以通过@Value
注解注入单个应用参数。
23.8 使用ApplicationRunner 或者 CommandLineRunner
如果你需要一旦SpringApplication
启动就执行一些特定的(specific)代码,你可以实现ApplicationRunner
或者CommandLineRunner
接口。
这两个接口以同样的方式运行,并提供单一的run
方法,这个方法仅在SpringApplication.run(…)
完成前调用。
CommandLineRunner
接口提供对应用参数的访问,把应用参数当做简单的字符数组,而ApplicationRunner
使用之前讨论的ApplicationArguments
接口,下面的例子展示了一个有run
方法的CommandLineRunner
:
- import org.springframework.boot.*;
- import org.springframework.stereotype.*;
- @Component
- public class MyBean implements CommandLineRunner {
- public void run(String... args) {
- // Do something...
- }
- }
如果个别被定义ApplicationRunner或者CommandLineRunner需要以特定的顺序调用,你可以另外实现org.springframework.core.Ordered
接口或者使用org.springframework.core.annotation.Order
注解。
23.9 应用退出
为了确保ApplicationContext
在退出时平和地关闭(close),每个SpringApplication
注册了一个JVM关闭(shutdown)钩子。所有标准的Spring 生命周期回调,如DisposableBean
接口或者@PreDestroy
注解,可以被使用。
此外,当SpringApplication.exit()
被调用时,如果beans希望返回一个特定的退出码(exit code),beans可以实现org.springframework.boot.ExitCodeGenerator
接口。这个退出码之后可以传给System.exit()
,把它作为状态码(status code)返回。如下面例子所示:
- @SpringBootApplication
- public class ExitCodeApplication {
- @Bean
- public ExitCodeGenerator exitCodeGenerator() {
- return () -> 42;
- }
- public static void main(String[] args) {
- System.exit(SpringApplication
- .exit(SpringApplication.run(ExitCodeApplication.class, args)));
- }
- }
ExitCodeGenerator
接口也可以被异常实现。当这样的异常触发时,Spring Boot返回实现了的getExitCode()
方法提供的退出码。
23.10 Admin 特性
为应用提供admin-related特性是可能的,通过指定spring.application.admin.enabled
属性。这在MBeanServer
平台上暴露了SpringApplicationAdminMXBean
。你可以通过这个特性远程地管理你的Spring Boot应用。这个特性对于任何服务包装实现(service wrapper implementation)也是有用的。
note:如果你想知道应用运行在哪个HTTP端口,使用键local.server.port
获取这个属性
caution:当提供这个特性时要小心,因为MBean暴露一个关闭应用的方法。