ArkTS + Node.js 端云一体应用的分层设计实践
一、为什么要做端云分层
鸿蒙端云一体应用的核心不是把请求发到云端,而是把渲染、状态、业务、数据四类职责划清边界。端侧负责 UI 渲染与用户交互状态,云侧负责业务规则、鉴权与数据持久化。边界清晰后,端侧可以在弱网、离线场景下降级,云侧可以独立演进接口与存储模型。
实践中常见的反模式是把业务规则写在页面里,导致同一规则在多个页面重复实现。更稳妥的做法是端侧只保留展示模型与交互状态,所有可复用的判定逻辑统一收敛到云侧接口,端侧只做结果映射。
二、接口契约先于代码
在 PRD 阶段就应明确端云接口契约,包括字段命名、时间格式、错误码与分页约定。时间统一使用带时区的 ISO 8601 字符串,避免端侧解析歧义;错误码分为业务错误与系统错误两类,端侧对业务错误做明确提示,对系统错误做统一兜底;列表接口统一返回 items、total、nextCursor,便于端侧实现分页与下拉刷新。
契约一旦确定,端侧可以用 Mock 数据先行开发,云侧并行实现,减少联调阶段的返工。
三、端侧工程结构
ArkTS 端侧建议按 Pages、Service、Models、Utils 分层。Pages 只处理渲染与事件,Service 封装网络请求与缓存,Models 描述数据结构与转换,Utils 收敛日期与格式化等纯函数。网络层统一封装超时、重试与统一错误提示,页面不直接调用 HTTP 客户端。
状态管理方面,页面级状态留在组件内,跨页面共享状态通过 AppStorage 或统一的状态容器管理,避免把全局状态散落在各页面。
四、云侧服务设计
Node.js 与 Express 侧按 Routes、Services、DAO 三层组织。Routes 只做参数校验与响应组装,Services 承载业务规则,DAO 负责数据访问。鉴权放在中间件层,统一校验令牌并注入当前用户上下文,业务层不重复解析令牌。
数据访问建议使用参数化查询,禁止字符串拼接 SQL;写操作统一放在事务中,保证多表更新的一致性。对外接口做限流与幂等处理,尤其是签到、下单这类重复提交风险高的场景。
五、数据同步与冲突处理
端云同步的难点是冲突。常见策略有两种:服务端时间为准的最后写入胜出,以及基于版本号的乐观并发控制。后者在字段级更新场景更可靠:端侧提交时携带版本号,服务端比对失败则返回冲突码,端侧拉取最新数据后提示用户合并。
离线场景下,端侧可以维护一个待同步队列,恢复网络后按顺序重放,并为每个操作生成客户端唯一 ID,服务端据此去重,避免重复提交。
六、部署与联调
部署阶段把端侧构建产物与云侧服务分离。端侧通过 hvigor 构建 HAP,云侧通过 PM2 或容器运行,反向代理统一入口并处理 HTTPS。联调时保留一份可开关的日志级别配置,便于定位端云之间的字段不一致问题。
最后,建议在项目初期就固化一份接口文档与错误码表,并纳入代码评审检查项。端云一体的质量,往往取决于契约是否被严格遵守,而不是框架选得多新。
- 点赞
- 收藏
- 关注作者
评论(0)