Spring Boot 官网文档简单翻译 Part X

Part X. Appendices

文档说明：

• 文档对应的版本为 2.1.0.M3
• 这不是文档的完整中文翻译，也有可能跟原文文字不一一对应，只是我阅读文档时候做的简单笔记
• 如果对应的章节没有任何中文，有可能是文档内容比较少，建议直接看原文，或者是我不感兴趣的部分
• 目录标题没有做翻译，首先标题一般一眼就能看懂什么意思，不做翻译还能保证原文意思，其次也方便对应到原文位置

A. Common application properties

主要介绍 application.properties 可以配置的项。

完整的 sample 文件可到官网文档查看，下面提取一下主要有哪几类配置内容：

# CORE PROPERTIES
    ## LOGGING
    ## AOP
    ## IDENTITY (ContextIdApplicationContextInitializer)
    ## ADMIN (SpringApplicationAdminJmxAutoConfiguration)
    ## AUTO-CONFIGURATION
    ## BANNER
    ## SPRING CORE
    ## SPRING CACHE (CacheProperties)
    ## SPRING CONFIG - using environment property only (ConfigFileApplicationListener)
    ## HAZELCAST (HazelcastProperties)
    ## PROJECT INFORMATION (ProjectInfoProperties)
    ## JMX
    ## Email (MailProperties)
    ## APPLICATION SETTINGS (SpringApplication)
    ## FILE ENCODING (FileEncodingApplicationListener)
    ## INTERNATIONALIZATION (MessageSourceProperties)
    ## OUTPUT
    ## PID FILE (ApplicationPidFileWriter)
    ## PROFILES
    ## QUARTZ SCHEDULER (QuartzProperties)
    ## REACTOR (ReactorCoreProperties)
    ## SENDGRID (SendGridAutoConfiguration)
    ## TASK EXECUTION  (TaskExecutionProperties)
    ## TASK SCHEDULING  (TaskSchedulingProperties)
# WEB PROPERTIES
    ## EMBEDDED SERVER CONFIGURATION (ServerProperties)
    ## FREEMARKER (FreeMarkerProperties)
    ## GROOVY TEMPLATES (GroovyTemplateProperties)
    ## SPRING HATEOAS (HateoasProperties)
    ## HTTP (HttpProperties)
    ## MULTIPART (MultipartProperties)
    ## JACKSON (JacksonProperties)
    ## GSON (GsonProperties)
    ## JERSEY (JerseyProperties)
    ## SPRING LDAP (LdapProperties)
    ## EMBEDDED LDAP (EmbeddedLdapProperties)
    ## MUSTACHE TEMPLATES (MustacheAutoConfiguration)
    ## SPRING MVC (WebMvcProperties)
    ## SPRING RESOURCES HANDLING (ResourceProperties)
    ## SPRING SESSION (SessionProperties)
    ## SPRING SESSION HAZELCAST (HazelcastSessionProperties)
    ## SPRING SESSION JDBC (JdbcSessionProperties)
    ## SPRING SESSION MONGODB (MongoSessionProperties)
    ## SPRING SESSION REDIS (RedisSessionProperties)
    ## THYMELEAF (ThymeleafAutoConfiguration)
    ## SPRING WEBFLUX (WebFluxProperties)
    ## SPRING WEB SERVICES (WebServicesProperties)
# SECURITY PROPERTIES
    ## SECURITY (SecurityProperties)
    ## SECURITY OAUTH2 CLIENT (OAuth2ClientProperties)
    ## SECURITY OAUTH2 RESOURCE SERVER (OAuth2ResourceServerProperties)
# DATA PROPERTIES
    ## FLYWAY (FlywayProperties)
    ## LIQUIBASE (LiquibaseProperties)
    ## COUCHBASE (CouchbaseProperties)
    ## DAO (PersistenceExceptionTranslationAutoConfiguration)
    ## CASSANDRA (CassandraProperties)
    ## DATA COUCHBASE (CouchbaseDataProperties)
    ## ELASTICSEARCH (ElasticsearchProperties)
    ## DATA LDAP
    ## MONGODB (MongoProperties)
    ## DATA REDIS
    ## NEO4J (Neo4jProperties)
    ## DATA REST (RepositoryRestProperties)
    ## SOLR (SolrProperties)
    ## DATA WEB (SpringDataWebProperties)
    ## DATASOURCE (DataSourceAutoConfiguration & DataSourceProperties)
    ## JEST (Elasticsearch HTTP client) (JestProperties)
    ## Elasticsearch REST clients (RestClientProperties)
    ## H2 Web Console (H2ConsoleProperties)
    ## InfluxDB (InfluxDbProperties)
    ## JOOQ (JooqProperties)
    ## JDBC (JdbcProperties)
    ## JPA (JpaBaseConfiguration, HibernateJpaAutoConfiguration)
    ## JTA (JtaAutoConfiguration)
    ## ATOMIKOS (AtomikosProperties)
    ## BITRONIX
    ## EMBEDDED MONGODB (EmbeddedMongoProperties)
    ## REDIS (RedisProperties)
    ## TRANSACTION (TransactionProperties)
# INTEGRATION PROPERTIES
    ## ACTIVEMQ (ActiveMQProperties)
    ## ARTEMIS (ArtemisProperties)
    ## SPRING BATCH (BatchProperties)
    ## SPRING INTEGRATION (IntegrationProperties)
    ## JMS (JmsProperties)
    ## APACHE KAFKA (KafkaProperties)
    ## RABBIT (RabbitProperties)
# ACTUATOR PROPERTIES
    ## MANAGEMENT HTTP SERVER (ManagementServerProperties)
    ## CLOUDFOUNDRY
    ## ENDPOINTS GENERAL CONFIGURATION
    ## ENDPOINTS JMX CONFIGURATION (JmxEndpointProperties)
    ## ENDPOINTS WEB CONFIGURATION (WebEndpointProperties)
    ## ENDPOINTS CORS CONFIGURATION (CorsEndpointProperties)
    ## AUDIT EVENTS ENDPOINT (AuditEventsEndpoint)
    ## BEANS ENDPOINT (BeansEndpoint)
    ## CACHES ENDPOINT (CachesEndpoint)
    ## CONDITIONS REPORT ENDPOINT (ConditionsReportEndpoint)
    ## CONFIGURATION PROPERTIES REPORT ENDPOINT (ConfigurationPropertiesReportEndpoint, ConfigurationPropertiesReportEndpointProperties)
    ## ENVIRONMENT ENDPOINT (EnvironmentEndpoint, EnvironmentEndpointProperties)
    ## FLYWAY ENDPOINT (FlywayEndpoint)
    ## HEALTH ENDPOINT (HealthEndpoint, HealthEndpointProperties)
    ## HEAP DUMP ENDPOINT (HeapDumpWebEndpoint)
    ## HTTP TRACE ENDPOINT (HttpTraceEndpoint)
    ## INFO ENDPOINT (InfoEndpoint)
    ## INTEGRATION GRAPH ENDPOINT (IntegrationGraphEndpoint)
    ## JOLOKIA ENDPOINT (JolokiaProperties)
    ## LIQUIBASE ENDPOINT (LiquibaseEndpoint)
    ## LOG FILE ENDPOINT (LogFileWebEndpoint, LogFileWebEndpointProperties)
    ## LOGGERS ENDPOINT (LoggersEndpoint)
    ## REQUEST MAPPING ENDPOINT  (MappingsEndpoint)
    ## METRICS ENDPOINT (MetricsEndpoint)
    ## PROMETHEUS ENDPOINT (PrometheusScrapeEndpoint)
    ## SCHEDULED TASKS ENDPOINT (ScheduledTasksEndpoint)
    ## SESSIONS ENDPOINT (SessionsEndpoint)
    ## SHUTDOWN ENDPOINT (ShutdownEndpoint)
    ## THREAD DUMP ENDPOINT (ThreadDumpEndpoint)
    ## HEALTH INDICATORS
    ## HTTP TRACING (HttpTraceProperties)
    ## INFO CONTRIBUTORS (InfoContributorProperties)
    ## METRICS
# DEVTOOLS PROPERTIES
    ## DEVTOOLS (DevToolsProperties)
    ## REMOTE DEVTOOLS (RemoteDevToolsProperties)
# TESTING PROPERTIES

B. Configuration Metadata

Spring Boot jars 包含了一些配置元数据，以支持配置属性。这些文件被设计用来给 IDE 编辑 application.properties 或者 application.yml 文件的时候提供上下文的帮组和自动补全。

B.1 Metadata Format

配置元数据的文件位置在 META-INF/spring-configuration-metadata.json。这份 JSON 格式的配置文件元素有 3 个大类：groups, properties 和 hints

{"groups": [
    {
        "name": "server",
        "type": "org.springframework.boot.autoconfigure.web.ServerProperties",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    },
    {
        "name": "spring.jpa.hibernate",
        "type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate",
        "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties",
        "sourceMethod": "getHibernate()"
    }
    ...
],"properties": [
    {
        "name": "server.port",
        "type": "java.lang.Integer",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    },
    {
        "name": "server.address",
        "type": "java.net.InetAddress",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    },
    {
          "name": "spring.jpa.hibernate.ddl-auto",
          "type": "java.lang.String",
          "description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.",
          "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate"
    }
    ...
],"hints": [
    {
        "name": "spring.jpa.hibernate.ddl-auto",
        "values": [
            {
                "value": "none",
                "description": "Disable DDL handling."
            },
            {
                "value": "validate",
                "description": "Validate the schema, make no changes to the database."
            },
            {
                "value": "update",
                "description": "Update the schema if necessary."
            },
            {
                "value": "create",
                "description": "Create the schema and destroy previous data."
            },
            {
                "value": "create-drop",
                "description": "Create and then destroy the schema at the end of the session."
            }
        ]
    }
]}

B.1.1 Group Attributes

groups 可配置的属性有：name, type, description, sourceType, sourceMethod
各项属性的详细内容可参看文档。

B.1.2 Property Attributes

properties 可配置的属性有：name, type, description, sourceType, defaultValue, deprecation
各项属性的详细内容可参看文档。

properties.deprecation 可配置的属性有：level, reason, replacement

Deprecation 还可以在代码里面声明。

B.1.3 Hint Attributes

hints 可配置的属性有：name, values, providers
hints.values 可配置的属性有：value, descripton
hints.providers 可配置的属性有：name, parameters

B.1.4 Repeated Metadata Items

配置元数据有可能会配置相同 group 和 propterties 的项，即有重复的配置项，解析器应该支持这种场景。

B.2 Providing Manual Hints

Hints 包含两部分内容：

• 可配置值的描述
• 提供相关处理的 provider

B.2.1 Value Hint

配置样例：

{"hints": [
    {
        "name": "sample.contexts.keys",
        "values": [
            {
                "value": "sample1"
            },
            {
                "value": "sample2"
            }
        ]
    }
]}

B.2.2 Value Providers

provider 是约束配置值的语法。
支持的 provider 有：

• any: Permits any additional value to be provided.

• class-reference: Auto-completes the classes available in the project. Usually constrained by a base class that is specified by the target parameter.

• handle-as: Handles the property as if it were defined by the type defined by the mandatory target parameter.

• logger-name: Auto-completes valid logger names. Typically, package and class names available in the current project can be auto-completed.

• spring-bean-reference: Auto-completes the available bean names in the current project. Usually constrained by a base class that is specified by the target parameter.

• spring-profile-name: Auto-completes the available Spring profile names in the project.

C. Auto-configuration classes

这里列出 Spring Boot 提供自动装配逻辑的类，可参看指定的类代码和 javadoc。参看的时候，最好能结合自己应用启动日志来分析。

C.1 From the "spring-boot-autoconfigure" module

列出了 spring-boot-autoconfigure 模块里面自动装配类 和 javadoc 列表。

C.2 From the "spring-boot-actuator-autoconfigure" module

列出了 spring-boot-autoconfigure 模块里面自动装配类 和 javadoc 列表。

D. Test auto-configuration annotations

这里列出 @…Test 的注解自动装配所引入的配置。

E. The Executable Jar Format

spring-boot-loader 模块让 Spring Boot 支持 jar 和 war 文件。Maven 和 Gradle 插件可以打包成一个可执行 jar 文件，如果只是使用，可以不用深入理解生成 jar 的细节。
如果你用其他的构建软件来生成可执行 jar 文件，那么你就需要看看这个章节的内容了。

E.1 Nested JARs

Java 没有提供关于加载嵌入 jar 文件（在 jar 文件里面包含另外的 jar 文件）的标准，命令行这种 jar 文件在不解压就在就可能会有问题。

为解决这个问题，很多开发者都通过共享 jar 的形式来处理。一个共享的 jar 包含了所有的类和 jar，并放进一个 jar 文件里面。这样你很难知道里面包含了多少库的依赖，而且还可能有文件重名的问题。Spring Boot 采取了不同的做法，它让你直接内嵌 jar 文件。

E.1.1 The Executable Jar File Structure

Spring Boot Loader-compatible jar 文件的结构大概如下，应用的 class 文件应该放在 BOOT-INF/classes 目录，依赖的 jar 文件应该放在 BOOT-INF/lib 目录:

example.jar
 |
 +-META-INF
 |  +-MANIFEST.MF
 +-org
 |  +-springframework
 |     +-boot
 |        +-loader
 |           +-
 +-BOOT-INF
    +-classes
    |  +-mycompany
    |     +-project
    |        +-YourClasses.class
    +-lib
       +-dependency1.jar
       +-dependency2.jar

E.1.2 The Executable War File Structure

Spring Boot Loader-compatible war 文件的结构大概如下，依赖的 jar 文件应该放在 WEB-INF/lib 目录，启动嵌入式容器服务需要，但部署到外部容器就不需要的依赖文件放在 WEB-INF/lib-provided 目录:

example.war
 |
 +-META-INF
 |  +-MANIFEST.MF
 +-org
 |  +-springframework
 |     +-boot
 |        +-loader
 |           +-
 +-WEB-INF
    +-classes
    |  +-com
    |     +-mycompany
    |        +-project
    |           +-YourClasses.class
    +-lib
    |  +-dependency1.jar
    |  +-dependency2.jar
    +-lib-provided
       +-servlet-api.jar
       +-dependency3.jar

E.2 Spring Boot’s “JarFile” Class

加载内嵌 jar 文件的核心类是 org.springframework.boot.loader.jar.JarFile。当第一次加载的时候，每个 JarEntry 都会被映射到一个物理文件的偏移量，如下所示：

myapp.jar
+-------------------+-------------------------+
| /BOOT-INF/classes | /BOOT-INF/lib/mylib.jar |
|+-----------------+||+-----------+----------+|
||     A.class      |||  B.class  |  C.class ||
|+-----------------+||+-----------+----------+|
+-------------------+-------------------------+
 ^                    ^           ^
 0063                 3452        3980

有了上面的信息，我们就可以通过查找外层 jar 文件来加载指定内嵌的实体类。我们不需要解压文件，也不需要把文件全部加载到内存。

E.2.1 Compatibility with the Standard Java “JarFile”

Spring Boot Loader 尽量重用现有代码和库的能力，org.springframework.boot.loader.jar.JarFile 是继承 java.util.jar.JarFile 的类，是可插拔的。

E.3 Launching Executable Jars

org.springframework.boot.loader.Launcher 类是一个特殊的启动类，它是可执行 jar 文件的主入口。它是 jar 文件里面的 Main-Class，会被用来设置 URLClassLoader 并最后调用你的 main() 方法。

有 3 个 launcher 的子类(JarLauncher, WarLauncher, and PropertiesLauncher)。它们的意图是从内嵌 jar 文件加载资源文件（例如 .class 等等）。对于 JarLauncher 和 WarLauncher 类，读取路径是固定的，可参看上节内容。PropertiesLauncher 默认查找 BOOT-INF/lib/ 路径，这个路径可以在 LOADER_PATH 或者 loader.properties 文件的 loader.path 配置。

E.3.1 Launcher Manifest

需要配置 META-INF/MANIFEST.MF 文件的 Main-Class 属性指定 Launcher。你实际启动的类（带有 main 方法的类）应在 Start-Class 属性里面配置。

jar 的 MANIFEST.MF 示例:

Main-Class: org.springframework.boot.loader.JarLauncher
Start-Class: com.mycompany.project.MyApplication

war 的 MANIFEST.MF 示例:

Main-Class: org.springframework.boot.loader.WarLauncher
Start-Class: com.mycompany.project.MyApplication

Class-Path 在内嵌 jar 文件中是不需要配置的。

E.3.2 Exploded Archives

有些 PaaS 实现会选择解压包文件后运行，例如 Cloud Foundry 就是真么干的。解决命令如下：

$ unzip -q myapp.jar
$ java org.springframework.boot.loader.JarLauncher

E.4 PropertiesLauncher Features

PropertiesLauncher 有一些在外部配置文件可以启用的功能，例如 System properties, environment variables, manifest entries, or loader.properties 等配置文件，可启用的属性有：

• loader.path
• loader.home
• loader.args
• loader.main
• loader.config.name
• loader.config.location
• loader.system

在配置环境变量或者 manifest entries 的时候，可使用下面的变量：

Key	Manifest entry	Environment variable
loader.path	Loader-Path	LOADER_PATH
loader.home	Loader-Home	LOADER_HOME
loader.args	Loader-Args	LOADER_ARGS
loader.main	Start-Class	LOADER_MAIN
loader.config.location	Loader-Config-Location	LOADER_CONFIG_LOCATION
loader.system	Loader-System	LOADER_SYSTEM

PropertiesLauncher 的几条规则

E.5 Executable Jar Restrictions

在使用 Spring Boot Loader 打包程序的时候，有两个约束需要遵循：

• Zip entry compression: The ZipEntry for a nested jar must be saved by using the
  ZipEntry.STORED method.
• System classLoader: Launched applications should use Thread.getContextClassLoader()
  when loading classes.

E.6 Alternative Single Jar Solutions

• Maven Shade Plugin
• JarClassLoader
• OneJar

F. Dependency versions

Spring BOOT 应用的 POM 依赖第三方库的版本号默认列表。

相关文章

• Spring Boot 官网文档简单翻译 Part I
• Spring Boot 官网文档简单翻译 Part II
• Spring Boot 官网文档简单翻译 Part III
• Spring Boot 官网文档简单翻译 Part IV
• Spring Boot 官网文档简单翻译 Part V
• Spring Boot 官网文档简单翻译 Part VI
• Spring Boot 官网文档简单翻译 Part VII
• Spring Boot 官网文档简单翻译 Part VIII
• Spring Boot 官网文档简单翻译 Part IX
• Spring Boot 官网文档简单翻译 Part X