全部产品
云市场

Ark Plugin

更新时间:2020-02-04 15:50:10

本文将介绍 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 PluginMaven 插件坐标为:

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

  1. 在工程根目录中新建一个空模块打包 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>
  2. 在该模块的 pom.xml 文件中,添加工程其他模块和三方包依赖,并配置模板配置 sofa-ark-plugin-maven-plugin 插件。
  3. 在该模块目录或工程根目录中敲击 mvn package 命令,即可在配置的 outputDirectory 目录中生成 ark-plugin-demo.ark.plugin 插件文件;敲击 mvn install 命令,则会安装到本地 Maven 仓库。

发布

在工程主 pom 中配置仓库地址,然后敲击 mvn deploy 命令,即可发布该 Ark Plugin ;需要指出的是,如果没有设置 classifier,则生成的 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>

如果设置了 classifier=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 典型目录结构

如何打包 Ark Plugin 为例,该示例工程打包生成的 ark plugin 目录结构如下:

  1. .
  2. ├── META-INF
  3. ├── MANIFEST.MF
  4. └── maven
  5. └── com.alipay.sofa
  6. └── sample-ark-plugin
  7. ├── pom.properties
  8. └── pom.xml
  9. ├── com
  10. └── alipay
  11. └── sofa
  12. └── ark
  13. ├── plugin
  14. └── mark
  15. └── sample
  16. ├── activator
  17. ├── facade
  18. └── impl
  19. └── lib
  20. ├── sample-ark-plugin-0.6.0.jar
  21. ├── sample-ark-plugin-common-0.6.0.jar
  22. ├── sofa-ark-exception-0.6.0.jar
  23. └── 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:记录插件元信息,内容类似如下。
    1. Manifest-Version: 1.0
    2. groupId: com.alipay.sofa
    3. artifactId: sample-ark-plugin
    4. version: 0.6.0
    5. priority: 100
    6. pluginName: sample-ark-plugin
    7. description:
    8. activator: com.alipay.sofa.ark.sample.activator.SamplePluginActivator
    9. import-packages:
    10. import-classes:
    11. import-resources:
    12. export-packages: com.alipay.sofa.ark.sample.common
    13. export-classes: com.alipay.sofa.ark.sample.facade.SamplePluginService
    14. export-resources: Sample_Resource_Exported
  • lib/:lib 目录存放插件工程依赖的普通 Jar 包,一般包含插件需要和其他插件或者业务有隔离需求的 Jar 包;插件配置的导出类都包含在这些 Jar 包中。
  • com/alipay/sofa/ark/sample/*:ark plugin 模块中包含的类文件