本文将主要介绍如何使用HZERO Front客户端工具并创建基于HZERO Front的前端项目
请确保环境变量以及相关工具已安装好
环境变量
- node.js: v10.x or v8.x(>= v8.10)
关于node.js请参考: https://nodejs.org/en/
-
yarn: 推荐使用yarn管理本项目
执行如下命令全局安装yarn
$ npm install --global yarn
关于
yarn请参考 https://yarnpkg.com
-
lerna: 用于管理具有多个
package的JavaScript项目的工具。A tool for managing JavaScript projects with multiple packages. 执行如下命令全局安装
$ npm install --global lerna或者
$ yarn global add lerna
关于
lerna请参考https://lernajs.io/
-
hzero-front-cli: HZERO Front客户端工具,用于创建/更新基于HZERO Front的客户端工具
-
HZERO Front npm源地址: http://nexus.saas.hand-china.com/content/groups/hzero-npm-group/
各系统环境变量搭建可以参考: 前端开发指引/开发环境搭建
安装HZERO Front客户端工具: hzero-front-cli
执行如下命令
$ npm install -g hzero-front-cli --registry=http://nexus.saas.hand-china.com/content/groups/hzero-npm-group/
# hzero-front-cli -v
安装完成后执行如下命令即可查看HZERO Front客户端工具(hzero-front-cli)的相关命令
$ hzero-front-cli -h
创建项目
执行如下命令
# 命令格式如下
# hzero-front-cli <project name>
# 例如:
$ hzero-front-cli hzero-front-demo
# 注意：在git base here中使用这个命令可能存在问题。
由于HZERO Front默认使用了puppeteer Chrome DevTools工具,所以在安装过程中会自动下载Chromium相关,所以可以执行如下命令
使用hzero-front-cli的辅助命令
# hzero-front-cli <project name> --puppeteer-skip (推荐使用)
$ hzero-front-cli hzero-front-demo --puppeteer-skip
或者相关项目目录下执行如下命令
$ export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1 # macos/linux
# set PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1 # windows
接下来客户端工具将自动安装基于HZERO Front创建的项目的全部依赖/配置,在依赖安装完成后,自动执行webpack dll编译操作
新项目目录结构
.
├── README.md # 项目说明文档
├── config # 项目基本配置,包含webpakc相关/路由相关/测试相关/样式相关
│ ├── alias.js # webpack.config别名alias配置
│ ├── env.js # node.js环境变量配置
│ ├── jest # jest单元测试工具配置文件
│ │ ├── cssTransform.js
│ │ └── fileTransform.js
│ ├── paths.js # 静态文件路径配置文件
│ ├── routers.js # 项目菜单路由配置文件
│ ├── theme.js # 默认样式配置文件
│ ├── webpack.config.js # webpack默认配置文件
│ ├── webpack.dll.config.js # webpack dll插件配置文件
│ └── webpackDevServer.config.js # webpack dev server开发者模式配文件
├── dll # webpack dll静态资源输出目录
│ └── ...
├── lerna.json # lerna多package JavaScript项目管理配置文件
├── mock # mock静态数据服务配置相关
│ └── index.js
├── package.json # 本项目配置node.js 配置文件
├── packages
├── public # 公共静态资源目录
│ ├── ...
│ └── index.html # 本项目主页面html文件
├── scripts
│ ├── build.js # 生产环境编译脚本文件
│ ├── start.js # 项目开发者模式dev server启动脚本文件
│ └── test.js # 单元测试脚本工具
├── src
│ ├── index.js # 项目入口文件
│ ├── index.less # 项目全局样式
│ ├── models # 项目数据模型
│ │ └── global.js # 全局数据模型
│ ├── router.js # 路由管理逻辑文件
│ ├── routes # 项目核心业务逻辑/页面
│ │ └── index.js # 页面入口文件
│ ├── serviceWorker.js # 静态缓存service worker
│ ├── setupProxy.js # mock静态数据代理服务器配置文件
│ └── utils # 项目业业务逻辑通用方法
│ ├── getModuleRouters.js # hzero-front相关模块依赖注册
│ └── router.js # 路由控制逻辑文件
└── yarn.lock # 项目yarn node.js模块配置文件
启动项目
请确保dll静态资源已编译完成,否则请执行如下命令
$ yarn build:dll
请注意
dll无需频繁编译,若有新的依赖安装,且需要加入config/webpack.dll.config.js配置中,则需要重新编译dll
执行如下命令即可启动项目
$ yarn start
启动成功后,请访问如下地址即可
http://localhost:8000
cross-env BASE_PATH=/ CLIENT_ID=localhost BPM_HOST=http://192.168.12.103:8330 API_HOST=http://hzeronb.saas.hand-china.com WEBSOCKET_HOST=ws://172.20.0.202:8260 HARD_SOURCE=none node --max_old_space_size=4096 ./node_modules/roadhog/bin/roadhog.js dev
- start 会设置几个环境变量, 您可以改变他们来适应自己的项目
- BASE_PATH: 部署在子目录时需要改变。 例如 部署在 /demo/ 下; 则该变量的值为 /demo/
- CLIENT_ID: 是hzero后端所需要的客户端参数
- BPM_HOST: 工作流的接口地址
- API_HOST: 请求接口的地址
- WEBSOCKET_HOST: websocket 地址
初始化项目
执行如下命令即可重新安装项目依赖
$ yarn --registry http://nexus.saas.hand-china.com/content/groups/hzero-npm-group/
请注意npm源地址
若使用了lerna工具管理packages,则需要为packages安装依赖,在项目根目录下执行如下命令
$ lerna bootstrap --registry http://nexus.saas.hand-china.com/content/groups/hzero-npm-group/
关于
lerna请参考https://lernajs.io/ 关于lerna在HZERO Front/基于HZERO Front的项目中的使用请参考lerna
发布生产环境
请确保dll已编译完成,然后执行如下命令
$ yarn build
编译完成后在项目根目录下生成静态文件
/dist
接下来您可以将该静态文件用于nginx/node.js serve/docker等服务器部署
build 会设置几个环境变量, 您可以改变他们来适应自己的项目。
变量名及含义如下表所示：
| 变量名 | 含义 | 构建后需要替换 |
|---|---|---|
| BASE_PATH | 部署在子目录时需要改变。 例如 部署在 /demo/ 下; 则该变量的值为 /demo/ | 是 |
| CLIENT_ID | hzero 后端进行 OAUTH 认证所需要的客户端参数 | 是 |
| BPM_HOST | 工作流的接口地址 | 是 |
| API_HOST | 请求接口的地址 | 是 |
| WEBSOCKET_HOST | websocket 地址 | 是 |
| ESLINT | 由于在提交的时候已经校验过了 所以这里不执行校验以提升打包速度 | 否 |
| PLATFORM_VERSION | 系统是OP版还是SAAS版 | 是 |
替换操作
如果采用jenkins进行构建，则需要在 build 结束后手动执行 ./docker/enterpoint.sh 进行变量替换，因而需要在脚本中填写实际的变量值。
而如果采用gitlab CI进行构建，这些变量的值配置于 /charts/hzero-front/values.yaml 内，在构建时会将这些变量设置到当前执行环境，在脚本执行时便可读取以进行替换。
使用HZEOR Front客户端工具更新/升级项目
HZEOR Front客户端工具hzero-front-cli支持更新/升级已创建的新项目,请执行如下命令
# cd <your new hzero-front project>
# hzero-front-cli .
# 例如
$ cd hzero-front-demo
$ hzero-front-cli .
# hzero-front-cli 需要指定你的项目路径在当前项目根目录下需要指定的路径是 .
请注意hzero-front/hzero-front-*依赖的版本,执行如下命令
# hzero-front-cli -m <modules<@version>
# 例如
$ hzero-front-cli -m 'hzero-front@0.8.6 hzero-front-hagd@0.8.6 hzero-front-hcnf@0.8.6 hzero-front-hdtt@0.8.6 hzero-front-hfile@0.8.6 hzero-front-hiam@0.8.6 hzero-front-himp@0.8.6 hzero-front-hitf@0.8.6 hzero-front-hmsg@0.8.6 hzero-front-hpfm@0.8.6 hzero-front-hptl@0.8.6 hzero-front-hrpt@0.8.6 hzero-front-hsdr@0.8.6 hzero-front-hsgp@0.8.6 hzero-front-hwfl@0.8.6'
HZEOR Front客户端工具相关命令
-
-v, --version: 查看hzero-front-cli版本$ hzero-front-cli -v -
-i, --ignore [files]: 更新/升级时指定需要忽略更新/升级的文件# hzero-front-cli -i <files> $ hzero-front-cli -i 'config/routers.js lerna.json' -
--latest-modules: 安装最新版本的hzero-front/hzero-front-*相关依赖$ hzero-front-cli --latest-modules -
-m, --modules [modules: 指定hzero-front/hzero-front-*相关依赖安装# hzero-front-cli -m <modules> $ hzero-front-cli -m 'hzero-front@0.8.6 hzero-front-hagd@0.8.6' -
-w, --workspace: 启用lerna管理packages,并设置默认workspace$ hzero-front-cli -w -
-h, --help:hzero-front-cli工具使用说明
开发新功能
开发方式与新功能开发-开发方式基本一致,但如下规则不同
-
多语言维护:
// old // import prompt from 'utils/intl/prompt'; // new import formatterCollections from 'utils/intl/formatterCollections';// old // @prompt({ code: ['hiam.client'] }) // new @formatterCollections({ code: ['hiam.client'] }) -
配置路由:
// old /* // src/common/router.js // 客户端 '/hiam/client': { component: dynamicWrapper(app, ['hiam/client'], () => import('../routes/hiam/Client')), }, */ // new // config/routers.js module.exports = [ { path: "/hiam/client", // 路由地址 component: "hiam/Client", // 页面组件入口文件相对路径 models: [ "hiam/client" // 页面数据逻辑models相对路径 ] }, // ... ]
HZERO Front默认moduls依赖清单
hzero-front # hzero-front模块包含hzero-front主要components/utils等
hzero-front-hagd # hzero-front-hagd 模块
hzero-front-hcnf # hzero-front-hcnf 模块
hzero-front-hdtt # hzero-front-hdtt 模块
hzero-front-hfile # hzero-front-hfile 模块
hzero-front-hiam # hzero-front-hiam 模块
hzero-front-himp # hzero-front-himp 模块
hzero-front-hitf # hzero-front-hitf 模块
hzero-front-hmsg # hzero-front-hmsg 模块
hzero-front-hpfm # hzero-front-hpfm 模块
hzero-front-hptl # hzero-front-hptl 模块
hzero-front-hrpt # hzero-front-hrpt 模块
hzero-front-hsdr # hzero-front-hsdr 模块
hzero-front-hsgp # hzero-front-hsgp 模块
hzero-front-hwfl # hzero-front-hwfl 模块
安装默认moduls依赖,执行如下命令
# yarn add <modules> --registry http://nexus.saas.hand-china.com/content/groups/hzero-npm-group/
$ yarn add hzero-front hzero-front-hiam hzero-front-hpfm --registry http://nexus.saas.hand-china.com/content/groups/hzero-npm-group/