最近在做一个 Flutter 业务模块的鸿蒙端迁移拿到工程后我做的第一件事不是去调 UI 组件而是先把三四十个手写 JSON Model 全部翻了一遍。越整理越觉得JSON 到模型的转换如果还靠逐字段手写后面光是字段变更就够让人头疼。于是我把 json_model 这个三方库重新捡了回来在鸿蒙 Flutter 工程里做了一轮完整适配最终用一套命令行脚本把模型生成这件事彻底自动化了。这篇就把适配思路、命令行走法和踩过的坑完整记录下来给正打算做类似迁移的团队作个参考。json_model 这个名字你如果混 Flutter 圈应该不陌生。它主打极简的 JSON 到 Dart 模型转换核心思路是你用尽可能干净的类声明定义数据结构生成器在命令行里扫描这些声明自动产出 fromJson、toJson 等解析代码。这次把它迁移到鸿蒙生态难点不在于库本身而在于鸿蒙 Flutter 工程的环境差异、依赖版本约束以及如何把生成动作嵌进整套构建流水线。本文会按为什么选它—环境差异—命令行实战—踩坑实录—验证与复用的顺序讲文章最后一部分是我个人的适配体会。1. 为什么我在鸿蒙工程里仍然坚持用 json_model 生成模型1.1 手写 Model 的痛点长什么样先看一个特别常见的订单 JSON{ id: ord_20250101_001, userId: 10086, items: [ {sku: A001, name: 商品A, price: 19.9, count: 2} ], status: 1, extra: {origin: app, channel: android} }手写这个 Model 时你要处理嵌套 items、动态 extra、默认值、null 安全、toJson 时字段过滤等一堆细节。三五个类还能应付几十个类就是灾难。鸿蒙侧工程对数据模型的准确性要求又格外高字段漏一个可能在原生侧不报错但页面渲染或数据上报就会出问题。我见过不少团队用 json_serializable 配合 build_runner 做代码生成方案本身成熟但侵入性很强每个类都要额外加 part 指令、注解、mixinreview 代码时大部分精力浪费在样板代码上。json_model 的路线不同它让模型源文件尽量保持纯声明生成逻辑收拢到命令行里一次跑完用起来确实更清爽。1.2 json_model 的生成逻辑到底怎么工作以我手头使用的版本为例json_model 本质上是一个 Dart 命令行程序。它扫描指定目录下的模型源文件读取类的字段声明再根据这些声明生成独立的解析辅助文件。这个辅助文件包含了字段映射、嵌套对象转换、默认值处理等逻辑。关键点是它是静态生成不是运行期反射。这一点对鸿蒙适配极其关键。鸿蒙 Flutter 工程在 release 模式下走 AOT 编译如果你用运行期反射库做 JSON 转换轻则性能受损重则直接被编译链路掐掉。json_model 生成的代码是显式的 Dart 函数调用编译器能清楚看到每个类型从原理上就规避了反射带来的兼容问题。和 json_serializable 做一个直观对比对比项json_serializablejson_model驱动方式注解 build_runner watch命令行一次性扫描代码侵入性每个类都要写 part 和注解源文件保持纯声明生成文件与源文件绑定紧密独立文件替换成本低AOT 友好度友好友好鸿蒙侧迁移成本需要处理 build.yaml 与生成器插件兼容更轻依赖链路更短当然这并不意味着 json_model 在所有场景都优于 json_serializable。如果项目里大量依赖 JSON 自定义转换、需要深度定制生成模板build_runner 生态更庞大。但如果你要的是一个能快速迁移到鸿蒙、不引入过多代码生成依赖的方案json_model 的极简路线明显更合适。1.3 鸿蒙工程为什么需要精密的数据模型我们说鸿蒙级精密数据模型不是营销话术而是实际编译环境的硬要求。鸿蒙侧的 Flutter 构建链路比普通 Flutter 多了一层原生桥接模型类如果写得粗糙比如到处用 dynamic 透传编译阶段可能不报错但运行时类型收窄会引发大量隐形问题。数据模型的精密体现在四个层面字段类型确定、嵌套模型显式声明、可选字段有明确的 null 策略、JSON key 与 Dart 字段名之间的映射可控。json_model 恰好能把这些规则固化到生成器里。只要源模型声明是精确的生成代码就是精确的。字段调整后重跑一次命令所有关联解析逻辑自动更新人工手改导致的疏漏直接被消灭。我个人的经验是不要在源模型里写任何业务逻辑也不要手改生成文件。源模型是唯一的真相来源生成文件只是产物。这样无论是普通 Flutter 还是鸿蒙工程模型部分都能稳定复现。2. 鸿蒙化适配的前置功课Flutter 工程形态与依赖差异2.1 鸿蒙 Flutter 工程和普通 Flutter 工程的目录差异普通 Flutter 工程结构非常统一pubspec.yaml 在最外层lib 目录android/ios 目录分列两侧。鸿蒙 Flutter 工程则通常以Flutter 模块 鸿蒙壳工程的方式存在。壳工程负责 HAP 打包和系统能力调用Flutter 模块承载业务 UI。这意味着模型文件并不在工程根目录下而是位于 Flutter 模块内的 lib/ 路径中。适配 json_model 时最容易踩的坑就是路径。命令行生成器默认扫描的目录是当前工作目录下的相对路径如果你站在壳工程根目录执行命令它可能根本找不到模型源文件。所以你得明确执行目录到底是 Flutter 模块目录还是外壳工程目录。我的建议是在 Flutter 模块目录中创建一个 tool/gen_models.dart 脚本所有路径基于该模块的 Directory.current 计算不依赖 shell 的当前位置。这样无论从 DevEco 还是命令行触发行为都是一致的。2.2 pubspec 依赖声明与版本锁定json_model 本身是纯 Dart 库不依赖任何 Flutter 原生插件理论上鸿蒙 Flutter SDK 的 Dart 版本只要满足要求就能直接运行。但实际操作时我发现它的传递依赖比如 analyzer、source_gen 相关包对 Dart 版本非常敏感。鸿蒙 Flutter SDK 锁定的 Dart 版本如果和你本地 Flutter 版本不一致pub get 时就会出现版本求解失败。解决方案把 json_model 放进 dev_dependencies因为模型生成只发生在开发期运行时根本不需要它。同时给相关传递依赖加上合理的版本范围。示例dev_dependencies: json_model: ^2.0.0 json_annotation: ^4.8.0 dependency_overrides: analyzer: 5.13.0注意 dependency_overrides 要参考 json_model 自身的兼容范围不能随手拉高。我的习惯是优先使用与鸿蒙 Flutter SDK 捆绑的 Dart 版本相近的 analyzer 版本先跑通生成命令再逐步升级。2.3 依赖源和网络环境配置的坑鸿蒙工程的构建机器很多时候是隔离环境访问 pub.dev 不一定顺畅。这一步不做后面所有命令都会卡在拉包阶段。建议提前配置 PUB_HOSTED_URL 和 FLUTTER_STORAGE_BASE_URL 镜像地址。这个问题和 json_model 本身无关但鸿蒙化适配过程中它往往是第一个拦路虎。还有团队策略问题。生成文件到底要不要提交到 git我是提交生成文件派。理由很直接鸿蒙构建链路里多一步生成动作就多一个失败点。只要生成文件由固定版本命令产出并且源模型与生成文件同时提交提交就是安全的。不提交的话CI 上每次都需要重新执行生成网络或环境稍微有点问题整个构建就挂了。3. 命令行构建实战把模型生成嵌进鸿蒙构建流程3.1 先跑通最小命令适配第一步永远是先跑通最小命令。假设模型源文件放在 lib/models/ 目录每个 dart 文件声明一个业务模型在 Flutter 模块根目录执行dart run json_model如果你习惯全局安装也可以这样做dart pub global activate json_model json_model不同版本对命令行参数的支持略有差异以实际版本输出为准。跑完后你会看到 lib/models 下多出对应的生成文件。如果什么都没生成多半是源文件没有被正确识别先检查类声明是不是有语法错误再看生成器是否有自己的源文件命名约定。3.2 编写自动生成脚本手动敲命令方便但不可靠。为了保证每次构建前模型都是最新的我在 Flutter 模块里建了一个 tool/gen_models.dartimport dart:io; Futurevoid main(ListString args) async { final moduleRoot Directory.current; final modelsDir Directory(${moduleRoot.path}/lib/models); if (!modelsDir.existsSync()) { stderr.writeln(models dir not found: ${modelsDir.path}); exit(1); } final result await Process.run(dart, [run, json_model]); stdout.write(result.stdout); stderr.write(result.stderr); if (result.exitCode ! 0) { exit(result.exitCode); } }这个脚本看起来很朴素但它的价值在于可重复。生成结束后我再加两个动作自动执行 dart format 统一格式然后跑一次 dart analyze确保新增生成文件没有引入静态错误。两个动作都通过后才允许继续构建。3.3 从命令行脚本到鸿蒙工程流水线鸿蒙侧的构建通常由 DevEco 的 hvigor 任务驱动。整体流程是Flutter 模块先构建出 Flutter 产物壳工程再把它打包进 HAP。json_model 的生成步骤必须放在 Flutter 构建之前。实际操作时我写了一个前置脚本内容大致是先 cd 到 Flutter 模块目录执行 dart run json_model再执行 flutter build 相关命令。在 CI 上这个脚本作为独立 stage 存在。任何一步失败都会终止整个流水线绝不会带着过期模型继续打包。这里要特别强调不要在壳工程目录里执行 json_model。壳工程不一定有 Dart SDK 环境即便有路径也容易错。所有 Dart 相关操作都收敛到 Flutter 模块内这是适配期间最省心的做法。3.4 生成文件的 import 路径处理生成文件落盘后通常和源文件在同一目录通过相对 import 或 part 关联。鸿蒙 Flutter 编译时这些纯 Dart 文件会被正常编译不需要额外配置。需要注意两点文件名建议统一用 .g.dart 后缀并在 .gitignore 中管理临时产物如果模型被模块外引用要在 models.dart 这类 barrel 文件里统一导出避免相对路径一路向上追溯到壳工程。4. 踩坑实录适配期间我遇到的三类典型问题4.1 Dart 版本不匹配导致的生成器崩溃现象执行生成命令后直接抛出跟 analyzer 相关的异常提示某个 API 不存在或签名变了。 原因json_model 的传递依赖版本与鸿蒙 Flutter SDK 的 Dart 版本错位。 定位过程先看 pubspec.lock 中被锁定的 analyzer 版本再查鸿蒙 SDK 内置的 Dart 版本。两个环境之间反复切换时lock 文件会被反复重新解析这是问题高发期。 解决在 pubspec.yaml 中添加 dependency_overrides把 analyzer 固定到兼容版本。注意覆盖版本要参考 json_model 自身的兼容范围不能随便拉高。我的经验是优先使用与鸿蒙 Flutter SDK 捆绑的 Dart 版本相近的 analyzer 版本。4.2 生成的类与 Dart 语言关键字冲突现象生成文件编译报错提示某字段名是保留字或不合法标识符。 原因后端 JSON 的 key 与 Dart 关键字恰好同名。例如字段名是 class、extension、mixin。 定位打开生成文件找到冲突位置逐个核对。 解决在模型源文件中为字段指定 JSON 别名比如 Dart 字段叫 klass映射到 JSON key class。生成器会自动产出正确的字段名映射而不是硬编码保留字。这个坑在普通 Flutter 项目里也会遇到但鸿蒙侧编译时错误往往被埋在原生构建日志里提示不够友好。我建议配置别名后顺手写一个测试用例对每个字段做一次 fromJson 往返验证。4.3 嵌套模型生成后又被人手动改回 dynamic现象AOT release 构建通过但启动后某个页面数据为空日志里是类型转换错误。 原因有人为了让一个嵌套对象灵活把生成的字段类型从具体模型改成了 dynamic。多了一层自由度代价是鸿蒙 Flutter 的 release 构建下动态类型绕过编译检查运行时拆箱失败直接静默返回 null。 解决回到源模型声明把嵌套对象的结构补全重新生成。数据模型层面宁可多建一个类也不要用 dynamic 换取一时方便。下面是我整理的问题对照问题现象常见原因处理方式生成器崩溃analyzer 版本与 Dart SDK 不匹配锁定 dependency_overrides编译报保留字错误JSON key 与 Dart 关键字冲突为字段设置 JSON 别名release 运行数据为空有人把嵌套类型改成 dynamic恢复具体类型并重新生成4.4 我总结的排查链路如果你也遇到不明所以的编译问题按这个顺序排查先确认生成文件是最新的删除所有生成文件后重新生成再单独运行 dart analyze看纯 Dart 层是否有错然后运行 flutter build把错误缩小到原生层最后才检查鸿蒙壳工程的打包配置。多数 json_model 相关的问题在第二步就会暴露完全不需要去翻 HAP 构建日志。这套链路我用了很多次每次都能快速定位问题。5. 适配完成后的质量验证、复用方式与后续扩展5.1 验证链路不只看能编译编译通过不等于模型正确。我在 Flutter 模块里加了一个模型解析测试用一份线上真实 JSON 快照作为测试数据断言每个字段值符合预期尤其覆盖四种情况嵌套对象、数组为空、字段缺失、额外多余字段。json_model 生成的代码对这些边界处理是否到位一测便知。在这个验证环节飞 null 安全策略也很重要有些字段缺省时应该为 null有些应该为默认值。这些策略要在源模型声明阶段就写清楚测试只是兜底。在鸿蒙工程里跑这个测试不需要真机直接用 flutter test 即可。这一步能帮你在开发早期发现大部分模型定义错误而不是等打包后到真机上去猜。5.2 多模块复用的组织方式当多个鸿蒙 Flutter 模块需要共用同一套模型时不要各自复制一份源文件。我的做法是把模型源文件抽成一个独立的本地 Dart package只存放纯模型声明和生成文件不包含任何业务逻辑。各个 Flutter 模块通过 path 依赖引用它这样改一个字段所有模块重新生成一次即可同步。这种结构还能规避鸿蒙侧依赖重复的问题。最终打 HAP 时Dart 代码会做统一的资源合并不会有原生模块那种重复符号冲突。如果某个模块只需要其中几个模型也不要拆包统一维护一套模型包更省心。5.3 后续扩展自定义类型与枚举模型不可能永远是 string/int你可能会遇到 DateTime、枚举、嵌套泛型等场景。我建议不要把复杂转换逻辑写进模型源文件而是为这些类型单独声明普通 Dart 类json_model 处理不了的转换逻辑在生成文件之外补充少量扩展函数。如果你觉得手动补充不够自动化可以在生成脚本里加一层自定义模板替换生成结束后对特定生成文件做字符串替换或追加辅助方法。只要保证可重复、可验证就不算 hack。我目前就是这么做的生成脚本里预留了一个 afterGenerate 钩子专门跑这些额外处理。最后再分享一点个人体会。这次鸿蒙化适配让我感受最深的是工具链迁移本身不复杂复杂的是把工具放进一个全新的构建链路时那些不起眼的路径、版本、环境问题。如果你正卡在类似问题上先从最小的模型声明开始跑通一次完整链路再逐步扩大应用范围。链路一旦通了后面全是体力活。不管你是刚从 Flutter 转到鸿蒙还是已经在鸿蒙工程里摸爬滚打了一阵子希望这份记录能帮你少踩几个坑。
