创建前端项目

本文将主要介绍如何使用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

由于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/