先跑起来

提示

Nop 平台还处于开发阶段，本文档中的实践方案可能会部分失效，但本人精力有限，无法及时跟进，请自行按照最新代码调整；
您可以与智谱清言 AI 进行问答互动以了解 Nop 平台相关内容；
若此文对您有很大帮助，请投币支持一下吧；

文章作者: flytreeleft - flytreeleft@crazydan.org
文章链接: https://nop.crazydan.io/practice/demo/start
版权声明: 本文章采用许可协议《署名 4.0 国际 (CC BY 4.0)》，转载或商用请注明文章来源及作者信息。

准备工作

按照本地构建的说明在本地构建并部署 Nop 平台组件包。

也可以直接使用第三方 Maven 仓库: https://nop.repo.crazydan.io/ 。

创建本案例的工程目录 nop-demo，并将 nop-cli/target/nop-cli-2.0.0-BETA.1.jar 复制到工程目录（此时还是空目录）中：

export NOP_HOME=/path/to/nop/dir

cp "${NOP_HOME}/nop-cli/target/nop-cli-2.0.0-BETA.1.jar" ./nop-cli.jar

创建空白工程

工程配置

下载 nop-demo.orm.v0.xlsx 并将其放到工程目录下的 model/ 子目录中，并重命名为 nop-demo.orm.xlsx，然后，在该 Excel 中的【配置】表单中填写本案例的 Maven 工程模块名和包名等信息：

详细的工程配置说明请见《Excel 数据模型》。

工程初始化

# 注意，请根据当前运行环境修改 JDK 17+ 的安装路径
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk

${JAVA_HOME}/bin/java \
  -Dfile.encoding=UTF8 \
  -jar ./nop-cli.jar \
  gen -t=/nop/templates/orm \
  ./model/nop-demo.orm.xlsx

通过 ${JAVA_HOME}/bin/java -jar ./nop-cli.jar gen -h 可查看 gen 子命令的详细参数说明。其中，-t 选项所指向的是 Nop 工程中 nop-codegen/src/main/resources/_vfs/nop/templates/orm 目录下的模板，gen 命令所生成的工程目录结构与该模板是一致的。

工程构建

# 注意，请根据当前运行环境修改 JDK 17+ 的安装路径
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk

# Note：若为首次执行需去掉选项 -o，以下载必要的构建依赖包
mvn clean package -o -DskipTests -Dquarkus.package.type=uber-jar

后续更新 Excel 数据模型文件，需要重新构建 mvn package -o -DskipTests -Dquarkus.package.type=uber-jar。

自动生成的工程目录结构如下：

├─ nop-demo-api       对外暴露的接口定义和消息定义
├─ nop-demo-codegen   代码生成辅助工程，根据 ORM 模型更新当前工程代码
├─ nop-demo-dao       数据库实体定义和 ORM 模型
├─ nop-demo-service   GraphQL 服务实现
├─ nop-demo-web       AMIS 页面文件以及 View 模型定义
├─ nop-demo-app       测试使用的打包工程
├─ nop-demo-meta      业务模型定义，是前端与 ORM 模型之间的中间层模型
├─ deploy             根据 Excel 模型生成的数据库建表语句
├─ src
├─ _dump              所有编译期合成的模型，其中会打印每个节点和属性的来源源码位置

工程服务启动

# 注意，请根据当前运行环境修改 JDK 17+ 的安装路径
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk

${JAVA_HOME}/bin/java \
  -Dfile.encoding=UTF8 \
  -Dquarkus.profile=dev \
  -jar ./nop-demo-app/target/nop-demo-app-1.0.0-SNAPSHOT-runner.jar

注意，在通过 IDE 做开发调试时，需要以调试模式启动 io.nop.demo.app.NopDemoApplication#main，并且需在启动配置中添加 VM 参数 -Dfile.encoding=UTF8 -Dquarkus.profile=dev，同时设置环境变量为 MAVEN_CMD_LINE_ARGS=-o -s /path/to/maven/settings.xml 以设置 Maven 的命令行参数：

io.quarkus.runtime.Quarkus#run 会自动调用 Maven 下载 NopDemoApplication 的项目依赖，其使用的是 Maven 默认配置，与 IDE 的 Maven 配置无关（但 Quarkus 使用的 Maven 是与 IDE 相同的），所以，需通过环境变量 MAVEN_CMD_LINE_ARGS（注意，多个环境变量是以 ; 分隔的，所以，环境变量的值本身不能加引号，而值中含空格的路径则需加上引号）向 Quarkus 内置的 Maven 传递参数，然后，在参数中指定配置文件位置（-s）并启用离线模式（-o）；
若是要调试构建逻辑，则调试启动 io.nop.demo.codegen.NopDemoCodeGen#main 或 io.nop.demo.web.NopDemoWebCodeGen#main 即可；

定制化准备

在工程目录下创建 Maven 模块 nop-demo-delta：

nop-demo-delta/pom.xml
<?xml version="1.0" encoding="UTF-8" ?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
            http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <artifactId>nop-demo-delta</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <parent>
    <artifactId>nop-demo</artifactId>
    <groupId>io.nop.demo</groupId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <dependencies>
  </dependencies>
</project>

并准备不同版本的 Delta：

mkdir -p nop-demo-delta/src/main/resources/_vfs/_delta/{v1,v2}/nop/demo

# 必须创建空文件 _module，否则，其不会被识别为可扫描的 Delta 路径
touch nop-demo-delta/src/main/resources/_vfs/_delta/{v1,v2}/nop/demo/_module

然后，在 Maven 模块 nop-demo-app 中引入 Delta 模块：

nop-demo-app/pom.xml
    <dependency>
      <artifactId>nop-demo-delta</artifactId>
      <groupId>io.nop.demo</groupId>
      <version>1.0.0-SNAPSHOT</version>
    </dependency>

最后，设置 Delta 层的应用顺序（若是只有一个 default 层，则不需要显式设置）：

nop-demo-app/src/main/resources/application.yaml
nop:
  core:
    vfs:
      delta-layer-ids: v1,v2

注意事项

Excel 数据模型文件默认需放在 model 目录下，且其名称必须为 ${appName}.orm.xlsx，因为在 Nop 内置的模板 nop-entropy/nop-codegen/src/main/resources/_vfs/nop/templates/orm/{appName}-codegen/postcompile/gen-orm.xgen.xgen 中固定了 Excel 数据模型的读取位置为 model/${moduleName}.orm.xlsx（其不影响初始化，但在后续 Maven 打包构建时需要读取），而 moduleName 默认是与 appName 相同的（在 nop-entropy/nop-codegen/src/main/resources/_vfs/nop/codegen/xlib/gen.xlib 中的 <DefineLoopForOrm/> 节点下有详细的处理逻辑）；
appName 中的 - 将被替换为 / 后作为虚拟文件系统的顶级子目录，如，src/main/resources/_vfs/nop/demo 中的 nop/demo 便是按此规则确定的，但是 Nop 限制该目录层级只能为两级，以便于控制模块扫描的范围，故而，在 appName 中只能有一个 -；
在指定了应用的配置参数 nop.orm.init-database-schema 为 true 后， Nop 将通过 DatabaseSchemaInitializer 自动创建数据库表

准备工作​

创建空白工程​

工程配置​

工程初始化​

工程构建​

工程服务启动​

定制化准备​

注意事项​

参考资料​