1. 项目概述从零到一构建HZERO前端应用最近在做一个基于HZERO平台的前端项目从环境搭建到功能上线完整走了一遍。HZERO作为一款企业级中台解决方案其前端架构基于React和Choerodon UI提供了一套完整的数据驱动开发范式。对于刚接触的开发者来说面对DataSet、路由配置、API对接这些概念可能会觉得有些门槛。这篇内容我就以一个完整的“员工信息管理”模块为例拆解HZERO前端开发的核心流程和关键细节分享从创建项目到部署上线的实操经验希望能帮你绕过我踩过的那些坑。这个示例适合有一定React基础正准备或正在使用HZERO进行前端开发的工程师。我们将聚焦于最核心的几个部分如何初始化一个标准的HZERO前端项目、如何使用DataSet管理表单和表格数据、如何配置路由与菜单、以及如何与后端API进行联调。你会发现一旦理解了其设计思想开发效率会非常高。2. 环境准备与项目初始化2.1 开发环境搭建HZERO前端开发依赖于Node.js环境。我推荐使用nvmNode Version Manager来管理Node版本这样可以轻松地在不同项目间切换。当前HZERO前端脚手架对Node版本有一定要求经过实测Node.js 14.x或16.x的LTS版本是比较稳定的选择。安装好Node后npm或yarn包管理器自然就可用我个人更倾向于yarn因为它在依赖安装的速度和确定性上表现更好。注意尽量避免使用Node.js的最新奇数版本如17.x, 19.x这些版本可能包含不稳定的特性与某些依赖包存在兼容性问题。接下来是关键的一步安装HZERO前端脚手架工具。官方提供了choerodon/boot脚手架。通过以下命令全局安装npm install -g choerodon/boot # 或 yarn global add choerodon/boot安装完成后你可以使用choerodon命令。验证安装是否成功可以运行choerodon -V查看版本号。2.2 创建并启动新项目有了脚手架创建新项目就非常简单了。找一个合适的目录执行创建命令choerodon init your-project-name这里的your-project-name替换为你的项目名称例如hzero-demo。执行命令后脚手架会交互式地询问一些配置选项例如项目描述、是否启用TypeScript、是否使用Less等。对于新手我建议先全部选择默认配置以减少初期复杂度。项目创建完成后进入项目目录并安装依赖cd your-project-name yarn install # 或使用 npm npm install依赖安装完成后使用yarn start或npm start即可启动本地开发服务器。默认情况下浏览器会自动打开http://localhost:8000你会看到HZERO平台的登录页面这标志着项目骨架已经成功运行。实操心得第一次yarn install可能会比较慢因为需要下载Choerodon UI、Ant Design等一整套依赖。如果遇到网络问题可以考虑配置淘宝NPM镜像。另外项目根目录下的.env文件可以配置一些环境变量比如PORT3000可以修改开发服务器的端口。3. 核心概念解析DataSet与路由3.1 DataSet数据集的深入理解与应用DataSet是HZERO前端开发中最核心、也最具特色的概念。你可以把它理解为一个智能的、统一的数据管理单元。在传统的React开发中表单数据、表格数据、查询条件可能散落在组件的各个useState里管理和联动非常繁琐。DataSet将这些数据状态、校验规则、提交逻辑集中管理实现了真正的数据驱动视图。一个DataSet主要包含以下几个部分fields: 定义数据字段。每个字段可以配置类型、默认值、标签、校验规则等。transport: 定义数据运输方式即如何与后端API交互。包括read查询、create新增、update更新、destroy删除的配置。events: 数据集的生命周期事件如beforeLoad、submitSuccess等用于在数据读取或提交前后执行自定义逻辑。让我们以“员工信息”为例创建一个DataSet。通常我们会在src/models目录下创建对应的模型文件例如employeeDS.js。// src/models/employeeDS.js import { DataSet } from choerodon-ui/pro; export default function EmployeeDS() { return new DataSet({ autoCreate: true, // 是否自动创建一条记录 primaryKey: employeeId, // 指定主键字段名 fields: [ { name: employeeId, type: string, label: 员工ID, required: true, }, { name: name, type: string, label: 姓名, required: true, maxLength: 50, }, { name: gender, type: string, label: 性别, required: true, lookupCode: HR.GENDER, // 使用值列表从后端获取选项 }, { name: email, type: string, label: 邮箱, validator: (value) { // 自定义校验器 const emailPattern /^[^\s][^\s]\.[^\s]$/; return emailPattern.test(value) ? true : 请输入有效的邮箱地址; }, }, { name: hireDate, type: date, label: 入职日期, required: true, }, ], transport: { read: { url: /hzero/v1/employees, method: get, }, create: { url: /hzero/v1/employees, method: post, }, update: { url: /hzero/v1/employees, method: put, }, destroy: { url: /hzero/v1/employees, method: delete, }, }, // 事件绑定 events: { submitSuccess: ({ dataSet }) { // 提交成功后刷新表格数据 dataSet.query(); }, }, }); }在这个配置中lookupCode是一个亮点。它指向后端定义的值列表编码HR.GENDER前端无需硬编码[ { value: M, meaning: 男 }, ... ]DataSet会自动发起请求获取选项数据保证了前后端枚举值的一致性。3.2 路由与菜单的配置逻辑HZERO前端采用中心化的路由配置方式所有路由信息在src/router/.router.config.js或类似配置文件中定义。这种配置不仅决定了页面的访问路径还自动生成了平台左侧的导航菜单。路由配置通常是一个数组每个路由对象包含path、component、authority等属性。一个关键点是menu属性它决定了这条路由是否以及如何出现在菜单中。// 简化版的路由配置示例 const routerConfig [ { path: /, component: ../layouts/BasicLayout, // 基础布局组件 routes: [ // 首页/仪表盘 { path: /, redirect: /dashboard, exact: true, }, { path: /dashboard, component: ./Dashboard, menu: { name: 工作台, // 菜单显示名称 icon: dashboard, // 菜单图标 }, }, // 员工管理模块 { path: /hr, menu: { name: 人事管理, icon: team, }, routes: [ { path: /hr/employee, component: ./hr/EmployeeList, // 对应的页面组件 menu: { name: 员工信息, icon: user, }, }, ], }, ], }, ];配置完成后访问http://localhost:8000/#/hr/employee就能看到员工列表页面并且左侧菜单会自动出现“人事管理”和其下的“员工信息”子菜单。注意事项路由的path配置需要和后端权限配置的菜单路由码保持一致这是实现权限控制的基础。修改路由后有时需要清除浏览器缓存或重启开发服务器才能看到最新的菜单结构。4. 页面组件开发实战4.1 构建员工信息列表页列表页通常是CRUD操作的入口主要包含查询表单和数据表格。我们创建一个src/pages/hr/EmployeeList.js文件。首先在组件中引入我们之前定义的DataSetimport React from react; import { DataSet, Table, Form, TextField, Select, DatePicker, Button } from choerodon-ui/pro; import EmployeeDS from /models/employeeDS; // 是配置好的src目录别名 const { Column } Table; const { Item: FormItem } Form; export default function EmployeeList() { // 初始化DataSet实例 const employeeDS React.useMemo(() new DataSet(EmployeeDS()), []); // 查询处理函数 const handleQuery () { employeeDS.query(); }; // 重置查询表单 const handleReset () { employeeDS.queryDataSet.reset(); employeeDS.query(); }; return ( div {/* 查询表单 */} Form dataSet{employeeDS.queryDataSet} columns{4} style{{ marginBottom: 16 }} FormItem namename TextField placeholder请输入姓名 / /FormItem FormItem namegender Select placeholder请选择性别 / /FormItem FormItem namehireDate DatePicker placeholder请选择入职日期 / /FormItem div style{{ lineHeight: 32px }} Button onClick{handleQuery} colorprimary 查询 /Button Button onClick{handleReset} style{{ marginLeft: 8 }} 重置 /Button /div /Form {/* 数据表格 */} Table dataSet{employeeDS} queryBarnone buttons{[add, delete, export]} Column nameemployeeId header员工ID width{120} / Column namename header姓名 width{100} / Column namegender header性别 width{80} / Column nameemail header邮箱 width{180} / Column namehireDate header入职日期 width{120} / Column header操作 width{120} renderer{({ record }) ( div Button funcTypeflat iconmode_edit onClick{() employeeDS.current record} / Button funcTypeflat icondelete onClick{() record.destroy()} / /div )} / /Table /div ); }这里有几个关键点employeeDS.queryDataSetDataSet会自动生成一个用于查询条件的子DataSet其字段定义与主DataSet一致但通常只用于查询过滤。Table的buttons属性直接配置了[add, delete, export]Choerodon UI的Table组件内置了这些按钮的功能add按钮会弹出一个模态框用于新增其表单字段自动基于DataSet的fields生成极大地减少了样板代码。操作列中的record代表当前行数据。employeeDS.current record会将当前记录设为“当前记录”从而在表单模态框中进入编辑模式record.destroy()会触发DataSet配置的transport.destroy请求删除该行数据。4.2 实现自定义弹窗表单虽然Table内置的弹窗很方便但有时我们需要更复杂的自定义表单布局。这时可以手动控制一个模态框Modal。我们需要用到Choerodon UI的Modal组件和Form组件。首先在组件状态中控制模态框的显示隐藏import { Modal } from choerodon-ui/pro; function EmployeeList() { const [modalVisible, setModalVisible] useState(false); const employeeDS React.useMemo(() new DataSet(EmployeeDS()), []); // 打开新增弹窗 const handleAdd () { employeeDS.create(); // 创建一条新记录 setModalVisible(true); }; // 打开编辑弹窗从操作列调用 const handleEdit (record) { employeeDS.current record; setModalVisible(true); }; // 保存表单 const handleSave async () { try { // 触发DataSet的提交会根据当前记录状态新建或更新自动调用create或update const result await employeeDS.submit(); if (result result.success) { setModalVisible(false); employeeDS.query(); // 保存成功后刷新列表 } } catch (error) { console.error(保存失败:, error); } }; return ( Button onClick{handleAdd} iconadd 新增员工 /Button {/* 自定义模态框 */} Modal title{employeeDS.current employeeDS.current.status add ? 新增员工 : 编辑员工} visible{modalVisible} onCancel{() setModalVisible(false)} onOk{handleSave} destroyOnClose Form dataSet{employeeDS} labelLayouthorizontal labelWidth{80} FormItem namename TextField / /FormItem FormItem namegender Select / /FormItem FormItem nameemail TextField / /FormItem FormItem namehireDate DatePicker / /FormItem /Form /Modal {/* ... 表格等其他代码 ... */} / ); }这种方式给了我们更大的控制权比如可以在模态框里放更复杂的布局或者在保存前后执行特定的业务逻辑。5. 前后端联调与API对接5.1 配置请求拦截与响应处理HZERO前端项目默认使用了axios作为HTTP客户端并已经在src/utils/request.js中进行了封装。我们通常需要在这里统一配置请求拦截器例如添加Token和响应拦截器例如统一处理错误。一个常见的需求是在请求头中携带认证Token// src/utils/request.js import axios from axios; import { getToken } from /utils/auth; // 假设有一个从cookie或localStorage获取token的方法 const service axios.create({ baseURL: process.env.API_HOST || /api, // 基础URL可在.env文件中配置 timeout: 20000, }); // 请求拦截器 service.interceptors.request.use( (config) { const token getToken(); if (token) { config.headers[Authorization] Bearer ${token}; } // HZERO后端接口通常需要租户ID和语言头 config.headers[H-Tenant-Id] localStorage.getItem(tenantId) || 0; config.headers[Accept-Language] localStorage.getItem(language) || zh-CN; return config; }, (error) { return Promise.reject(error); } ); // 响应拦截器 service.interceptors.response.use( (response) { const res response.data; // 根据后端统一返回结构判断成功与否例如 { success: true, data: {...} } if (res.success) { return res.data; // 直接返回业务数据 } else { // 业务逻辑错误例如参数校验失败 Message.error(res.message || 请求失败); return Promise.reject(new Error(res.message || Error)); } }, (error) { // HTTP状态码错误如 401, 403, 500 if (error.response error.response.status 401) { Message.error(登录已过期请重新登录); // 跳转到登录页 window.location.href /user/login; } else { Message.error(error.message || 网络请求失败); } return Promise.reject(error); } ); export default service;在DataSet的transport配置中我们写的URL如/hzero/v1/employees会被自动拼接到baseURL之后形成完整的请求地址。5.2 处理文件上传与下载在员工管理模块很可能需要上传员工头像或导出员工列表。HZERO的Choerodon UI组件库提供了Upload组件可以很好地与DataSet集成。文件上传示例假设员工信息中有一个头像字段avatar其值是一个文件ID由后端上传接口返回。// 在employeeDS的fields中增加头像字段 { name: avatar, type: string, label: 头像, },在页面组件中使用Upload组件import { Upload, Button } from choerodon-ui/pro; FormItem nameavatar Upload acceptimage/* action/hzero/v1/files/upload // 后端上传接口 headers{{ Authorization: Bearer ${getToken()} }} data{{ bucketName: employee-avatar }} // 额外的上传参数 onChange{(info) { if (info.file.status done) { // 上传成功将后端返回的文件ID设置到DataSet字段中 const fileId info.file.response.fileId; employeeDS.current.set(avatar, fileId); } }} Button iconfile_upload上传头像/Button /Upload /FormItem文件下载示例导出员工列表为Excel是一个常见功能。我们可以直接通过一个GET请求触发下载后端接口应设置正确的响应头Content-Disposition: attachment。const handleExport () { const queryParams employeeDS.queryDataSet.toData(); // 获取查询条件 const params new URLSearchParams(queryParams).toString(); const downloadUrl /hzero/v1/employees/export?${params}; window.open(downloadUrl, _blank); };将这个函数绑定到导出按钮上即可。6. 样式定制与主题配置6.1 使用Less进行样式覆盖HZERO前端基于Ant Design而Ant Design使用Less作为样式预处理器。项目结构中的src/styles目录是放置全局样式的地方。如果你想覆盖Choerodon UI或Ant Design的默认样式可以在这里创建override.less文件。例如修改全局主色// src/styles/override.less primary-color: #1890ff; // 默认蓝色 // 改为企业品牌色 primary-color: #f5222d; // 修改表格行高 table-row-height: 60px; // 修改按钮圆角 border-radius-base: 2px;修改后需要在入口文件如src/index.js中引入这个样式文件import ./styles/override.less;注意事项样式覆盖应在了解组件原有样式结构的基础上进行避免过度覆盖导致样式混乱。建议使用浏览器开发者工具查看元素类名再进行精准覆盖。6.2 组件级别的样式方案对于页面或组件独有的样式我推荐使用CSS Modules或者Styled Components这样的方案来避免样式冲突。HZERO脚手架默认支持CSS Modules。创建一个EmployeeList.module.less文件// src/pages/hr/EmployeeList.module.less .container { padding: 24px; background: #fff; } .queryForm { margin-bottom: 20px; padding: 16px; background: #fafafa; border-radius: 4px; } .operationBar { display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px; }在组件中引入并使用import styles from ./EmployeeList.module.less; export default function EmployeeList() { return ( div className{styles.container} div className{styles.operationBar} {/* ... 操作按钮 ... */} /div {/* ... 其他内容 ... */} /div ); }这样样式会被编译成唯一的类名完全隔离在当前组件内。7. 构建优化与部署上线7.1 生产环境构建配置开发完成后需要构建生产环境代码。HZERO脚手架基于Umi构建命令很简单npm run build # 或 yarn build构建过程会进行代码压缩、Tree Shaking、代码分割等优化产出物在./dist目录下。在构建前有几个关键的配置需要检查环境变量在项目根目录创建.env.production文件配置生产环境变量。# .env.production API_HOSThttps://api.your-domain.com PUBLIC_PATH/hzero-front/PUBLIC_PATH非常重要它决定了静态资源JS、CSS、图片的引用路径。如果你的应用部署在子路径下如https://www.your-domain.com/hzero-front/必须正确设置此变量。路由模式HZERO默认使用hash路由URL中有#。如果想使用更优雅的browser history模式无#需要在src/config.js或Umi配置中修改。// .umirc.js 或 config/config.js export default { history: { type: browser }, // ... 其他配置 };注意使用browser history模式需要后端服务器如Nginx做好路由回退配置将所有前端路由请求都指向index.html。7.2 部署与Nginx配置构建出的dist目录是纯静态文件可以部署到任何静态文件服务器或CDN。这里以最常用的Nginx为例给出一个基本的配置。假设我们将dist目录下的所有文件上传到服务器的/usr/share/nginx/html/hzero-front目录。server { listen 80; server_name your-domain.com; # 前端静态资源 location /hzero-front/ { alias /usr/share/nginx/html/hzero-front/; index index.html index.htm; try_files $uri $uri/ /hzero-front/index.html; # 支持browser history的关键配置 expires 1y; add_header Cache-Control public, immutable; } # 后端API代理解决跨域 location /api/ { proxy_pass http://backend-server:8080/; # 后端服务地址 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 如果API网关或后端服务有独立域名也可以不配代理前端直接请求完整URL }这个配置做了三件事将/hzero-front/路径映射到前端静态文件目录。try_files指令确保在直接访问前端路由如/hzero-front/hr/employee时能正确返回index.html由前端React Router接管路由。将/api/开头的请求代理到真正的后端服务器解决了开发和生产环境的API地址问题也避免了跨域。部署后访问http://your-domain.com/hzero-front即可看到应用。8. 开发中的常见问题与调试技巧8.1 DataSet数据状态管理问题问题1表格数据不更新现象调用dataSet.query()后表格数据没有刷新。排查检查浏览器网络面板确认请求是否成功发出并返回了数据。检查返回的数据结构是否与DataSet中fields定义的字段名匹配。特别是主键字段primaryKey如果返回数据的主键名不一致例如定义为id但返回employeeIdDataSet可能无法正确合并数据。在transport.read的transformResponse回调中打印返回数据看是否需要进行数据转换。解决确保API返回的数据格式正确或使用transformResponse进行适配。transport: { read: { url: /hzero/v1/employees, method: get, transformResponse: (data) { // 如果后端返回格式为 { content: [...], total: 100 } return { list: data.content, total: data.total, }; }, }, }问题2表单提交后字段被清空现象在自定义模态框中编辑数据点击保存后表单输入框的内容突然清空了。原因这通常是因为在保存成功后直接setModalVisible(false)关闭了弹窗但DataSet的当前记录current状态没有重置。或者在保存成功的回调中又触发了某些会重置DataSet的操作。解决在关闭模态框时手动清除DataSet的当前记录。const handleSave async () { try { await employeeDS.submit(); setModalVisible(false); employeeDS.current null; // 关键清空当前记录 employeeDS.query(); } catch (error) { // 处理错误 } };8.2 路由与菜单配置不生效问题新增了路由配置但菜单不显示或页面访问404排查步骤检查路由配置文件路径和语法确认修改的是正确的router.config.js文件并且JSON/JS语法没有错误。检查menu配置确保路由对象中包含了menu: { name: ..., icon: ... }。只有配置了menu属性的路由才会出现在菜单中。嵌套路由的父节点通常也需要menu配置。检查组件路径component属性指向的页面组件路径是否正确文件是否存在。清除缓存开发环境下Umi可能会缓存路由配置。尝试执行yarn start --force或删除.umi临时目录后重启。检查权限如果平台启用了权限控制需要确认当前登录用户是否拥有该菜单和页面的权限。可以在后端的权限管理界面进行配置。8.3 样式覆盖不生效或冲突问题写了Less样式覆盖但没有效果排查加载顺序确保自定义的override.less在Ant Design的样式之后引入。在src/global.less或入口文件中正确的引入顺序是import ~antd/lib/style/themes/default.less; import ~antd/dist/antd.less; import ./override.less; // 你的覆盖样式样式优先级使用浏览器开发者工具检查目标元素看你的样式规则是否被更高优先级的规则覆盖了。可能需要使用更具体的选择器或添加!important谨慎使用。变量名检查覆盖的Less变量名是否正确。Ant Design的变量列表可以在其官方文档中查到。8.4 性能优化点随着应用变大需要注意一些性能问题按需加载Umi默认支持路由组件的动态导入Code Splitting。确保路由配置中的component使用的是动态导入语法dynamic这能有效减少首屏加载体积。// 在router.config.js中 { path: /complex-page, component: dynamic(() import(./pages/ComplexPage)), }DataSet序列化避免将DataSet实例直接存入Redux或通过Context传递因为DataSet包含大量观察者和方法序列化会消耗性能且可能出错。应该只传递必要的数据dataSet.toData()。表格大数据量渲染超长列表时使用Table的virtual属性开启虚拟滚动或使用分页。Choerodon UI的Table组件对性能有较好优化但仍需避免单页加载过多数据。整个流程走下来HZERO前端开发的核心在于理解DataSet这一套数据管理哲学。初期可能需要适应这种强约束的模型但一旦熟悉在开发标准的中后台CRUD应用时效率提升是非常明显的。最大的体会是前期花时间设计好DataSet的fields和transport后续的视图层开发会变得非常顺畅。
原理与应用)
