可执行 Jar

1. 嵌套 JAR

Java 不提供任何标准方法来加载嵌套的 jar 文件（即，本身包含在 jar 中的 jar 文件）。如果您需要分发一个无需解压缩即可从命令行运行的独立应用程序，这可能会出现问题。spring-doc.cadn.net.cn

为了解决这个问题，许多开发人员使用“阴影”jar。阴影 jar 将所有 jar 中的所有类打包到一个 “uber jar” 中。着色 jar 的问题在于，很难看到您的应用程序中实际存在哪些库。如果在多个 jar 中使用相同的文件名（但内容不同），也可能出现问题。 Spring Boot 采用不同的方法，让您实际上直接嵌套 jar。spring-doc.cadn.net.cn

1.1. 可执行 jar 文件结构

与 Spring Boot Loader 兼容的 jar 文件应按以下方式构建：spring-doc.cadn.net.cn

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

应用程序类应放置在嵌套的BOOT-INF/classes目录。依赖项应放置在嵌套的BOOT-INF/lib目录。spring-doc.cadn.net.cn

1.2. 可执行的 war 文件结构

与 Spring Boot Loader 兼容的 war 文件应按以下方式构建：spring-doc.cadn.net.cn

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

依赖项应放置在嵌套的WEB-INF/lib目录。运行嵌入式容器时需要但在部署到传统 Web 容器时不需要的任何依赖项都应放在WEB-INF/lib-provided.spring-doc.cadn.net.cn

1.3. 索引文件

Spring Boot Loader 兼容的 jar 和 war 档案可以在BOOT-INF/目录。一个classpath.idx文件可以为 JAR 和 WAR 提供，并且它提供了应将 JAR 添加到 Classpath 的顺序。这layers.idx文件只能用于 jar，它允许将 jar 拆分为逻辑层以创建 Docker/OCI 映像。spring-doc.cadn.net.cn

索引文件遵循 YAML 兼容语法，因此第三方工具可以轻松解析它们。但是，这些文件在内部不会解析为 YAML，它们必须以下面描述的格式编写才能使用。spring-doc.cadn.net.cn

1.4. 类路径索引

类路径索引文件可以在BOOT-INF/classpath.idx. 通常，它是由 Spring Boot 的 Maven 和 Gradle 构建插件自动生成的。它提供了一个 jar 名称（包括目录）的列表，其顺序是它们应该添加到 Classpath 中的顺序。当由 build 插件生成时，此 classpath 排序与 build system 用于运行和测试应用程序的 classpath 排序匹配。每行必须以破折号（）开头，名称必须用双引号括起来。"-·"spring-doc.cadn.net.cn

例如，给定以下 jar：spring-doc.cadn.net.cn

example.jar
 |
 +-META-INF
 |  +-...
 +-BOOT-INF
    +-classes
    |  +...
    +-lib
       +-dependency1.jar
       +-dependency2.jar

索引文件将如下所示：spring-doc.cadn.net.cn

- "BOOT-INF/lib/dependency2.jar"
- "BOOT-INF/lib/dependency1.jar"

1.5. 图层索引

layers 索引文件可以在BOOT-INF/layers.idx. 它提供了一个层列表以及应包含在其中的 jar 部分。层按照应添加到 Docker/OCI 映像的顺序写入。图层名称写为带引号的字符串，前缀为破折号（）和冒号（"-·"":"）后缀。图层内容是文件或目录名称，以带引号的字符串编写，前缀为 space、space、dash space、（）。目录名称以结尾，文件名则不以 . 结尾。使用目录名称时，表示该目录内的所有文件都位于同一层中。"··-·"/spring-doc.cadn.net.cn

层索引的一个典型示例是：spring-doc.cadn.net.cn

- "dependencies":
  - "BOOT-INF/lib/dependency1.jar"
  - "BOOT-INF/lib/dependency2.jar"
- "application":
  - "BOOT-INF/classes/"
  - "META-INF/"

2. Spring Boot 的 “JarFile” 类

用于支持加载嵌套 jar 的核心类是org.springframework.boot.loader.jar.JarFile. 它允许您从标准 jar 文件或嵌套的子 jar 数据加载 jar 内容。首次加载时，每个JarEntry映射到外部 jar 的物理文件偏移量，如以下示例所示：spring-doc.cadn.net.cn

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

前面的示例显示了A.class可以在/BOOT-INF/classes在myapp.jarat 位置0063.B.class实际上可以在myapp.jarat 位置3452和C.class位于3980.spring-doc.cadn.net.cn

有了这些信息，我们可以通过查找外部 jar 的适当部分来加载特定的嵌套条目。我们不需要解压缩存档，也不需要将所有 entry 数据读入内存。spring-doc.cadn.net.cn

2.1. 与标准 Java “JarFile” 的兼容性

Spring Boot Loader 努力保持与现有代码和库的兼容性。org.springframework.boot.loader.jar.JarFile延伸自java.util.jar.JarFile并且应该可以作为直接替代品。这getURL()method 返回一个URL这将打开与java.net.JarURLConnection并且可以与 Java 的URLClassLoader.spring-doc.cadn.net.cn

3. 启动可执行 Jar

这org.springframework.boot.loader.Launcherclass 是一个特殊的引导类，用作可执行 jar 的主入口点。这是实际的Main-Class在您的 jar 文件中，它用于设置适当的URLClassLoader并最终调用您的main()方法。spring-doc.cadn.net.cn

有三个Starters子类（JarLauncher,WarLauncher和PropertiesLauncher). 它们的目的是加载资源（.class文件等），来自目录中的嵌套 jar 文件或 war 文件（而不是 Classpath 上显式的 WAR 文件）。在JarLauncher和WarLauncher，则嵌套路径是固定的。JarLauncher查找范围BOOT-INF/lib/和WarLauncher查找范围WEB-INF/lib/和WEB-INF/lib-provided/. 如果需要更多，可以在这些位置添加额外的 jar。这PropertiesLauncher查找范围BOOT-INF/lib/在您的应用程序存档中。您可以通过设置名为LOADER_PATH或loader.path在loader.properties（这是目录、存档或存档中的目录的逗号分隔列表）。spring-doc.cadn.net.cn

3.1. Starters清单

您需要指定适当的Launcher作为Main-Class属性META-INF/MANIFEST.MF. 要启动的实际类（即包含mainmethod）应在Start-Class属性。spring-doc.cadn.net.cn

以下示例显示了一个典型的MANIFEST.MF对于可执行 jar 文件：spring-doc.cadn.net.cn

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

对于 war 文件，它如下所示：spring-doc.cadn.net.cn

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

您无需指定Class-Path条目。类路径是从嵌套的 jar 中推导出来的。

4. PropertiesLauncher 功能

PropertiesLauncher具有一些可以通过外部属性（系统属性、环境变量、清单条目或loader.properties). 下表描述了这些属性：spring-doc.cadn.net.cn

钥匙目的

钥匙	目的
`loader.path`spring-doc.cadn.net.cn	逗号分隔的类路径，例如`lib,${HOME}/app/lib`. 较早的条目优先，就像常规的`-classpath`在`javac`命令行。spring-doc.cadn.net.cn
`loader.home`spring-doc.cadn.net.cn	用于解析`loader.path`. 例如，给定`loader.path=lib`然后`${loader.home}/lib`是 Classpath 位置（以及该目录中的所有 jar 文件）。此属性还用于查找`loader.properties`文件，如以下示例所示`/opt/app`它默认为`${user.dir}`.spring-doc.cadn.net.cn
`loader.args`spring-doc.cadn.net.cn	main 方法的默认参数（以空格分隔）。spring-doc.cadn.net.cn
`loader.main`spring-doc.cadn.net.cn	要启动的主类的名称（例如`com.app.Application`).spring-doc.cadn.net.cn
`loader.config.name`spring-doc.cadn.net.cn	属性文件的名称（例如`launcher`). 它默认为`loader`.spring-doc.cadn.net.cn
`loader.config.location`spring-doc.cadn.net.cn	属性文件的路径（例如`classpath:loader.properties`). 它默认为`loader.properties`.spring-doc.cadn.net.cn
`loader.system`spring-doc.cadn.net.cn	Boolean 标志，指示应将所有属性添加到系统属性中。它默认为`false`.spring-doc.cadn.net.cn

loader.pathspring-doc.cadn.net.cn

逗号分隔的类路径，例如lib,${HOME}/app/lib. 较早的条目优先，就像常规的-classpath在javac命令行。spring-doc.cadn.net.cn

loader.homespring-doc.cadn.net.cn

用于解析loader.path. 例如，给定loader.path=lib然后${loader.home}/lib是 Classpath 位置（以及该目录中的所有 jar 文件）。此属性还用于查找loader.properties文件，如以下示例所示/opt/app它默认为${user.dir}.spring-doc.cadn.net.cn

loader.argsspring-doc.cadn.net.cn

main 方法的默认参数（以空格分隔）。spring-doc.cadn.net.cn

loader.mainspring-doc.cadn.net.cn

要启动的主类的名称（例如com.app.Application).spring-doc.cadn.net.cn

loader.config.namespring-doc.cadn.net.cn

属性文件的名称（例如launcher). 它默认为loader.spring-doc.cadn.net.cn

loader.config.locationspring-doc.cadn.net.cn

属性文件的路径（例如classpath:loader.properties). 它默认为loader.properties.spring-doc.cadn.net.cn

loader.systemspring-doc.cadn.net.cn

Boolean 标志，指示应将所有属性添加到系统属性中。它默认为false.spring-doc.cadn.net.cn

当指定为环境变量或清单条目时，应使用以下名称：spring-doc.cadn.net.cn

钥匙清单条目环境变量

钥匙	清单条目	环境变量
`loader.path`spring-doc.cadn.net.cn	`Loader-Path`spring-doc.cadn.net.cn	`LOADER_PATH`spring-doc.cadn.net.cn
`loader.home`spring-doc.cadn.net.cn	`Loader-Home`spring-doc.cadn.net.cn	`LOADER_HOME`spring-doc.cadn.net.cn
`loader.args`spring-doc.cadn.net.cn	`Loader-Args`spring-doc.cadn.net.cn	`LOADER_ARGS`spring-doc.cadn.net.cn
`loader.main`spring-doc.cadn.net.cn	`Start-Class`spring-doc.cadn.net.cn	`LOADER_MAIN`spring-doc.cadn.net.cn
`loader.config.location`spring-doc.cadn.net.cn	`Loader-Config-Location`spring-doc.cadn.net.cn	`LOADER_CONFIG_LOCATION`spring-doc.cadn.net.cn
`loader.system`spring-doc.cadn.net.cn	`Loader-System`spring-doc.cadn.net.cn	`LOADER_SYSTEM`spring-doc.cadn.net.cn

loader.pathspring-doc.cadn.net.cn

Loader-Pathspring-doc.cadn.net.cn

LOADER_PATHspring-doc.cadn.net.cn

loader.homespring-doc.cadn.net.cn

Loader-Homespring-doc.cadn.net.cn

LOADER_HOMEspring-doc.cadn.net.cn

loader.argsspring-doc.cadn.net.cn

Loader-Argsspring-doc.cadn.net.cn

LOADER_ARGSspring-doc.cadn.net.cn

loader.mainspring-doc.cadn.net.cn

Start-Classspring-doc.cadn.net.cn

LOADER_MAINspring-doc.cadn.net.cn

loader.config.locationspring-doc.cadn.net.cn

Loader-Config-Locationspring-doc.cadn.net.cn

LOADER_CONFIG_LOCATIONspring-doc.cadn.net.cn

loader.systemspring-doc.cadn.net.cn

Loader-Systemspring-doc.cadn.net.cn

LOADER_SYSTEMspring-doc.cadn.net.cn

构建插件会自动将Main-Class属性设置为Start-Class当 fat jar 构建完成时。如果使用该选项，请使用Main-Class属性并省略Start-Class.

以下规则适用于使用PropertiesLauncher:spring-doc.cadn.net.cn

loader.properties在loader.home，然后在 Classpath 的根目录中，然后在classpath:/BOOT-INF/classes. 使用具有该名称的文件所在的第一个位置。spring-doc.cadn.net.cn
loader.home是附加属性文件的目录位置（覆盖默认值），仅当loader.config.location未指定。spring-doc.cadn.net.cn
loader.path可以包含目录（以递归方式扫描 jar 和 zip 文件）、存档路径、存档中扫描 jar 文件的目录（例如dependencies.jar!/lib）或通配符模式（用于默认 JVM 行为）。归档路径可以是相对于loader.home或文件系统中具有jar:file:前缀。spring-doc.cadn.net.cn
loader.path（如果为空）默认为BOOT-INF/lib（如果从存档运行，则表示本地目录或嵌套目录）。正因为如此，PropertiesLauncher的行为与JarLauncher未提供其他配置时。spring-doc.cadn.net.cn
loader.path不能用于配置位置loader.properties（用于搜索后者的类路径是 JVM 类路径，当PropertiesLauncher启动）。spring-doc.cadn.net.cn
占位符替换是在使用之前根据 System 和 environment variables 以及 properties 文件本身对所有值完成的。spring-doc.cadn.net.cn
属性的搜索顺序（在多个位置查找是有意义的）是环境变量、系统属性、loader.properties、exploded archive 清单和 archive 清单。spring-doc.cadn.net.cn

5. 可执行 Jar 限制

在使用 Spring Boot Loader 打包的应用程序时，需要考虑以下限制：spring-doc.cadn.net.cn

Zip entry 压缩：这ZipEntry，因为嵌套的 jar 必须使用ZipEntry.STORED方法。这是必需的，以便我们可以直接查找嵌套 jar 中的单个内容。嵌套 jar 文件本身的内容仍然可以压缩，外部 jar 中的任何其他条目也可以压缩。spring-doc.cadn.net.cn

系统 classLoader 中：启动的应用程序应使用Thread.getContextClassLoader()加载类时（默认情况下，大多数库和框架都会这样做）。尝试使用ClassLoader.getSystemClassLoader()失败。java.util.Logging始终使用 System 类加载器。因此，您应该考虑不同的日志记录实现。spring-doc.cadn.net.cn

6. 替代单罐解决方案

如果上述限制意味着您不能使用 Spring Boot Loader，请考虑以下替代方案：spring-doc.cadn.net.cn