前后端视频教程（持续更新）

关联教程：

Chapter I: 升级说明

1. 新版功能

1.1. 基本功能

  1. 升级 Apache Felix 为主容器（ Vertx 为子容器 ），支持 OSGI 规范（原版依旧可运行）。

  2. 热插拔、低代码管理工具实现全流程生命周期管理。

  3. 开发环境使用 Maven 自动化脚本一键完成，部署管理内部实现一键式部署，可集成外层 CI/CD 标准化流程。

  4. 工具平台提供监控中心、管理中心、开发中心，配合 Zero UI 实现全平台/全应用监管控模式。

  5. 引入类似 MBSE 的理论和规范，实现系统自证，并保证系统本身在运行过程中的标准化定义。

  6. 硬件对接：模块实现可使用 C、Python、Rust 等其他语言开发，底层可对接硬件抽象层实现万物互联的集成方式。

1.2. 模块化思路

1.2.1. 模块类型

类型 说明

OSGI 模块

基于 OSGI 规范支持热插拔的模块。—— Open Service Gateway Initiative

JPMS 模块

基于 JDK 9+ 之后的模块（module-info.java）方式，可打包成 .mod。—— Java Platform Module System

1.2.2. 模块形态

形态 说明

静态 jar

静态依赖库，通常位于 Maven 项目的 <dependency> 标签中引入。

动态 bundle

OSGI模块，直接支持热插拔，在环境中实现模块的安装、启动、停止、卸载。

微服务

以脚本为中心（ FAAS ），每个模块都可独立部署成微服务，提供 mod.yaml / app.yaml 描述文件即可，直接对接云原生 K8S 环境。

Chapter II: 环境综述

2. 项目结构

2.1. 纯环境

纯环境中只包含 Felix OSGI 环境，不携带其他内容，且只有发布版，信息如下：

  1. 地址：https://gitee.com/zero-ws/Zero.Build.Rapid.Fabric.Runtime

  2. 引用配置（git submodule）：

    [submodule "Zero.Rapid.Fabric.Runtime"]
    path = refs/Zero.Rapid.Fabric.Runtime
    url = git@gitee.com:zero-ws/Zero.Build.Rapid.Fabric.Runtime.git
    branch = master

如果库名称发生变更，请在自己的 pom.xml 重新配置，其他需引用的模块仓库前缀以 Zero.Build 库名为主，每个库的 README.md 中都包含了上述引用配置。

2.2. 模块环境

Zero新版内部核心模块研发环境和用户最终研发环境维持一致。

2.2.1. 目录说明

运行时的结构目录直接参考纯环境下的发布目录即可（带启动脚本），标记为不提交的记得检查 .gitignore 文件中的设置。
路径 是否提交 备注

/document

否

maven-javadoc-plugin 生成的文档。

/env

否

自动化运行环境，保证每个模块可以独立运行调试。

/refs

是

git submodule 存储引用模块专用位置，配合 git 管理提交，子模块单独提交，主模块只提交 commits 记录。

/src

是

当前模块源代码目录，开发人员主体操作目录。

2.2.2. Profile说明

完整环境依赖 Maven Profile 来管理开发过程中的生命周期流程：

名称 说明

release

专用于生产环境发布的 Profile。

test

专用于测试环境发布的 Profile。

dev

一键生成可直接运行的 Zero 全容器运行环境。

debug

一键运行/调试。

2.2.3. 命令说明

# 初始化开发环境（环境可一键搭建）
mvn -Pdev clean package install

# 生产部署
mvn -Prelease clean package install

# 测试部署（保留）
mvn -Ptest clean package install
mvn -Ptest test

# 一键运行/调试
mvn -Pdebug test

3. 开发调试

执行过 mvn -Pdev clean package install 之后已搭建好开发调试环境。

3.1. JAR 方式

一个模块一个配置

使用 JAR Application 类型的应用启动环境：

0

3.1.1. IDEA 配置

配置项 说明

项目类型

JAR Application

Path to JAR

<Module>/env/bin/libs/felix.jar

Working directory

<Module>/env/bin/

3.2. MAVEN 方式

一个模块一个配置

使用 Maven 类型的应用启动环境：

0

3.2.1. IDEA 配置

配置项 说明

项目类型

Maven

Run

test

Working directory

<Module>

Profiles

debug

运行之后点击 Attach Debugger 则可进入调试模式，参考如下截图：

0

3.3. Remote JVM Debug 方式

多个模块可共享配置，且跨 IDE

先执行如下脚本启动应用：

# 调试专用命令
mvn -Pdebug test

使用 Remote JVM Debug 类型的应用启动调试：

0

3.3.1. IDEA 配置

配置项 说明

项目类型

Remote JVM Debug

Host

127.0.0.1

Port

5005

Use module classpath

<Module>

此处配置和 pom.xml 中的配置相关联，主要注意 Host 和 端口，参考如下片段（debug 的 Profile，插件 exec-maven-plugin 中）：

<configuration>
    <workingDirectory>${project.basedir}/env/bin</workingDirectory>
    <executable>java</executable>
    <arguments>
        <argument>-jar</argument>
        <argument>-Xdebug</argument>
        <argument>
            -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005
        </argument>
        <argument>libs/felix.jar</argument>
    </arguments>
</configuration>

4. 命令说明

4.1. 基础执行

直接从 Gogo Command 后台执行，示例如：

g! service bundle all
[ ZERO ] Command : all
No service registered in current bundle. name = io.zerows.zero-core-ams-specification
----------------------------------------
No service registered in current bundle. name = io.zerows.zero-core-entry-osgi
----------------------------------------
Bundle: ( id = 16, name = io.zerows.zero-core-runtime-configuration )
Service Registered List:
   [io.zerows.core.configuration.osgi.service.EnergyOption]
      com.aisz.platform-entry-osgi
   [io.zerows.core.configuration.osgi.RuntimeConfigurationCommand]
----------------------------------------
Bundle: ( id = 17, name = io.zerows.zero-core-runtime-metadata )
Service Registered List:
   [io.zerows.core.metadata.osgi.service.EnergyFailure]
      io.zerows.zero-core-runtime-metadata
      io.zerows.zero-core-runtime-configuration
      com.aisz.platform-entry-osgi
   [io.zerows.core.metadata.osgi.RuntimeMetadataCommand]
      org.apache.felix.gogo.runtime
----------------------------------------

4.2. 命令清单

命令 参数 说明

exit

（无）

追加的退出命令，可退出整个应用。

cache

（无）

查看当前环境中的所有组件缓存。

failure error

all

查看当前环境中所有自定义异常。

size

查看当前环境中异常数量。

{BUNDLE_ID}

查看某个 Bundle 中的异常定义。

failure info

all

查看当前环境中所有自定义异常（前端可阅读版本）。

node network

all

查看 Cluster 集群详细信息。

node vertx

all

查看 Vertx 运行实例的详细信息。

service bundle

all

查看当前环境中所有注册的 OSGI 服务信息，以及服务调用者信息。

{BUNDLE_ID}

查看某个 Bundle 相关的服务注册信息，以及服务调用者信息。

5. 运行环境

兼容运行旧版程序过程中，为了保证生产环境和开发环境拥有同样的目录结构，方便多个 App 实例的运行，所以针对此环境进行重新规划，以达到单镜像、单程序的多目录（每个目录一个实例）的运行模式，此模式之下配合第二管理端完整程序，您可以完成多应用的部署模式。

5.1. 目录结构

5.1.1. 作用

第二管理端和应用程序端的部署结构维持一致，新的目录结构作用：

  • 开发环境和生产环境目录维持一致，生产环境运行时可实现绿色启动/一键部署。

  • 容器化部署时可直接将 Docker 的存储挂载外置目录，并将目录中相关信息全部拷贝到目标目录中。

  • 每个应用都可以开启多个 App 实例，可多实例运行。

5.1.2. 运行目录

路径 说明

/running/

运行主目录

/running/bin/

程序主目录

/running/bin/app.jar

入口程序

/running/bin/start.sh

（脚本）启动脚本

/running/bin/stop.sh

（脚本）停止脚本

/running/bin/lib/

依赖库存放目录

/running/instance/

实例配置目录

/running/instance/{name}

单个实例配置目录，开发过程中实例运行主目录、工作目录

/running/instance/{name}/.env.development

开发专用实例环境变量

/running/instance/{name}/.env.lock

实例配置锁，运行过程中检查锁文件，若锁文件存在则跳过 run-configure.sh 配置脚本

/running/instance/{name}/keys

安全运行证书配置

/running/instance/{name}/conf

实例运行配置程序，开发中 src/main/resources 目录中的内容。

/running/instance/{name}/database

实例运行数据库目录

/running/instance/{name}/logs

实例运行日志目录

/running/util/inst/

指令程序运行目录

/running/util/inst/inst-load.jar

（指令）数据导入程序

/running/util/inst/inst-menu.jar

（指令）菜单规划程序

/running/util/inst/inst-atom.jar

（指令）动态建模程序

5.2. 初始化

5.2.1. 应用端

  1. 在 demo 目录中配置相关环境变量，参考如：

    #!/usr/bin/env bash
# -------- playbook.database.yml
export DB_TYPE=MYSQL                      # 数据库类型
# 数据库名关键字，最终生成
# DB_HOTEL_001
# DB_HOTEL_001_WF
export DB_INSTANCE=HOTEL_001

# database 应用账号密码
export DB_APP_USER=??
export DB_APP_PASS=??
# database 脚本执行所需（zero账号密码）
export DB_PASSWORD=??

# -------- playbook.conf.vertx.yml
export PORT_WEB=7105                      # 前端接口
export PORT_API=7185                      # 后端接口

# -------- 应用专用环境变量
# export DB_ENV=DEV
export Z_APP=app.micro.hotel              # 应用名
export Z_HED_ENABLED=true                 # 是否开启 HED
export Z_SIS_STORE=/Users/lang/zero-store # 集成服务上传下载存储配置
# environment.json 所需
export APP_SIGMA=??
export APP_ID=??
export APP_TENANT=??
export APP_HOTEL=??

# export Z_HED=io.zerows.plugins.store.liquibase.hed.HEDCore

  2. 执行初始化编译

    mvn -Pinit clean package install

  3. 分布执行实例初始化脚本

    # 语法
# init.sh {instance} {dbtype}
# 第一步
./init.sh hotel-001 MYSQL
# 第二步
./configure.sh hotel-002 MYSQL
# 注意此处实例名和 demo 中的文件名对应

Chapter III: 升级流程

6. 升级流程

由于新版结构发生了很大的变化，所以记录每个模块的详细升级流程，升级过程中检查每个点是否已经就绪。

6.1. Maven 环境

新版 Maven 环境有三处需修改：

6.1.1. 项目类型

Maven 中配置项目类型为 bundle

<project>
    <packaging>bundle</packaging>
</project>

6.1.2. 插件配置

在插件 maven-bundle-plugin 中追加 <Bundle-SymbolicName>，后续配置目录和它保持一致：

<plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <extensions>true</extensions>
    <configuration>
        <instructions>
            <!-- 注意这里的配置目录 -->
            <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>

6.1.3. Liquibase 配置

新版 liquibase-maven-plugin 插件配置有所变化

<plugin>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-maven-plugin</artifactId>
    <configuration>
        <propertyProviderClass>io.zerows.extension.runtime.skeleton.secure.ZeroLiquibaseEncryption
        </propertyProviderClass>
        <!-- 配置文件路径（此处有所变化） -->
        <propertyFile>plugins/${project.artifactId}/database/MYSQL.properties</propertyFile>
        <changeLogFile>plugins/${project.artifactId}/database/MYSQL.yml</changeLogFile>
        <!-- 配置参数 -->
        <promptOnNonLocalDatabase>false</promptOnNonLocalDatabase>
        <outputFileEncoding>UTF-8</outputFileEncoding>
    </configuration>
</plugin>

注意配置的属性文件路径对应到第二步中的 <Bundle-SymbolicName> 中：

  • Norm 环境为一个固定常量写死，注意不和其他文件重复。

  • Osgi 环境会直接通过 Bundle.getSynbolicName() 读取到。

除了 Maven 插件要变化之外，liquibase 还有一个需要变更的地方，文件 database/MYSQL.yml 中将绝对路径改成相对路径

databaseChangeLog:
  # 应用信息
  - include:
      file: MYSQL/X_APP.sql                             # 此处使用相对路径
      relativeToChangelogFile: true                     # 此处设置为 true
  # 数据源处理
  - include:
      file: MYSQL/X_SOURCE.sql
      relativeToChangelogFile: true

上述示例中有两处改动

  • file 由原来的绝对路径修正成相对路径。

  • relativeToChangelogFile 的值设置为 true。

6.1.3.1. 变更

迁移表

原始路径 新路径

plugin/xxx/db.yml

database/<TYPE>.yml

plugin/xxx/db.properties

database/<TYPE>.properties

plugin/xxx/sql/*.sql

database/<TYPE>/*.sql

6.2. 配置目录

前文中已配置过 <Bundle-SymbolicName>，接下来根据此名称创建基础配置信息。

6.2.1. 入口目录

创建 plugins/<Bundle-SymbolicName>/ 的配置目录，注意此处 plugins 是复数格式。

6.2.2. 入口配置

创建 plugins/<Bundle-SymbolicName>.yml 的配置文件，文件内容如下：

shape:
  # 此处 id 即为前文中的 <Bundle-SymbolicName> 部分
  id: zero-extension-commerce-document
  # 此处名称通常是 pom.xml 中配置的 <Name>
  name: "Zero.Extension.Commerce.Documentation"

6.2.3. 目录规范

此处目录规范以 plugins/<Bundle-SymbolicName> 之下的规范为主。

路径 类型 含义

configuration.json

文件

原扩展模块入口配置

data/

目录

（Excel导入）数据导入专用目录

data/<TABLE>/

目录

（Excel导入）数据导入目录中带表名的数据导入目录

database/

目录

Liquibase 数据库初始化专用目录

database/<TYPE>.yml

文件

Liquibase 表生成专用目录，此处 TYPE 为数据库类型，默认 MYSQL

database/<TYPE>.properties

文件

Liquibase 使用的 JDBC 配置文件

`database/<TYPE>/

目录

Liquibase 中的表结构初始化 SQL 文件位置

logging/

目录

Logback 专用模块配置目录

logging/logback-segment.xml

文件

Logback 模块配置文件，此配置文件为静态的，一般是配置在入口 logback.xml 中链接

model/

目录

建模专用目录，内置之前和表结构对应的生成了代码的实体和模型。

model/connect.yml

文件

（Excel导入）新版导入专用配置文件

model/<identifier>/

目录

单个模块基础配置

model/<identifier>/entity.json

文件

对应原 zero-crud 引擎的 KModule 核心配置文件

model/<identifier>/column.json

文件

对应原 zero-ui 界面列表列的核心配置文件

modulat/

目录

对应原 zero-battery 模块化专用配置目录

security/

目录

对应原 zero-rbac 安全模块专用配置目录

security/RBAC_ADMIN/

目录

权限管理专用配置目录，对应原 ACL 管理部分配置目录

security/RBAC_RESOURCE/

目录

当前模块安全资源定义配置目录，S_RESOURCE / S_ACTION 部分

security/RBAC_ROLE/

目录

角色和账号的权限配置目录

security/RBAC_ROLE/ADMIN.SUPER

目录

原系统管理员角色权限配置目录

web/

目录

X_MODULE 配置中所需的 metadata 配置文件专用目录

web/<path>

目录

此处 Path 只包含前端的后半部分，不配置前置部分，方便模块复用

workflow/

目录

对应原 zero-wf 工作流配置目录

6.3. Excel 导入配置

6.3.1. 表配置

原版的 Excel 中使用了 Java 反射中的类名来对接表中实体 Dao 相关信息，新版直接使用表名做对接，新配置如下：

# 旧配置
- dao: io.zerows.extension.commerce.documentation.domain.tables.daos.DDocDao                # D_DOC 文档主表，文档批量导入用
  key: key
  unique:
    - name
    - sigma
    - version

# 新配置
- dao: D_DOC                # D_DOC
  unique:
    - name
    - sigma
    - version

  • 属性名不变，直接将 dao 值设置成表名，系统会自动解析。

  • 可直接忽略 key: key 这种主键设置。

6.3.1.1. 变更

迁移表

原始路径 新路径

plugin/xxx/oob/initialize.yml

model/connect.yml

6.3.2. Excel数据目录

通常情况下，数据库中一张表的数据都是放在一个 Excel 文件中，但像安全管理、模块化、流程引擎也会有意外，所以基于这点考虑，才会在模块中开出四个核心数据目录：

目录名 含义

data/

基础数据导入专用目录，内部以表结构为中心。

modulat/

模块化配置专用目录，对应原 zero-battery 配置。

security/

安全管理配置专用目录，对应原 zero-rbac 配置。

workflow/

流程管理配置专用目录，对应原 zero-wf 配置。

6.3.3. Excel路径规范

参考如下截图

0

基本规则：

  1. 文件名具有一定辨识度，如 zero.directory.xlsx 的文件名是 X_CATEGORY 表中的 TYPE 列的值，此文件中所有数据的 TYPE 都是该值。

  2. 文件名相同目录的含义：

    X_CATEGORY/zero.directory/document/treeComponent.json

    • X_CATEGORY 是数据库中表名。

    • zero.directory 是对应的文件名，如 zero.directory.xlsx。

    • document 是 CODE = 'document` 的数据单条记录信息（新版还支持另外两种格式）。

    • treeComponent.json 则是单条记录信息中的 treeComponent 字段的配置。

  3. 和文件名相同的目录主要用于配置外联反射和外联JSON配置。

6.3.4. 单元格配置

原反射字段，直接通过上述规范转换成外联配置（方便类名变更做重构），如上述 treeComponent.json

[
    "io.zerows.extension.runtime.ambient.osgi.spi.feature.CatalogArbor"
]

为了统一读取 JSON 配置文件，所以此处文件格式为单个元素的数组。

原配置字段则格式不发生任何变化，直接放到对应的字段上即可。

有了上述基础外联之后，新版多了两个固定单元格的值：

osgi excel cell

单元格配置 含义

PWD

加载当前目录中的基础数据。

NAME:config

加载配置字段到环境中，只是此处使用 name = 'xxx' 的方式作为唯一记录查询条件。

NAME_ABBR:config

模块化专用配置，缩略名作为当前行标识。

CODE:class

加载反射字段到环境中，数组中的唯一元素，对齐到原版配置。

CODE:config

加载配置字段到环境中，近似原版的 JSON:xxx，只是原版从 classpath 路径开始加载，而新版这种写法基于上述目录规范开始加载。

CODE:NAME:config

（新）加载配置字段到环境中，目录使用 <filename>/<code>/<name> 的格式作为唯一记录查询条件。

6.4. CRUD 专用配置

6.4.1. Module/UI 专用配置

KModule 配置在新版中也将反射配置修正成了类名，配置内容对比如下

旧版
{
    "name": "comment",
    "daoCls": "io.zerows.extension.commerce.documentation.domain.tables.daos.DCommentDao",
    "field": {
        "unique": [
            [
                "code",
                "sigma"
            ]
        ]
    }
}
新版
{
    "name": "comment",
    "daoCls": "D_COMMENT",
    "field": {
        "unique": [
            [
                "code",
                "sigma"
            ]
        ]
    }
}

如果存在 <identifier> 对应的目录，则必须在 model/connect.yml 中执行对应配置，以保证实体类可以被扫描。
6.4.1.1. 变更

迁移表

原始路径 新路径

plugin/xxx/oob/module/crud/<identifier>.json

model/<identifier>/entity.json

plugin/xxx/oob/module/ui/<identifier>.json

model/<identifier>/column.json