1. 为什么数据层会越写越重以及 simple_model 的纯粹从何而来先抛个结论这两年我过手的 Flutter 项目几乎每一个都栽在同一个坑里——把数据层做成了全家桶。而这次做鸿蒙化适配反而是项目里最轻的那一层最先跑通它就是基于 simple_model 构建的 POJO 映射与持久化中台。1.1 反模式一代码生成依赖过重构建时间被拖垮用 build_runner 和 json_serializable 做 JSON 映射在 Flutter 社区里已经算标准操作了。但代价是项目越到后期越难受。打个比方一个只有十几个字段的用户模型加上注解、私有字段、copyWith、toJson、fromJson 这些样板生成文件动不动就是两三百行。团队协作时同步 build_runner 版本、避免冲突、处理缓存失效都是不小的时间成本。更麻烦的是代码生成出来的类在 IDE 里跳转总是隔了一层。你明明改的是源文件但引用方看到的是生成文件排查问题的时候经常要在两个文件之间来回切。时间长了简单的数据类反而成了开发流程里最不简单的一环。1.2 反模式二模型类混入状态管理与业务逻辑另一个更隐蔽的坑是把 setState、ValueNotifier、甚至网络请求直接写在 Model 类里。我之前接手过一个订单模块OrderModel 里既有网络方法又有 UI 状态字段还有本地缓存逻辑。看起来写起来方便可真要换框架或者迁移到别的平台牵一发动全身。这类代码最大的问题是没法测试。Model 类一旦依赖了 BuildContext 或者平台通道单元测试就得 mock 一堆东西。真正干净的模型层应该做到不 import 任何 UI 相关的包不依赖任何平台能力只描述这条数据长什么样。1.3 POJO 思维的回归simple_model 到底做了什么simple_model 这个库的设计思路就是把 Model 重新变回纯粹的数据描述。你可以把它理解成 Flutter 世界里的 POJO——一个不带业务逻辑、不带界面、不带平台依赖的普通数据类。它和 json_serializable 这类方案最大的区别在于simple_model 不依赖庞大的代码生成流程而是把映射动作收敛到一组轻量的注解和运行时方法里。核心代码本身只依赖 collection、meta 这类纯 Dart 包没有任何平台通道参与。我在实际使用中的感受是它把创建模型这件事的认知负担降到了最低你要做的只是声明字段、声明类型、声明默认值其余交给库去处理。// simple_model 的模型声明方式 model(user) class User { final String id; final String name; final int age; final bool vip; User({required this.id, required this.name, required this.age, required this.vip}); }这样的模型类既不侵入业务也不用反复跑 build_runner而且天然方便做单元测试。更重要的是这种极致纯粹的设计在鸿蒙适配这件事上帮了我大忙——因为纯 Dart 代码在鸿蒙平台上几乎不需要额外改造。1.4 持久化与映射中台simple_model 的第二重身份简单来说simple_model 不只是一个 POJO 定义工具它还扮演了持久化与映射的中台角色。它把对象到 JSON、JSON 到对象的序列化过程以及对象到本地存储、本地存储回对象的持久化过程统一收敛到一个抽象层里。我自己在项目里是这么用的所有业务 Model 都继承同一个基础接口由 simple_model 统一提供 toJson、fromJson 的能力然后通过注册不同的持久化适配器把数据写到内存、偏好存储或者文件里。网络层、UI 层、缓存层全部通过这个中台交互谁也不直接碰 JSON 字符串或者文件路径。这带来一个直接的好处当我要把 Flutter 应用移植到鸿蒙时数据层完全不用重写。真正要处理的只是底层持久化适配器在鸿蒙上的落位问题。这也是为什么标题里我说它是专家级的 POJO 持久化与映射中台——它把数据建模这件事从天天写样板代码变成了定义结构其余交给中间层。2. 鸿蒙化适配的本质先摸清 simple_model 的代码边界很多人一听到鸿蒙化适配就头大以为要把整个工程推倒重来。实际上Flutter 应用鸿蒙化有个非常明确的分水岭你的依赖是纯 Dart还是带了平台通道。2.1 鸿蒙上 Flutter 的现状官方支持但生态尚浅先说清楚当前的大环境。Flutter 在鸿蒙上的运行是靠社区维护的 flutter_flutter 分支也就是常说的 harmony 分支实现的。这个分支已经能够支持创建 ohos 平台工程、编译成 HAP 包并在 HarmonyOS 设备上运行。开发工具也收敛到了 DevEco Studio 里流程比前几年成熟了不少。但生态深度还是比 Android/iOS 差一截。大量原生插件在鸿蒙上没有官方支持需要靠 OpenHarmony 社区提供的适配插件或者自己写。所以在选型阶段是否纯 Dart就成了一个决定适配工作量的关键指标。2.2 用三分法快速判断一个库的鸿蒙适配成本我一般用一套很简单的三分法来判断第三方库的鸿蒙适配难度准确率很高依赖形态典型表现鸿蒙适配成本纯 Dart 库pubspec 里只有 Dart 生态包不碰 dart:io、platform channel极低编译通过后基本直接可用依赖 Flutter 框架但无原生调用使用 Flutter 引擎提供的存储、路径等抽象接口中等需要确认鸿蒙分支对相关接口的实现是否完整依赖原生代码 MethodChannel通过插件注册、原生文件读写、硬件能力调用高必须编写鸿蒙原生侧适配simple_model 属于第一类。它的核心代码跑在纯 Dart VM 上不涉及 MethodChannel不依赖 Android Gradle Plugin也不依赖 iOS Pod。这意味着它在鸿蒙上的适配本质上就是编译进去、跑通测试的过程而不是改写实现的过程。2.3 从 pubspec 和源码确认 simple_model 的可移植性光靠判断还不够我通常还会做两步确认。第一步打开 simple_model 的 pubspec.yaml逐个看 dependencies。如果全部是纯 Dart 包比如 collection、meta 这类基本可以放心。如果出现了 shared_preferences、path_provider 这类平台插件就得继续看它是否正确拆分了可选依赖。第二步直接搜索源码里的 import 语句确认有没有 dart:io、package:flutter/services.dart、MethodChannel 之类的引用。package:flutter/services.dart这个 import 尤其要警惕它意味着库内部可能注册了平台通道而这种通道在鸿蒙上未必有对应实现。我用 simple_model 的某个版本验证过核心模块干净没有 dart:io 相关代码持久化适配器单独拆成了可插拔模块只有在实际需要时才引入平台相关实现。这种设计模式才是真正适合跨平台迁移的形态。它让我在鸿蒙化的时候几乎不用改业务代码。3. 一步步把 simple_model 跑在鸿蒙设备上完整适配过程确认边界之后适配工作就进入实操阶段了。下面这整套流程我跑通过好几遍照着做基本能一次走到构建环节。3.1 准备鸿蒙 Flutter 开发环境第一步是准备支持鸿蒙的 Flutter SDK。我使用的是社区维护的 harmony 分支部署方式和官方 Flutter SDK 基本一致。需要注意一个细节下载完 SDK 后不要直接覆盖原有的 Flutter 环境建议单独建一个目录用环境变量切换避免日常开发被破坏。# 切换到支持鸿蒙的 Flutter SDK 目录 export PATH$HOME/flutter_sdk_harmony/bin:$PATH # 确认版本信息 flutter --version我一般还会检查一下 Flutter 的版本号是否带 harmony 标记同时确认 dart 版本是否能正常工作。如果网络环境特殊记得把 PUB_HOSTED_URL 和 FLUTTER_STORAGE_BASE_URL 指到国内镜像这样下载依赖和预编译产物会稳定很多。3.2 创建支持 ohos 平台的新项目环境准备好之后创建一个新项目命令和官方 flutter create 几乎一样只是 platforms 参数里多了 ohos。flutter create --platforms ohos simple_model_demo cd simple_model_demo执行完会自动生成 ohos 目录里面是鸿蒙工程文件包括 entry、hvigorfile、build-profile.json5 等。这一步如果失败九成是 HarmonyOS SDK 没有在 DevEco Studio 里正确安装回头检查一下 API 版本配置。3.3 引入 simple_model 并处理依赖关系然后引入 simple_modelflutter pub add simple_model如果你需要持久化能力再根据 simple_model 的文档引入对应的适配模块。这里有个小经验尽量把项目里的依赖保持精简。有的适配模块依赖 shared_preferences 这类平台插件虽然现在有鸿蒙支持版但每多一个平台插件多一步适配风险。我自己的做法是先用 simple_model 自带的纯 Dart 文件持久化能力跑通全流程等确认无误再决定要不要换成偏好存储。3.4 构建 HAP 包并完成首次运行引入依赖后执行构建命令flutter build hap --debug第一次构建会花点时间因为它要编译 Dart 代码、生成鸿蒙工程资源还要完成签名配置。签名这块是新手最容易卡住的地方。鸿蒙应用需要 profile 签名文件你得在 DevEco Studio 里申请或者导入调试证书然后在工程的 build-profile.json5 里配置好签名信息。构建成功之后用flutter run -d device或者直接在 DevEco Studio 里运行看到一个 Hello World 页面出现在鸿蒙设备上就说明 Flutter 鸿蒙化底座已经通了。接下来要做的就是把 simple_model 真正用起来。4. 持久化与映射中台在鸿蒙上的落地实践底座通了接下来的问题就是数据层能不能在鸿蒙设备上正常工作我把 simple_model 的映射和持久化能力在鸿蒙上完整跑了一遍下面说说关键点。4.1 JSON 映射层的验证POJO 与 JSON 的双向转换simple_model 的映射层核心是 toJson 和 fromJson。我在鸿蒙设备上做了一个最小验证定义几个不同类型的字段包括 String、int、bool以及嵌套的对象类型然后测试往返转换的一致性。void verifyMapping() { final user User(id: 1001, name: Ada, age: 30, vip: true); // POJO - JSON final MapString, dynamic json user.toJson(); // JSON - POJO final User restored User.fromJson(json); assert(restored.id user.id); assert(restored.name user.name); assert(restored.vip user.vip); }这步看起来简单但在鸿蒙上跑通的含义很大。它意味着整个 Dart 侧的序列化链路在鸿蒙虚拟机里是完整可用的不需要任何平台通道参与。我之前担心过某些 Flutter 运行时接口在鸿蒙分支上实现不完整实际测下来纯 Dart 的部分非常稳。4.2 持久化适配层的选择文件存储优先simple_model 的持久化适配器通常有几种选择内存缓存、偏好存储、文件存储。在鸿蒙平台上我优先推荐文件存储。原因很简单偏好存储在鸿蒙上依赖 shared_preferences 的平台适配虽然社区有方案但多一层依赖就多一个不稳定因素。文件存储只需要一个可写的文件路径鸿蒙应用的沙盒目录机制和 Android 类似适配起来非常简单。final store SimpleModelFileStore( directory: await getApplicationSupportDirectory(), ); final dao UserDao(store); await dao.save(user); final loaded await dao.load(1001);如果不想引入 path_provider还有一个更保守的方案把存储路径硬编码成应用沙盒相对路径。鸿蒙和 Android 一样每个应用有自己隔离的文件目录直接使用Directory.systemTemp或者运行时构造一个相对路径也能达到持久化的目的。当然正式项目里还是建议用 path_provider 这类经过验证的路径方案。4.3 单元测试在鸿蒙模拟器上的坑与解法适配过程中我最推荐先跑单元测试而不是直接上界面。simple_model 是纯 Dart 库测试可以直接跑在 Dart 虚拟机上不需要鸿蒙模拟器。flutter test test/models_test.dart测试要点包括字段缺失时能否正确给出默认值未知字段是否被忽略而不是抛异常嵌套对象能否递归完成序列化持久化适配器写入和读回后对象是否完全一致把这几类测试跑绿数据层在鸿蒙上的信心就立住了。模拟器和真机上的差异主要集中在文件路径和权限这些在 UI 集成阶段再处理也来得及。5. 踩坑记录鸿蒙化过程中最折磨人的几个问题聊完顺利的部分再分享几个我实际踩过的坑。这些问题不是 simple_model 本身的问题而是整个 Flutter 鸿蒙化过程中的共性问题。5.1 旧版 Flutter 构建提示Gradle 插件即将被废弃适配初期我复用了一个比较旧的项目构建时终端打出一长串警告核心是一句you are applying flutters main gradle plugin imperatively using the apply method这句话的意思是 Flutter 的 Gradle 插件通过命令式 apply 方式被引入而新版 Flutter 推荐使用声明式插件配置。在 Windows 上意思可能会不同主要是由于当前 Flutter SDK 版本与项目 Gradle 配置不匹配。排查链路先确认 Flutter SDK 是否切到了 harmony 分支再检查 android/settings.gradle 里插件引入方式最后确认 gradle wrapper 版本是否和当前 Flutter 兼容。我当时的解决方案是重新用flutter create --platforms ohos生成一个新的工程骨架把旧项目的数据层代码和业务代码迁移过来。与其在旧工程里打补丁不如直接换新骨架干净利落。5.2 构建产物里缺少平台插件shared_preferences 静默失效另一个常见的坑是数据层明明调用了 shared_preferences但运行时不报错数据就是读不到。这个问题特别隐蔽因为 Flutter 应用在鸿蒙上时会走插件注册机制原生插件如果没被正确注册进 HarmonyOS 工程Dart 侧调用就会静默失败。排查链路检查ohos工程里是否生成了对应插件的原生代码查看oh-package.json5是否声明了插件依赖确认 Flutter 引擎在初始化时是否正确加载了插件注册表我一度以为是 simple_model 的问题后来发现是 shared_preferences 的鸿蒙适配需要单独引入插件包并且在工程配置里显式声明。所以如果你在鸿蒙上遇到不报错但功能无效的情况优先怀疑平台插件注册而不是业务代码。5.3 路径与目录差异临时目录和缓存目录不可混用鸿蒙的沙盒目录和 Android 有细微差别。我在一个版本里用了 getTemporaryDirectory 来存持久化数据结果在系统清理缓存后数据全部丢失。这其实不是适配问题而是使用姿势问题——临时目录本来就该放临时文件持久化数据应该放到应用支持目录。排查链路先确认用的是哪个 path_provider 接口打印并检查实际返回的路径判断是否落在缓存目录将持久化文件迁移到应用支持目录并写一个迁移工具这个问题是我自己使用不当但恰恰说明了一个道理在鸿蒙化过程中数据持久化方案要尽量简洁可控。simple_model 的文件存储适配器让我能清晰地看到文件写到了哪里而不是像偏好存储那样黑盒操作排查起来省了不少事。5.4 热重载失效与增量编译最后说一个效率问题。鸿蒙分支的 Flutter 热重载能力一开始会让人很沮丧尤其是在 Modifiers 编辑代码时按下去的快捷键根本没有反应。这通常不是 simple_model 的问题而是 harmony 分支的运行时限制。遇到这种情况最直接的解法是改用热重启而不是热重载。热重启虽然会重新执行 main 方法但至少不需要重新构建 HAP能节省大量时间。另外一个技巧是尽量把数据逻辑拆分到纯 Dart 模块里配合单元测试快速验证不要等跑到真机上才发现问题。6. 适配完成之后的一些体会和后续建议整个 simple_model 鸿蒙化适配做完我最大的体会是数据建模的纯粹性直接决定了跨平台迁移的难度。simple_model 这类 POJO 风格的设计之所以在鸿蒙上走得顺就是因为它把平台无关性当成了核心设计原则。如果你在选型的时候把鸿蒙友好也作为一个考量维度优先选择纯 Dart 依赖的库后续的适配成本会下降一个量级。关于后续扩展我有两个方向想聊。一个是在 simple_model 的数据层之上继续加上缓存策略和离线同步机制。因为它的持久化中台已经定义好了统一的读写接口加缓存只是在这个接口上再套一层策略而已。另一个方向是把它和现有的状态管理方案结合在鸿蒙应用里把数据层和 UI 层彻底解耦这样后续如果要把应用搬到其他形态的设备上数据模型这部分完全不用动。最后分享一个小技巧如果你也打算做鸿蒙化建议从最开始就把通用业务逻辑抽成一个纯 Dart 的包和宿主工程分开维护。这样无论是适配鸿蒙、继续支持 Android还是未来做桌面端适配你的数据层永远是最省心的那部分。