1. 服务端开发
  2. 软件包

软件包发布后还可以选择在华炎魔方应用市场售卖,无论是华炎云上还是私有部署的魔方项目,要安装您发布到应用市场中的软件包都必须按您规定的价格来购买才能安装和使用。

关于软件包

华炎魔方基于 nodejs 标准的 npm 规范定义软件包,元数据可以在可视化界面中进行修改,然后使用Steeods VS Code插件同步到软件包,实现版本管理,并进一步编写代码、调试、测试、打包、部署。

软件包&元数据 示意图

软件包目录结构

每个软件包至少包含以下内容:

  • package.json:基于 npmjs 标准规范,定义软件包的信息, 用于描述软件包名称、版本、依赖的软件包信息。具体参考 https://docs.npmjs.com/cli/v7/configuring-npm/package-json
  • package.service.js:软件包微服务,是一个遵循 Moleculer 规范的微服务定义文件,可以编写代码,控制软件包加载时、启动、停止时执行的操作。具体参考: https://moleculer.services/docs/0.14/services.html
  • main/default文件夹:包含软件包中具体的内容,包括元数据、触发器、服务端路由、自定义脚本等等。

多软件包模式

华炎魔方项目根目录有一个文件夹steedos-app,这个文件夹中定义了一个名为steedos-app-default的默认软件包。

一个华炎魔方项目是可以定义多个软件包的,在文件夹steedos-packages中的每个子文件夹就是一个软件包,多软件包模式的魔方项目软件包文件目录结构为:

my-app
├── steedos-app
├── steedos-packages
    ├── package1
    ├── package2
    └── package3

我们推荐使用多软件包的方式开发华炎魔方项目。

创建软件包

可以把项目根目录的 steedos-app 文件夹复制下来并粘贴到 steedos-packages 文件夹中,并执行以下操作来创建一个新的软件包。

  • 修改软件包文件夹名称
  • 修改软件包名称,即软件包文件夹中 package.json 文件中的“name”属性。

切换默认软件包

如需要切换当前开发的软件包,需要先在 .env.local.env文件中配置以下环境变量来变更默认软件包的位置,或者您也可以使用VSCODE编辑器的“查看→命令面板”中的set Default Package Path命令来自动创建相关环境变量:

[package] 
DEFAULT_PACKAGE_PATH=steedos-packages/project #配置为相关软件包目录

软件包配置文件

项目根目录有个 .steedos 文件夹,该文件夹是一个独立的 NPM 项目,在该项目中可以定义要在华炎魔方项目中引用哪些软件包。

  • .steedos/package.json:这是 NPM 项目的配置文件,可以在dependencies中定义要安装哪些软件包到本地。

  • .steedos/steedos-packages.yml:在该文件中可以配置当前华炎魔方项目要引用哪些软件包,包括之前在package.json文件依赖项中定义的软件包也需要在这里引用才能生效。

    每个软件包可以定义的属性说明如下:

    '@steedos-labs/oa': # 软件包名称
      enable: true #是否启用该软件包
      version: 2.1.20 # 软件包版本号
      description: '' # 软件包备注
      local: false # 是否是本地项目下的软件包,只要不是安装到`.steedos/node_modules`文件夹下的软件包都应该设置为true
      path: .steedos/node_modules/@steedos-labs/oa #软件包所在文件目录,所有软件包都必须在这里填写软件包所在硬盘目录
    

重新加载软件包

通常来说我们会在以下情况下需要重新加载软件包:

  • 在开发过程中为软件包编写了代码需要测试相关开发成果。
  • 通过Git源码管理工具更新了其他团队成员提交到Git仓库中的代码后,在不重启项目的情况下让更新到的代码生效。
  • 软件包安装或升级后加载异常。

请在“设置”应用中进入“应用程序→软件包”界面,在软件包列表找到要重新加载的软件包,然后点击其右侧下拉菜单并在展开的菜单中点击“重新加载”菜单来重新加载软件包。

软件包开发

下面我们简单描述下软件包的开发过程,以下描述均假设我们已经按教程 开通华炎魔方云服务 注册好了云服务账户,然后按教程 开发环境部署 - Windows开发环境部署 - Mac 安装好了华炎魔方开发环境。

创建魔方项目

让我们先使用命令行npx create-steedos-app test-package创建一个空的魔方项目并使用VSCODE编辑器打开该项目。

创建软件包

这里假设我们需要开发一个名为project的项目管理的软件包,可以把项目根目录的 steedos-app 文件夹复制下来并粘贴到 steedos-packages 文件夹中,并执行以下操作来创建一个新的软件包。

  • 修改软件包文件夹名称为project
  • 修改软件包名称,即软件包文件夹中 package.json 文件中的“name”属性值为project

因为华炎魔方是基于 nodejs 标准的 npm 规范来定义软件包的,所以我们也可以在软件包文件夹steedos-packages中新建一个子文件夹project,然后cd到该文件夹,并执行命令npm init来初始化项目的方式来创建一个软件包,不过我们依然需要从默认软件包文件夹steedos-app中把名为package.service.js的微服务配置文件复制该文件夹中。

运行项目

在运行项目前,我们需要在项目根目录执行yarn安装项目依赖包,并把云服务上注册好的魔方ID和私有部署ApiKey配置到.env.local.env文件中:

STEEDOS_CLOUD_SPACE_ID=#在此填入华炎云上新建的私有部署记录中的魔方ID
STEEDOS_CLOUD_API_KEY=#在此填入华炎云上新建的私有部署记录中的API Key

然后我们命令行执行yarn start,在跑起服务后就可以在浏览器上访问该魔方项目了。

需求开发

为方便演示,我们在“对象设置→对象”界面上简单新建一个名为“项目”的对象,为其配置好相关字段后,在“应用程序→选项卡”界面新建一个选项卡指向该对象,最后在“应用程序→应用程序”界面新建一个应用配置上该选项卡用于展示该对象数据。

同步为代码

软件包需求开完完成后,只能同步为代码才能发布,要同步为代码,我们需要打开VSCODE编辑器中的Steedos插件面板,并点击右上角的刷新按钮来浏览界面上的元数据。

如果未配置元数据同步相关的环境变量的话,点击右上角的刷新按钮会报错Please run command, steedos source:config,我们只要在.env.local.env文件中把以下相关环境变量配置上,或者在项目命令行上运行指令steedos source:config在向导中配置相关环境变量即可。

[metadata]
METADATA_SERVER=http://localhost:5000 #配置为访问华炎魔方的URL
METADATA_APIKEY=#在此填入华炎云上新建的私有部署记录中的API Key

接下来我们在Steedos插件面板上找到刚在界面上新建的应用、对象和选项卡元数据,点击其右侧的下载按钮即可把代码同步到项目本地文件夹。

需要注意的是我们这里需要把界面上配置的元数据同步到steedos-packages/project这个软件包目录中,而上面的操作会把代码同步到默认软件包steedos-app目录中并不是我们要的效果。

所以我们需要先配置下以下环境变量来变更默认软件包的位置,或者您也可以使用VSCODE编辑器的“查看→命令面板”中的setDefaultPackagePath命令来自动创建相关环境变量:

[package]
DEFAULT_PACKAGE_PATH=steedos-packages/project #配置为相关软件包目录

在配置该环境变量后,再点击Steedos插件面板上相关元数据右侧的下载按钮即可把代码同步到project这个软件包的目录下,而不是同步到默认软件包目录下。

以下就是我们同步成功后的软件包文件目录,接下来我们需要发布的软件包内容也正是这个目录中的文件。

在软件包发布前,您可以随意在软件包steedos-packages/project文件夹中进行华炎魔方低代码开发,软件包发布后的内容会包括该文件夹内的所有文件,而不是只包括我们刚刚同步下来的从界面上配置的元数据文件,华炎魔方低代码开发请参考 开发人员快速向导

软件包发布

公开软件包是发布到 NPM官网,即 https://www.npmjs.com/ 仓库。下面我们来简单介绍下如何发布一个软件包。

注册账号

登录 NPM官网 注册账号。 注册完后请点击右上角头像图标,并选择菜单“Profile → Organization”来创建一个组织。

组织名称将会在软件包名称中使用!

软件包名称

要发布的公开软件包必须用组织名称作为前缀来命名。

例如:现有一个名为 test-oa-ldx 的软件包和一个名为 liaodx 的组织。 那么软件包内的package.json文件中把软件包名称从test-oa-ldx改为@liaodx/test-oa-ldx

修改软件包名称的同时请检查是否有以下属性内容,若无请添加。

"publishConfig": {
    "access": "public"
}

登录NPM

先执行命令 cd 到软件包根目录,然后执行 npm login 命令:

$ npm login
> Username: #npm账号 
> Password: #npm密码
> Email: # PUBLIC-EMAIL-ADDRESS,输入有效邮件地址即可

发布

执行 npm publish 进行发布软件包。

如果软件包已经发布过需要重新发布,需要修改软件包文件夹中 package.json 文件中的“version”为下一个版本来发布新版本的软件包。

发布成功后您可以回到 NPM官网,在搜索栏中搜索软件包名称来查看刚发布的软件包。

软件包安装

软件包发布成功后,我们只要在华炎魔方项目中安装上就可以使用了。

安装前准备

如果要安装的是发布到 NPM官网,即 https://www.npmjs.com/ 仓库中的软件包,请跳过本小节描述的安装前准备,直接参阅后面的安装小节来安装软件包即可。

在运行项目前,我们需要在项目根目录执行yarn安装项目依赖包,并把云服务上注册好的魔方ID和私有部署ApiKey配置到.env.local.env文件中:

STEEDOS_CLOUD_SPACE_ID=#在此填入华炎云上新建的私有部署记录中的魔方ID
STEEDOS_CLOUD_API_KEY=#在此填入华炎云上新建的私有部署记录中的API Key

以上两个环境变量是所有魔方项目都必须配置的,根据之前软件包发布中“NPM作用域”小节中提到的授权规则,这里配置的STEEDOS_CLOUD_API_KEY所属的华炎云账户必须符合要安装的软件包所属的NPM作用域的授权规则,即每个魔方项目只能安装符合其NPM作用域授权规则的软件包。

在执行yarn start运行魔方项目过程中,华炎魔方会根据上面配置的环境变量STEEDOS_CLOUD_API_KEY值,登录到华炎魔方NPM仓库,即 https://registry.steedos.cn/ ,并自动下载授权给它的NPM域配置到本地,当项目运行起来后,我们可以在项目根目录的.steedos文件夹下看到名为.npmrc.yarnrc的文件:

  • .npmrc文件:存储了STEEDOS_CLOUD_API_KEY关联账户的steedos registry token
  • .yarnrc文件:存储了STEEDOS_CLOUD_API_KEY关联账户的steedos registry中可用的NPM作用域列表。

其中.yarnrc中列出的是当前魔方项目可以安装的发布到华炎魔方NPM仓库,即 https://registry.steedos.cn/ 中的软件包所属的NPM作用域清单,当该清单为空时,只表示无法安装华炎魔方NPM仓库中包括公开和私有类型的NPM作用域下的任何软件包,但是可以安装NPM仓库,即 https://www.npmjs.com/ 中公开的软件包,比如@steedos-labs/stimulsoft-reports@steedos-labs/project等。

基于上面描述的NPM作用域授权规则,要在魔方项目中安装我们之前发布的入@ylh/project 这个软件包,我们只有两种方案:

  • 在魔方项目中把环境变量STEEDOS_CLOUD_SPACE_IDSTEEDOS_CLOUD_API_KEY设置为要安装的软件包在发布时使用的环境变量值一样,这样就会使用已授权的NPM账户自动登录到华炎魔方NPM仓库中。
  • 上面两个环境变量与软件包在发布时不一样,但是使用与软件包在发布时一样的npm login参数执行一次npm login命令登录到华炎魔方NPM仓库。

第一种方式可以安装已授权的NPM账户下的公开和私有域下任何软件包,但是第二种方式只能安装公开类型的NPM作用域下发布的软件包。

安装

请在“设置”应用中进入“应用程序→软件包”界面并点击右上角的“手动安装软件包”按钮来安装软件包:

  • 软件包名称:可以输入发布到华炎魔方NPM仓库,即 https://registry.steedos.cn/ 中的软件包名称,比如输入@ylh/project表示要安装我们上面刚发布的软件包,也可以输入发布到NPM仓库,即 https://www.npmjs.com/ 中的公开软件包,比如@steedos-labs/stimulsoft-reports@steedos-labs/project等。
  • 版本号:可以输入希望具体安装哪个版本的软件包,不填写该项时表示安装最新版本。

点击提交即可把软件包安装到当前魔方项目中。

软件包安装成功后可以在软件包列表看到刚安装的软件包,如果该软件包状态显示为“已启用”则表示安装成功。

在软件包列表界面点击进入@ylh/project这个软件包详细页面,可以看到该软件包中包含哪些元数据,比如可以看到我们之前在软件包开发小节中创建的对象、选项卡和应用。

另外还可以在项目根目录下的 .steedos/steedos-packages.yml文件中查看已安装的软件包。

升级

在安装软件包时可以选择要安装的软件包版本号,软件包安装成功后,还可以按以下操作步骤来手动升级软件包的版本,而不用重新安装软件包。

  • 请在“设置”应用中进入“应用程序→软件包”界面。
  • 找到要升级的软件包并点击软件包名称进入详情界面。
  • 在界面右上角点击升级按钮。
  • 在弹出的升级窗口中选择要安装软件包版本,可以选择高版本来升级软件包,也可以选择低版本软件包以安装早期版本的软件包。
  • 点击确认按钮等待升级完成。