Ark Plugin
本文将介绍 Ark Plugin
的标准规范和目录结构,以及如何使用官方插件 sofa-ark-plugin-maven-plugin
打包发布 Ark Plugin
。
插件规范
标准的 Ark Plugin
需要满足以下规范:
插件必须配置插件名,默认为
${artifactId}
;运行时,不允许存在同名的插件,可以认为它是Ark Plugin
的唯一 ID。插件必须配置优先级,默认为 1000,数字越低表示优先级越高。
插件最多配置一个入口类
activator
,它是容器启动插件的入口,统一实现。com.alipay.sofa.ark.spi.service.PluginActivator
接口类;优先级高的插件优先启动。导入类支持 package 和 class 两个级别;导入类优先从其他的插件加载。
导出类支持 package 和 class 两个级别;优先级高的插件优先导出。
支持导入 classpath 中资源,不支持通配符;优先从其他插件中查找指定资源。
支持导出 classpath 中资源,不支持通配符;优先级高的插件优先导出。
Maven 插件
官方提供 Maven
插件 sofa-ark-plugin-maven-plugin
可以将工程打包成标准格式的 Ark Plugin
。Maven
插件坐标为:
<plugin>
<groupId>com.alipay.sofa</groupId>
<artifactId>sofa-ark-plugin-maven-plugin</artifactId>
<version>${demo.version}</version>
</plugin>
Goals 配置
sofa-ark-plugin-maven-plugin
插件提供 goal: ark-plugin
,可以将工程打包成标准格式的 Ark Plugin
,如下配置:
<build>
<plugin>
<groupId>com.alipay.sofa</groupId>
<artifactId>sofa-ark-plugin-maven-plugin</artifactId>
<version>${sofa.ark.version}</version>
<executions>
<execution>
<id>default-cli</id>
<goals>
<goal>ark-plugin</goal>
</goals>
</execution>
</executions>
<configuration>
<!-- 配置信息 -->
</configuration>
</plugin>
</build>
完整配置模板
完整的 sofa-ark-plugin-maven-plugin
插件配置模板如下:
<plugins>
<plugin>
<groupId>com.alipay.sofa</groupId>
<artifactId>sofa-ark-plugin-maven-plugin</artifactId>
<version>${sofa.ark.version}</version>
<executions>
<execution>
<id>default-cli</id>
<goals>
<goal>ark-plugin</goal>
</goals>
<configuration>
<!--指定打包的 ${pluginName}.ark.plugin 存放目录;默认放在 ${project.build.directory}-->
<outputDirectory>./</outputDirectory>
<!--是否把 ark plugin 安装、发布到仓库,默认为true-->
<attach>true</attach>
<!--ark plugin 最多仅能指定一个 com.alipay.sofa.ark.spi.service.PluginActivator 接口实现类-->
<activator>com.alipay.sofa.ark.service.impl.SampleActivator</activator>
<!--配置优先级,数字越小,优先级越高,优先启动,优先导出类,默认1000-->
<priority>2000</priority>
<!--配置插件的名字,务必配置对,运行时,是插件的唯一标识 ID。比如 sofa-rpc 插件,可以配置为 sofa-rpc;默认为 ${artifactId}-->
<pluginName>${ark.plugin.name}</pluginName>
<!--设置 ark plugin 的 classifier,默认为空,如非必要,建议不用设置-->
<classifier>ark-plugin</classifier>
<!--配置导入类、资源-->
<imported>
<!--配置需要优先从其他 ark plugin 加载的 package-->
<packages>
<package>javax.servlet</package>
<package>org.springframework.*</package>
</packages>
<!--配置需要优先从其他 ark plugin 加载的 class -->
<classes>
<class>com.alipay.sofa.rpc.config.ProviderConfig</class>
</classes>
<!--配置需要优先从其他 ark plugin 加载的资源-->
<resources>
<resource>META-INF/spring/bean.xml</resource>>
</resources>
</imported>
<!--配置导出类、资源-->
<exported>
<!--配置包级别导出的类-->
<packages>
<package>com.alipay.sofa.ark.service</package>
</packages>
<!--配置类级别导出类-->
<classes>
<class>com.alipay.sofa.ark.common.CommonUtils</class>
<class>com.alipay.sofa.mock</class>
</classes>
<!--配置 ark plugin 对外导出的资源-->
<resources>
<resource>META-INF/spring/bean.xml</resource>>
</resources>
</exported>
<!--打包插件时,排除指定的包依赖;格式为:${groupId:artifactId}或者 ${groupId:artifactId:classifier}-->
<excludes>
<exclude>org.apache.commons:commons-lang3</exclude>
</excludes>
<!--打包插件时,排除和指定 groupId 相同的包依赖-->
<excludeGroupIds>
<excludeGroupId>org.springframework</excludeGroupId>
</excludeGroupIds>
<!--打包插件时,排除和指定 artifactId 相同的包依赖-->
<excludeArtifactIds>
<excludeArtifactId>sofa-ark-spi</excludeArtifactId>
</excludeArtifactIds>
<!--将指定的 Jar 包 shade 至 ark plugin-->
<shades>
<shade>groupId:artifactId[:classifier]:version</shade>
</shades>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
配置项含义如下:
outputDirectory
: 指定打包的 ${pluginName}.ark.plugin 存放目录;默认放在 ${project.build.directory}。attach
: 是否把 ark plugin 安装、发布到仓库,默认为true。activator
: ark plugin 最多仅能指定一个com.alipay.sofa.ark.spi.service.PluginActivator
接口实现类。priority
: 配置优先级,数字越小,优先级越高,优先启动,优先导出类,默认1000。pluginName
: 配置插件的名字,务必配置对,运行时,是插件的唯一标识 ID。比如 sofa-rpc 插件,可以配置为 sofa-rpc; 默认为 ${artifactId}。imported
: 配置导入类、资源;需要注意一点,配置 package 级别的导入类时,如果包名末尾带通配符*
,则表示满足该 package 前缀的包或者类全部被导入。如果不带通配符*
,则表示满足该 package 前缀的类才会被导入,而子包不会被导入。exported
: 配置导出类、资源;同样需要注意一点,配置 package 级别的导出类时,如果包名末尾带通配符*
,则表示满足该 package 前缀的包或者类全部被导出。如果不带通配符*
,则表示满足该 package 前缀的类才会被导出,而子包不会被导出。excludes
: 打包插件时,排除指定的包依赖;格式为:${groupId:artifactId} 或者 ${groupId:artifactId:classifier}。excludeGroupIds
: 打包插件时,排除和指定 groupId 相同的包依赖。excludeArtifactIds
: 打包插件时,排除和指定 artifactId 相同的包依赖。classifier
: 如非必要,建议不用设置,默认为空,只会打包生成 ark plugin;如果配置不为空,则会额外打包生成普通的 Jar 包。shades
: 打包插件时,将指定的 Jar 包 shade 进入 ark plugin。
构建
对于普通的 Java 工程,为了生成标准的 Ark Plugin
,操作步骤如下:
在工程根目录中新建一个空模块打包
Ark Plugin
,定义插件坐标,假设为:<dependency> <groupId>com.alipay.sofa</groupId> <artifactId>sofa-ark-plugin-demo</artifactId> <version>1.0.0</version> </dependency>
在该模块的 pom.xml 文件中,添加工程其他模块和三方包依赖,并配置模板配置
sofa-ark-plugin-maven-plugin
插件。在该模块目录或工程根目录中敲击
mvn package
命令,即可在配置的outputDirectory
目录中生成ark-plugin-demo.ark.plugin
插件文件;敲击mvn install
命令,则会安装到本地Maven
仓库。
发布
在工程主 pom 中配置仓库地址,然后敲击 mvn deploy
命令,即可发布该 Ark Plugin
;需要指出的是,如果没有设置 classifier
,则生成的 ark plugin 坐标为:
<dependency>
<groupId>com.alipay.sofa</groupId>
<artifactId>sofa-ark-plugin-demo</artifactId>
<version>1.0.0</version>
</dependency>
如果设置了 classifier=ark-plugin
,发布的 Ark Plugin
坐标会带上 classifier = ark-plugin
;则生成的 ark plugin 坐标为:
<dependency>
<groupId>com.alipay.sofa</groupId>
<artifactId>sofa-ark-plugin-demo</artifactId>
<classifier>ark-plugin</classifier>
<version>1.0.0</version>
</dependency>
其他应用通过该坐标即可引用该插件。
Ark Plugin 典型目录结构
以 如何打包 Ark Plugin 为例,该示例工程打包生成的 ark plugin 目录结构如下:
.
├── META-INF
│├── MANIFEST.MF
│└── maven
│└── com.alipay.sofa
│└── sample-ark-plugin
│├── pom.properties
│└── pom.xml
├── com
│└── alipay
│└── sofa
│└── ark
│├── plugin
││└── mark
│└── sample
│├── activator
│├── facade
│└── impl
└── lib
├── sample-ark-plugin-0.6.0.jar
├── sample-ark-plugin-common-0.6.0.jar
├── sofa-ark-exception-0.6.0.jar
└── sofa-ark-spi-0.6.0.jar
上述目录结构相关文件和目录说明如下:
com/alipay/sofa/ark/plugin/mark
:标记文件,标记该 Jar 包是sofa-ark-plugin-maven-plugin
打包生成的Ark Plugin
文件。META-INF/MANIFEST.MF
:记录插件元信息,内容类似如下。Manifest-Version:1.0 groupId: com.alipay.sofa artifactId: sample-ark-plugin version:0.6.0 priority:100 pluginName: sample-ark-plugin description: activator: com.alipay.sofa.ark.sample.activator.SamplePluginActivator import-packages: import-classes: import-resources: export-packages: com.alipay.sofa.ark.sample.common export-classes: com.alipay.sofa.ark.sample.facade.SamplePluginService export-resources:Sample_Resource_Exported
lib/
:lib 目录存放插件工程依赖的普通 Jar 包,一般包含插件需要和其他插件或者业务有隔离需求的 Jar 包;插件配置的导出类都包含在这些 Jar 包中。com/alipay/sofa/ark/sample/*
:ark plugin 模块中包含的类文件