4.5.2. 创建应用程序组件

如果正在开发可复用的应用程序组件，本节包含一些有用的建议。

命名规则

  1. 使用标准的反转域名表示法选择根 java 包，例如 com.jupiter.amazingsearch。

    根包不应该以任何其它组件或应用程序的根包开头。例如，如果有一个带有 com.jupiter.tickets 根包的应用程序，则不能将 com.jupiter.tickets.amazingsearch 包用于组件。原因是 Spring 从指定的根包开始扫描 bean 的类路径，并且每个组件的扫描空间必须是唯一的。

  2. 命名空间用作数据库表的前缀，因此对于公共组件，应该是一个表示综合含义的单词(或缩写)，如 jptams，而不仅仅是 search。这样可以将目标应用程序中命名冲突的风险降到最低。不能在命名空间中使用下划线和短横，只能使用字母和数字。

  3. 模块前缀应该与命名空间名称一致，但可以包含短横，如 jpt-amsearch。

  4. 使用命名空间作为 bean 名称和应用程序属性的前缀，例如：

    1. @Component("jptams_Finder")
    2. @Property("jptams.ignoreCase")

安装到本地 Maven 仓库

要使组件可用于本地计算机上的项目，请通过执行 CUBA > Advanced > Install app component 主命令将其安装到本地 Maven 仓库中。这个命令实际上只是在停止 Gradle 守护进程之后运行 install Gradle 任务。

上传到远程 Maven 仓库

  1. 按照安装配置私仓中的说明设置私仓。

  2. 指定项目的仓库和凭证，由于使用私仓，此处不能设置标准 CUBA 仓库。

  3. 在文本编辑器中打开组件项目的 build.gradle，并将 uploadRepository 添加到 cuba 部分：

    1. cuba {
    2.     //...
    3.     // repository for uploading your artifacts
    4.     uploadRepository {
    5.         url = 'http://repo.company.com/nexus/content/repositories/snapshots'
    6.         user = 'admin'
    7.         password = 'admin123'
    8.     }
    9. }

  4. 在 Studio 中打开组件项目。

  5. 从命令行运行 uploadArchives Gradle 任务。组件的工件将被上传到仓库。

  6. 从本地 Maven 仓库中删除组件工件，以确保在下一次装载应用程序项目时会从远程仓库下载组件：只需删除位于用户主目录中的 .m2/repository/com/company 文件夹。

  7. 现在，当装载并运行使用此组件的应用程序时，将从远程仓库中下载依赖的扩展组件。

上传到 Bintray

  1. 首先，在 https://bintray.com/signup/oss 注册账号

    可以在 Bintray 上使用社交账户登录（GitHub，Gmail，Twitter），但稍后必须重置密码，因为获取 API 密钥需要此帐户的密码（见下文）。

  2. 获取 Bintray 用户名。可以在登录 Bintray 后看到的 URL 中找到。例如，在 https://bintray.com/vividphoenix 中，vividphoenix 是用户名。

  3. 获取 API 密钥。可以在 Bintray 编辑个人资料界面中找到。在 API 密钥部分，系统会要求输入帐户密码以获取密钥。然后，将能够使用此密钥和用户名进行 Bintray 的 Gradle 插件验证：

    • Bintray 凭证可以添加为环境变量：

      1. BINTRAY_USER=your_bintray_user
      2. BINTRAY_API_KEY=9696c1cb90752357ded8fdf20eb3fa921bf9dbbb

    • 除了环境变量，也可以在项目的 build.gradle 文件中显式定义这些参数：

      1. bintray {
      2.     user = 'bintray_user'
      3.     key = 'bintray_api_key'
      4.     ...
      5. }

    • 或者，可以在命令行中提供 Bintray 凭据的参数：

      1. ./gradlew clean assemble bintrayUpload -Pcuba.artifact.version=1.0.0 -PbintrayUser=your_bintray_user -PbintrayApiKey=9696c1cb90752357ded8fdf20eb3fa921bf9dbbb

  1. 创建 Maven 类型的公共仓库。对于开源（OSS）仓库，必须设置许可证类型。

    Bintray 会隐式的使用仓库内的包。此时，还不是必须要创建组件包，因为在之后的 gradle bintrayUpload 任务会自动创建。

  2. 在 build.gradle 中，添加 Bintray 上传插件的依赖如下：

    1. buildscript {
    2.     // ...
    3.     dependencies {
    4.         classpath "com.haulmont.gradle:cuba-plugin:$cubaVersion"
    5.         // Bintray upload plugin
    6.         classpath "com.jfrog.bintray.gradle:gradle-bintray-plugin:1.8.0"
    7.     }
    8. }

  3. 在 build.gradle 结尾，添加 Bintray 插件设置：

    1. /** * If you have a multi-project build, make sure to apply the plugin and the plugin configuration to every project which artifacts you want to publish to Bintray. */
    2. subprojects {
    3.     apply plugin: 'com.jfrog.bintray'
    5.     bintray {
    6.         user = project.hasProperty('bintrayUser') ? project.property('bintrayUser') : System.getenv('BINTRAY_USER')
    7.         key = project.hasProperty('bintrayApiKey') ? project.property('bintrayApiKey') : System.getenv('BINTRAY_API_KEY')
    9.         configurations = ['archives']
    11.         // make files public ?
    12.         publish = true
    13.         // override existing artifacts?
    14.         override = false
    16.         // metadata
    17.         pkg {
    18.             repo = 'main'           // your repository name
    19.             name = 'amazingsearch'  // package name - it will be created upon upload
    20.             desc = 'AmasingSearch'  // optional package description
    22.             // organization name, if your repository is created inside an organization.
    23.             // remove this parameter if you don't have an organization
    24.             userOrg = 'jupiter-org'
    26.             websiteUrl = 'https://github.com/jupiter/amazing-search'
    27.             issueTrackerUrl = 'https://github.com/jupiter/amazing-search/issues'
    28.             vcsUrl = 'https://github.com/jupiter/amazing-search.git' // mandatory for Open Source projects
    30.             licenses = ["Apache-2.0"]
    31.             labels = ['cuba-platform', 'opensource']
    33.             //githubRepo = 'amazingsearch/cuba-platform' // optional Github repository
    34.             //githubReleaseNotesFile = 'README.md' // optional Github readme file
    35.         }
    36.     }
    37. }

    • pkg:repo 是仓库（使用 main），

    • pkg:name 是包名（使用唯一名称，例如 amazingsearch），

    • pkg:desc 将显示在 Bintray 界面上的可选组件包描述，

    • pkg:userOrg - 是仓库所属组织的名称（如果没有设置，默认情况下 BINTRAY_USER 将用作组织名称）。

  1. 现在，可以使用以下命令构建和上传项目：

    1. ./gradlew clean assemble bintrayUpload -Pcuba.artifact.version=1.0.0

  2. 如果在 CUBA 市场上发布扩展组件，则其仓库将链接到标准 CUBA 仓库，用户不必在其项目中指定仓库。