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 插件坐标为：

  1. <plugin>
  2.     <groupId>com.alipay.sofa</groupId>
  3.     <artifactId>sofa-ark-plugin-maven-plugin</artifactId>
  4.     <version>0.2.0</version>
  5. </plugin>

Goals

sofa-ark-plugin-maven-plugin 插件提供 goal: ark-plugin，可以将工程打包成标准格式的 Ark Plugin, 如下配置：

  1. <build>
  2.     <plugin>
  3.         <groupId>com.alipay.sofa</groupId>
  4.         <artifactId>sofa-ark-plugin-maven-plugin</artifactId>
  5.         <version>0.2.0</version>
  6.         <executions>
  7.             <execution>
  8.                 <id>default-cli</id>
  9.                 <goals>
  10.                     <goal>ark-plugin</goal>
  11.                 </goals>
  12.             </excution>
  13.         </executions>
  14.         <configuration>
  15.             <!-- 配置信息 -->
  16.         </configuration>
  17.     </plugin>
  18. </build>

完整配置模板

完整的 sofa-ark-plugin-maven-plugin 插件配置模板如下：

  1. <plugins>
  2.     <plugin>
  3.         <groupId>com.alipay.sofa</groupId>
  4.         <artifactId>sofa-ark-plugin-maven-plugin</artifactId>
  5.         <version>0.2.0</version>
  6.         <executions>
  7.             <execution>
  8.                 <id>default-cli</id>
  9.                 <goals>
  10.                     <goal>ark-plugin</goal>
  11.                 </goals>
  13.                 <configuration>
  15.                     <!-- 指定打包的 ${pluginName}.ark.plugin 存放目录; 默认放在 ${project.build.directory} -->
  16.                     <outputDirectory>./</outputDirectory>
  18.                     <!-- 是否把 ark plugin 安装、发布到仓库，默认为true -->
  19.                     <attach>true</attach>
  21.                     <!-- ark plugin 最多仅能指定一个 com.alipay.sofa.ark.spi.service.PluginActivator 接口实现类 -->
  22.                     <activator>com.alipay.sofa.ark.service.impl.SampleActivator</activator>
  24.                     <!-- 配置优先级，数字越小，优先级越高，优先启动，优先导出类，默认1000 -->
  25.                     <priority>2000</priority>
  27.                     <!-- 配置插件的名字，务必配置对，运行时，是插件的唯一标识 ID。比如 sofa-rpc 插件，可以配置为 sofa-rpc; 默认为 ${artifactId} -->
  28.                     <pluginName>${ark.plugin.name}</pluginName>
  30.                     <!-- 配置导入类、资源 -->
  31.                     <imported>
  32.                         <!-- 配置需要优先从其他 ark plugin 加载的 package -->
  33.                         <packages>
  34.                             <package>javax.servlet</package>
  35.                             <package>org.springframework.*</package>
  36.                         </packages>
  38.                         <!-- 配置需要优先从其他 ark plugin 加载的 class -->
  39.                         <classes>
  40.                             <class>com.alipay.sofa.rpc.config.ProviderConfig</class>
  41.                         </classes>
  43.                         <!-- 配置需要优先从其他 ark plugin 加载的资源 -->
  44.                         <resources>
  45.                             <resource>META-INF/spring/bean.xml</resource>>
  46.                         </resources>
  47.                     </imported>
  49.                     <!-- 配置导出类、资源 -->
  50.                     <exported>
  51.                         <!-- 配置包级别导出的类 -->
  52.                         <packages>
  53.                             <package>com.alipay.sofa.ark.service</package>
  54.                         </packages>
  56.                         <!-- 配置类级别导出类 -->
  57.                         <classes>
  58.                             <class>com.alipay.sofa.ark.common.CommonUtils</class>
  59.                             <class>com.alipay.sofa.mock</class>
  60.                         </classes>
  62.                         <!-- 配置 ark plugin 对外导出的资源 -->
  63.                         <resources>
  64.                             <resource>META-INF/spring/bean.xml</resource>>
  65.                         </resources>                        
  66.                     </exported>
  68.                     <!-- 打包插件时，排除指定的包依赖；格式为: ${groupId:artifactId} 或者 ${groupId:artifactId:classifier} -->
  69.                     <excludes>
  70.                         <exclude>org.apache.commons:commons-lang3</exclude>
  71.                     </excludes>
  73.                     <!-- 打包插件时，排除和指定 groupId 相同的包依赖 -->
  74.                     <excludeGroupIds>
  75.                         <excludeGroupId>org.springframework</excludeGroupId>
  76.                     </excludeGroupIds>
  78.                     <!-- 打包插件时，排除和指定 artifactId 相同的包依赖 -->
  79.                     <excludeArtifactIds>
  80.                         <excludeArtifactId>sofa-ark-spi</excludeArtifactId>
  81.                     </excludeArtifactIds>
  83.                 </configuration>
  84.             </execution>
  86.         </executions>
  87.     </plugin>
  88. </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 相同的包依赖；

构建

对于普通的 Java 工程，为了生成标准的 Ark Plugin ，只需要三步操作：

  • 在工程根目录中新建一个空模块打包 Ark Plugin，定义插件坐标，假设为：
  1. <dependency>
  2.     <groupId>com.alipay.sofa</groupId>
  3.     <artifactId>sofa-ark-plugin-demo</artifactId>
  4.     <version>1.0.0</version>
  5. </dependency>

  • 在该模块的 pom.xml 文件中，添加工程其他模块和三方包依赖，并配置模板配置 sofa-ark-plugin-maven-plugin 插件；

  • 在该模块目录或工程根目录中敲击 mvn package 命令，即可在配置的 outputDirectory 目录中生成 ark-plugin-demo.ark.plugin 插件文件；敲击 mvn install 命令，则会安装到本地 Maven 仓库；

发布

在工程主 pom 中配置仓库地址，然后敲击 mvn deploy 命令，即可发布该 Ark Plugin ;需要指出的是，发布的 Ark Plugin 坐标会带上 classifier = ark-plugin ；如上述构建描述，会生成如下坐标的 Ark Plugin :

  1. <dependency>
  2.     <groupId>com.alipay.sofa</groupId>
  3.     <artifactId>sofa-ark-plugin-demo</artifactId>
  4.     <classifier>ark-plugin</classifier>
  5.     <version>1.0.0</version>
  6. </dependency>

其他应用通过该坐标即可引用该插件。

Ark Plugin 典型目录结构

  1. .
  2. │
  3. ├── com
  4. │   └── alipay
  5. │       └── sofa
  6. │           └── ark
  7. │               └── plugin
  8. │                   └── mark
  9. │
  10. ├── META-INF
  11. │   └── MANIFEST.MF
  12. │
  13. ├── conf
  14. │   └── export.index
  15. └── lib
  16.     ├── commons-lang3-3.3.1.jar
  17.     ├── sample-plugin-1.0.0.jar
  18.     └── sample-plugin-common-1.0.0.jar

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

  • com/alipay/sofa/ark/plugin/mark ：标记文件，标记该 Jar 包是 sofa-ark-plugin-maven-plugin 打包生成的 Ark Plugin 文件。

  • META-INF/MANIFEST.MF ：记录插件元信息，内容类似如下：

  1. Manifest-Version: 1.0
  2. groupId: com.alipay.sofa
  3. artifactId: sample-plugin
  4. version: 1.0.0
  5. priority: 2000
  6. pluginName: sample-demo-plugin
  7. activator: com.alipay.sofa.ark.service.impl.SampleActivator
  8. import-packages: javax.servlet,org.springframework
  9. import-classes: com.alipay.sofa.rpc.config.ProviderConfig
  10. export-packages: com.alipay.sofa.ark.service
  11. export-classes: com.alipay.sofa.ark.common.CommonUtils,com.alipay.sofa.mock

  • conf/export.index ：插件导出类索引文件；为了避免在运行时计算插件 export-packages 下面具体的导出类，在打包生成 Ark Plugin 时，会生成插件所有导出类的索引文件，缩短 Ark Container 解析配置时间。而导入类只需要读取 META-INF/MANIFEST.MF 配置信息，直接比较 import-packages 和 import-classes 前缀即可，无需生成索引文件。

  • lib/ : lib 目录存放插件工程依赖的普通 Jar 包，一般包含插件需要和其他插件或者业务有隔离需求的 Jar 包；插件配置的导出类都包含在这些 Jar 包中。

原文: https://alipay.github.io/sofastack.github.io/docs/ark-plugin.html