文档

Ark 包介绍

更新时间:

本文将介绍标准 Ark 包的目录结构,以及如何使用官方插件 sofa-ark-maven-plugin 打包并发布 Ark 包。

Maven 插件

SOFAArk 默认提供的 Maven 插件 sofa-ark-maven-plugin 可以将普通 Java 工程或者 Spring Boot 工程打包成标准格式 Ark 包。基于 Fat Jar 技术,您使用java -jar命令可以直接启动 Ark 包 。Maven 插件坐标为:

<plugin>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>sofa-ark-maven-plugin</artifactId>
    <version>${sofa.ark.version}</version>
</plugin>

Goals 配置

sofa-ark-maven-plugin 插件提供goal: repackage,可以将工程打包成可执行的 Ark 包,如下配置:

<build>
    <plugin>
        <groupId>com.alipay.sofa</groupId>
        <artifactId>sofa-ark-maven-plugin</artifactId>
        <version>${sofa.ark.version}</version>
        <executions>
            <execution>
                <id>default-cli</id>
                <goals>
                    <goal>repackage</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
        <!-- 配置信息 -->
        </configuration>
    </plugin>
</build>

完整配置模板

完整的 sofa-ark-maven-plguin 插件配置模板如下:

<plugins>
    <plugin>
        <groupId>com.alipay.sofa</groupId>
        <artifactId>sofa-ark-maven-plugin</artifactId>
        <version>${sofa.ark.version}</version>
        <executions>
            <execution>
                <id>default-cli</id>
                <goals>
                    <goal>repackage</goal>
                </goals>
                <configuration>
                    <!--ark 包和 Ark Biz 的打包存放目录,默认为工程 build 目录-->
                    <outputDirectory>./target</outputDirectory>
                    
                    <!--设置应用的根目录,用于读取 ${base.dir}/conf/ark/bootstrap.application 配置文件,默认为 ${project.basedir}-->
                    <baseDir>./</baseDir>
                    
                    <!--生成 Ark 包文件名称,默认为 ${artifactId}-->
                    <finalName>demo-ark</finalName>
                    
                    <!--是否跳过执行 goal:repackage,默认为false-->
                    <skip>false</skip>
                    
                    <!--是否打包、安装和发布 Ark Biz,详细参考 Ark Biz 文档,默认为false-->
                    <attach>true</attach>
                    
                    <!--设置 ark 包的 classifier,默认为空-->
                    <arkClassifier>ark</arkClassifier>
                    
                    <!--设置 Ark Biz 的 classifier,默认为 ark-biz-->
                    <bizClassifier>ark-biz</bizClassifier>
                    
                    <!--设置 Ark Biz 的 biz name,默认为 ${artifactId}-->
                    <bizName>demo-ark</bizName>
                    
                    <!--设置 Ark Biz 的 biz version,默认为 ${artifactId}-->
                    <bizVersion>0.0.1</bizVersion>
                    
                    <!--设置 Ark Biz 的 启动优先级,值越小优先级越高,${artifactId}-->
                    <priority>100</priority>
                    
                    <!--设置 Ark Biz 的启动入口,默认会搜索被打 org.springframework.boot.autoconfigure.SpringBootApplication 注解且含有 main 方法的入口类-->
                    <mainClass>com.alipay.sofa.xx.xx.MainEntry</mainClass>
                    
                    <!--设置是否将 scope=provided 的依赖打包,默认为 false-->
                    <packageProvided>false</packageProvided>
                    
                    <!--设置是否生成 Biz 包,默认为true-->
                    <keepArkBizJar>true</keepArkBizJar>
                    
                    <!--针对 Web 应用,设置 context path,默认为 /-->
                    <webContextPath>/</webContextPath>
                    
                    <!--打包 Ark Biz 时,排除指定的包依赖;格式为: ${groupId:artifactId} 或者 ${groupId:artifactId:classifier}-->
                    <excludes>
                        <exclude>org.apache.commons:commons-lang3</exclude>
                    </excludes>
                    
                    <!--打包 Ark Biz 时,排除和指定 groupId 相同的包依赖-->
                    <excludeGroupIds>
                        <excludeGroupId>org.springframework</excludeGroupId>
                    </excludeGroupIds>
                    
                    <!--打包 Ark Biz 时,排除和指定 artifactId 相同的包依赖-->
                    <excludeArtifactIds>
                        <excludeArtifactId>sofa-ark-spi</excludeArtifactId>
                    </excludeArtifactIds>
                    
                    <!--打包 Ark Biz 时,配置不从 Ark Plugin 索引的类;默认情况下,Ark Biz 会优先索引所有 Ark Plugin 的导出类,
                            添加该配置后,Ark Biz 将只在Ark Biz内部加载该类,不再优先委托 Ark Plugin 加载-->
                    <denyImportClasses>
                        <class>com.alipay.sofa.SampleClass1</class>
                        <class>com.alipay.sofa.SampleClass2</class>
                    </denyImportClasses>
                    
                    <!--对应 denyImportClasses 配置,可以配置包级别-->
                    <denyImportPackages>
                        <package>com.alipay.sofa</package>
                        <package>org.springframework.*</package>
                    </denyImportPackages>
                    
                    <!--打包 Ark Biz 时,配置不从 Ark Plugin 索引的资源;默认情况下,Ark Biz 会优先索引所有 Ark Plugin 的导出资源,
                            添加该配置后,Ark Biz 将只在Ark Biz内部寻找该资源,不在从 Ark Plugin 查找-->
                    <denyImportResources>
                        <resource>META-INF/spring/test1.xml</resource>
                        <resource>META-INF/spring/test2.xml</resource>
                    </denyImportResources>
                </configuration>
            </execution>
        </executions>
    </plugin>
</plugins>

配置项含义可以参考上述注释。

构建

以 Spring Boot Web 工程为例,为了生成标准的 Ark 包,操作步骤如下:

  1. 参考配置模板,在 Web 模块的pom.xml文件中配置 sofa-ark-maven-plugin 插件。

  2. 在 Web 模块目录或应用根目录中敲击mvn pacakge命令,即可在配置的outputDirectory目录中生成 Ark 包和 Ark Biz 文件。默认命名分别为 Web 模块${artifactId}${artifactId}-ark-biz

    您也可以分别通过 arkClassifier 和 bizClassifier 设置 classifier。运行mvn install命令,则会安装 Ark 包到本地仓库。如果设置了 attach 为 true,会同时把 Ark Biz 安装到本地仓库。

发布

在工程主 pom 中配置仓库地址,然后敲击mvn deploy命令,即可发布该 Ark 包。

重要

如果设置了attachtrue,Ark Biz 也会发布到仓库。此外 Ark Biz 发布包默认会带上classifier = ark-biz,可以通过 bizClassifier 设置 Ark Biz 的 classifier。

Ark 包典型目录结构

如何打包 Ark 包 为例,普通的 Spring Boot Web 应用打包生成的 Ark 包 目录结构如下:

.
├── META-INF
│    └── MANIFEST.MF
├── SOFA-ARK
│    ├── biz
│    │    └── sofa-ark-sample-springboot-ark-0.6.0-ark-biz.jar
│    └── container
│         └── sofa-ark-all-0.6.0.jar
├── com
│    └── alipay
│         └── sofa
│              └── ark
│                   ├── bootstrap
│                   ├── common
│                   ├── loader
│                   └── spi
└── conf
     └── ark
          └── bootstrap.properties

上述目录结构相关文件和目录说明如下:

  • META-INF/MANIFEST.MF:记录 Ark 包的元信息,其中最关键的信息是 Ark 包的启动入口类Main-Class。文件内容类似如下:

    Manifest-Version:1.0
    web-context-path:/
    Archiver-Version:PlexusArchiver
    Built-By: qilong.zql
    Ark-Biz-Name: sofa-ark-sample-springboot-ark
    Sofa-Ark-Version:0.6.0
    deny-import-packages:
    priority:100
    Main-Class: com.alipay.sofa.ark.bootstrap.ArkLauncher
    deny-import-classes:
    Ark-Container-Root: SOFA-ARK/container/
    deny-import-resources:
    Ark-Biz-Version:0.6.0
    Created-By:ApacheMaven3.2.5
    Build-Jdk:1.8.0_101

    可以看到,Ark 包启动入口类是com.alipay.sofa.ark.bootstrap.ArkLauncher

  • com/alipay/sofa/ark/*:存放使用 java -jar 命令启动 Ark 包所必需的引导类。

  • SOFA-ARK/container:存放 ark container 容器依赖包,如下所示:

    <dependency>
         <groupId>com.alipay.sofa</groupId>
         <artifactId>sofa-ark-all</artifactId>
         <version>${sofa.ark.version}</version>
    </dependency>
  • SOFA-ARK/biz:存放所有的 Ark Biz 包,因为示例工程中没有依赖其他的 Ark Biz,因此只有自身的 Ark Biz。

  • SOFA-ARK/plugin:在该示例工程中,没有生成这个目录,因为工程中没有依赖其他的 Ark Plugin。

  • conf/ark/properties:SOFAArk 的容器配置文件,在该示例工程中,设置了 SOFAArk 日志生成路径。