把一套重度使用三方库dartonic的 Flutter 工程往鸿蒙上迁移时最先翻车的地方往往不在页面也不在状态管理而是那些依赖运行时反射和代码生成的三方逻辑库。dartonic这种主打模式匹配与 ADT代数数据类型的库恰好就踩在这个点上。这篇文章讲的是我们团队怎么把它“鸿蒙化”的不是硬着头皮去改它的源码也不是用一堆if/else把逻辑重新糊一遍而是借鸿蒙侧 Flutter SDK 的现代化 Dart 能力把模式匹配和 ADT 治理沉淀成一套可复用的中台方案。如果你也在做 Flutter 应用向鸿蒙迁移或者正在为团队的业务逻辑越来越难维护而头疼这篇适配指南应该能给你一条可落地的路径。先说清楚我们说的“ADT”是什么。ADT 是 Algebraic Data Type 的缩写翻译过来是代数数据类型核心就两种积类型比如一个数据类同时有多个字段和和类型一个数在多个互斥的子类型中取其一。Dart 里的sealed class加上final class其实就是在表达和类型。而 ADT 治理指的是用这种类型建模业务状态、约束非法组合、通过模式匹配把分支逻辑收敛到一处。dartonic这个三方库干的正是这件事它提供了类似 Scala 或 Haskell 风格的模式匹配器配合不可变数据类让业务逻辑保持“函数式纯粹”。听起来很美好但到了鸿蒙上问题就来了。1. 为什么鸿蒙应用需要 ADT 治理中台1.1 业务逻辑失控的根源if/else 泥潭我先讲一个真实的场景。我们团队之前维护一个电商 App 的 Flutter 版本订单模块的状态既有待支付、已支付、待发货、已发货、已取消还有售后中的各种子状态。这些状态本来应该是一个封闭的集合——在某一时刻订单只会处于其中一种状态。但代码里怎么写的散落各处的if (order.status 1)、if (order.status ! 4 order.canRefund)十几处地方各判断各的没人能说清楚到底有多少种组合是合法的。这种代码的问题在于状态的可视性被稀释了。单个字段的取值看起来无害但状态和状态之间的关联、状态和操作之间的约束全都被埋在命令式代码里。后来我们接入了dartonic把订单状态建模成一棵密封的继承树每个子类型自带不可变字段所有分支逻辑收敛到模式匹配器里。效果立竿见影新增一种状态编译器会提醒你哪些匹配点没覆盖非法状态组合在建模阶段就被类型系统挡住了。这就是 ADT 治理要解决的核心问题让业务状态可枚举、可穷尽、不可篡改。它不改变业务本身而是把“哪些情况是合法的”这件事从运行时错误变成了编译期约束。1.2 dartonic 在 Flutter 侧承担的职责dartonic这个库在我们工程里承担了三件事。第一它提供了类似sealed class的 ADT 定义方式甚至在某些旧版本 Dart 上也能模拟出密封继承的效果第二它提供了一套运行时模式匹配器匹配回调采用“回调表”的写法每个子类型对应一个回调函数第三它配套了一些不可变集合和构造函数工具帮我们减少样板代码。用了一段时间之后团队实际上已经形成了一套“代码组织纪律”领域对象一律用 ADT 建模UI 层和业务层之间的消息传递也用 ADT不允许直接用裸字符串或魔法数字在模块间传状态。这套纪律本身没有问题问题在于它绑定在dartonic这个具体的三方库上。当鸿蒙化任务提上日程后我们才意识到这把“函数式纯粹”的双刃剑另一面是三方库对运行时能力的依赖。那为什么要专门写鸿蒙化而不是直接换个库因为业务代码里已经有大量的dartonic调用点直接抛弃等于重写业务逻辑。我们需要的是一条迁移路径让代码能从dartonic的语义平滑过渡到鸿蒙侧可用的实现同时保住 ADT 治理的收益。2. dartonic 鸿蒙化的摩擦点三个真实拦路虎2.1 运行时反射与代码生成依赖第一个拦路虎是反射。dartonic的部分版本在匹配时依赖运行时类型信息比如通过dart:mirrors展开对象的真实类型或者在编译期用build_runner生成类型标签。鸿蒙侧的 Flutter SDK 并不是官方 Flutter 的完整拷贝我们对齐到社区版本时发现dart:mirrors被裁剪了AOT 编译模式下本身就不可用。dartonic 在标准 Flutter 上能跑是因为 Android 和 iOS 的运行时还留着对应的能力鸿蒙侧这套 Flutter 引擎直接把这个通道给断了。跑起来是什么表现不是编译报错而是运行时崩溃NoSuchMethodError找不到typeMirror之类的调用。这类错误在 Flutter 的 debug 模式还能看到一点堆栈一旦打了 release 包鸿蒙侧往往直接崩溃退出连堆栈都很难捞全。我们后续的结论是能不用反射就别用反射尤其在跨平台 SDK 的适配场景下。反射是隐性的运行时依赖平台裁剪一个能力你的整个逻辑层就要跟着遭殃。2.2 穷尽性检查的编译期通道不同第二个拦路虎是穷尽性检查的通道。dartonic的模式匹配是运行时分发它判断“你覆盖了所有子类型”靠的是运行时断言在匹配器的实现里遍历已知的子类型列表如果某个子类型没有对应回调就抛一个异常。这在普通 Flutter 上问题不大因为 debug 模式会触发断言。但鸿蒙侧我们通常会跑 release 包验证性能而 release 模式下的断言经常被抠掉。结果就是漏了某个分支开发环境从来不会报警线上某个用户走到了那个分支直接闪退。对比之下Dart 3 原生的switch表达式配合sealed class穷尽性是编译期检查的分支漏没漏编译器直接给你报错。把运行时断言升级为编译期检查这是这次适配最大的收益。2.3 序列化与平台通道的不可变破坏第三个拦路虎藏在数据边界。鸿蒙应用里Flutter 层和原生层之间要过平台通道PlatformChannel数据要和鸿蒙侧的应用组件交互。dartonic 定义的 ADT 在 Dart 侧是不可变的但一旦要序列化成 Map 传到鸿蒙侧不可变性就失效了那边是可变对象绕一圈回来字段多一个少一个Dart 侧根本不知道。我们当时排查过一个诡异问题消息推送回调里订单状态对象偶尔会多出一个未知字段导致模式匹配器走到兜底分支。后来定位发现是鸿蒙侧在序列化响应时把一些内部标记混进了 Map。这种在纯 Flutter 环境下不会出现的问题在跨语言边界上成了常态。这也逼着我们做了一件事在 ADT 定义里显式声明序列化白名单而不是让框架自动序列化所有字段。3. 适配策略与其修包不如还权给语言3.1 目标架构UI 层、逻辑层、平台层的三层治理既然 dartenic 在鸿蒙上有这些摩擦点我们的第一个想法是给 dartenic 打补丁改一版鸿蒙专用 fork。但评估下来工作量太大而且鸿蒙侧 Flutter 版本还在快速演进维护一个 fork 会让团队长期背上包袱。后来我们换了个思路借用 Dart 3 的原生模式匹配能力把 dartenic 的语义完整“翻译”过来然后在团队内部沉淀一套统一的 ADT 治理规范。这套规范分三层UI 层只消费 ADT不做状态判断通过模式匹配拿到要渲染的视图模型。逻辑层只依赖 sealed class 和 switch 表达式不引入任何三方匹配库。平台层负责 ADT 与鸿蒙平台通道之间的序列化、反序列化统一走白名单映射。说白了就是把“治理中台”这件事从某个库身上剥离出来变成团队自己的工程规范。dartenic 只是我们认识 ADT 价值的启蒙老师鸿蒙化之后它完成了历史使命可以优雅退场了。3.2 能力映射表dartonic 原语到 Dart 原生语法的对应关系适配之前我们先做了一张能力映射表把 dartenic 提供的每个能力和 Dart 3 原生语法的对应关系列清楚。这张表是整个迁移团队的“导航图”。dartenic 能力Dart 3 / 鸿蒙侧替代方案语义等价性备注密封类继承sealed 模拟sealed class关键字完全等价编译期强制同一文件内继承运行时模式匹配器switch表达式匹配能力等价穷尽性从运行时报错升级为编译期报错子类型回调表switch 的 case 分支写法不同逻辑等价注意回调表的顺序依赖切换成分支匹配守卫条件when子句完全等价例如case Paid(:final id) when id.isNotEmpty字段解构对象模式(:final field)完全等价比 dartenic 的 getter 写法更直观不可变约束final字段 私有构造函数需要手动补dartenic 可能自动生成原生需要约定运行时类型标签compile-time type promotion更优没有运行时开销序列化辅助手工toJson/fromJson需要补样板可配合代码生成但不再依赖 dartenic这张表做完团队的迁移任务就从“分析 dartenic 源码”变成了“按表抄作业”。3.3 分支策略按 SDK 能力选择适配方案你可能会问如果鸿蒙侧的 Flutter SDK 的 Dart 版本还不到 3.0没 sealed 和 switch 表达式怎么办这个问题我们提前探了口风也做了兜底方案。当时我们锁定的鸿蒙侧 Flutter SDK 已经对齐到 Dart 3.x所以主路线是直接上原生语法。但如果你的目标 SDK 更旧兜底方案是用一个抽象基类加一个taggetter 模拟和类型用静态工厂构造函数约束可创建的子类型匹配时先用if (state is Pending)做类型收窄然后用else if链模拟穷尽检查最后在else里抛异常兜底。这套兜底方案能保证语义等价只是失去编译期穷尽性检查开发时必须配合测试覆盖。好在以鸿蒙生态的迭代速度真正停留在 Dart 2 时代的 Flutter 发行版已经不多原生方案大概率能覆盖绝大多数团队。4. 实操把 dartonic 的 ADT 与匹配器改造成鸿蒙可编译代码4.1 ADT 定义迁移从 class matchable 到 sealed class先看迁移前dartenic 风格的 ADT 定义。我们原来的订单状态大概长这样// 迁移前dartonic 风格示意 import package:dartonic/dartonic.dart; ADT() abstract class OrderState {} class Pending extends OrderState with Matchable { final DateTime createdAt; Pending(this.createdAt); } class Paid extends OrderState with Matchable { final String transactionId; Paid(this.transactionId); } class Sent extends OrderState with Matchable { final String logisticsNo; Sent(this.logisticsNo); } class Cancelled extends OrderState with Matchable { final String reason; Cancelled(this.reason); }迁移后用 Dart 3 原生的 sealed class// 迁移后Dart 3 原生 sealed class sealed class OrderState { const OrderState(); // 序列化白名单供平台通道使用 MapString, Object? toJson(); } final class Pending extends OrderState { final DateTime createdAt; const Pending(this.createdAt); override MapString, Object? toJson() {type: Pending, createdAt: createdAt.millisecondsSinceEpoch}; } final class Paid extends OrderState { final String transactionId; const Paid(this.transactionId); override MapString, Object? toJson() {type: Paid, transactionId: transactionId}; } final class Sent extends OrderState { final String logisticsNo; const Sent(this.logisticsNo); override MapString, Object? toJson() {type: Sent, logisticsNo: logisticsNo}; } final class Cancelled extends OrderState { final String reason; const Cancelled(this.reason); override MapString, Object? toJson() {type: Cancelled, reason: reason}; }改动背后有几个关键点。第一sealed class要求所有直接子类必须在同一个文件里定义这看起来是个限制其实恰恰是 ADT 治理想要的你不知道系统的状态有多少但至少要能在同一个文件里数清它们。第二我们故意用final class断掉子类型继续派生的可能保证和类型的封闭性。第三序列化白名单直接放进 ADT 定义每个子类型自己负责自己的 JSON 映射而不是靠一个中心化的序列化器去猜字段。4.2 模式匹配调用点替换从 match 回调表到 switch 表达式这是改动量最大的部分。原来每个 dartenic 匹配点都长这样// 迁移前dartonic match 回调表示意 String orderDesc orderState.match( pending: (Pending p) 待支付创建于 ${p.createdAt}, paid: (Paid p) 已支付交易号 ${p.transactionId}, sent: (Sent s) 已发货物流单号 ${s.logisticsNo}, cancelled: (Cancelled c) 已取消${c.reason}, );迁移后用 switch 表达式// 迁移后Dart 3 switch 表达式 String orderDesc switch (orderState) { Pending(:final createdAt) 待支付创建于 $createdAt, Paid(:final transactionId) 已支付交易号 $transactionId, Sent(:final logisticsNo) 已发货物流单号 $logisticsNo, Cancelled(:final reason) 已取消$reason, };这里有个容易踩坑的地方dartenic 的 match 回调表是运行时遍历已知子类型分发回调之间的顺序不影响结果switch 表达式则是按 case 顺序匹配。如果你原来的回调表里对多个子类型有重叠逻辑迁移时要特别注意顺序。好在 ADT 建模要求子类型互斥正常写顺序无所谓。还有一种是全局兜底。dartenic 时代很多人习惯在最后加一个orElse处理未知类型// 不推荐的迁移写法 String orderDesc switch (orderState) { Pending(:final createdAt) 待支付创建于 $createdAt, Paid(:final transactionId) 已支付交易号 $transactionId, _ 未知状态, };这个_兜底分支会把编译期穷尽性检查彻底干掉跟 ADT 治理的初衷相悖。我们的团队规范是允许default存在但必须显式写// TODO: 处理新增状态并触发 code review。否则不允许使用兜底分支。4.3 守卫条件、递归结构与组合匹配的平移业务代码不可能只有最简单的子类型匹配。我们遇到三种高频进阶用法这里直接给迁移对照。守卫条件dartenic 时代用when回调参数或者自己写if。Dart 3 直接用when子句// 迁移前 orderState.match( paid: (Paid p) p.transactionId.isNotEmpty ? 已支付 : 异常支付, ); // 迁移后 switch (orderState) { case Paid(:final transactionId) when transactionId.isNotEmpty: return 已支付; case Paid(): return 异常支付; }注意when和 case 顺序的配合如果when不满足会继续往下匹配下一条 case这弥补了 dartenic 回调表里难以表达“某个子类型在满足条件时走 A否则走 B”的尴尬。递归结构ADT 经常用来表达树或链表。迁移前后对比如下// 递归 ADT一棵二叉树 sealed class Tree {} final class Leaf extends Tree { final int value; const Leaf(this.value); } final class Node extends Tree { final Tree left; final Tree right; const Node(this.left, this.right); } // 匹配时case 里继续嵌套模式 int sumTree(Tree tree) switch (tree) { Leaf(:final value) value, Node(:final left, :final right) sumTree(left) sumTree(right), };这里完全不需要 dartenic 的递归 match 机制Dart 3 的模式匹配本身支持嵌套编译器还能对嵌套的穷尽性做检查。组合模式有些场景要一次性匹配多个 ADT比如一个聚合里的状态。Dart 的 switch 也支持通过(obj1, obj2)这样的记录类型做组合匹配String describe(OrderState order, PaymentStatus payment) switch ((order, payment)) { (Paid(), PaymentStatus.success) 订单已支付且扣款成功, (Paid(), PaymentStatus.pending) 订单已置为已支付但扣款未确认, (Cancelled(), _) 订单已取消, _ 其他, };组合匹配的兜底分支往往无法避免因为两个 ADT 的笛卡尔积通常远大于真实业务状态。我们团队的约定是遇到这种组合先问自己“这个组合有没有可能违反业务约束”如果不可能说明建模有问题应该新建一个描述业务阶段的 ADT而不是用组合判断硬凑。5. 实战复盘订单状态机从 Flutter 到鸿蒙的完整迁移5.1 案例背景与迁移目标这里用订单状态机做完整复盘。这个模块有 4 个状态节点、6 条合法迁移路径涉及退款、售后、物流三个子域代码规模在 5000 行左右。迁移目标有三条第一解除对 dartenic 的依赖第二在鸿蒙侧 SDK 上编译通过并稳定运行第三保持原有的穷尽性约束打 release 包后不能出现“漏分支但不报错”。5.2 七个迁移步骤全过程第一步依赖隔离。先把pubspec.yaml里对 dartenic 的依赖标记为 deprecated并新增 Dart 3 的原生分析选项。这一步不动业务代码只是为了确认整个工程切换到鸿蒙 SDK 后编译器对这个库的报错范围。# pubspec.yaml 片段 environment: sdk: 3.3.0 4.0.0 dependencies: # dartonic: ^0.6.5 # 准备移除迁移后删除 flutter: sdk: flutter第二步手工盘点调用点。用脚本把所有match调用点列出来按模块分组排序。我们当时列出来 127 个调用点分布在订单、售后、库存三个 feature 里。这里建议不要用全局自动替换因为 dartenic 的回调参数和 switch case 的变量作用域差异很大自动替换容易改错。第三步ADT 定义层整体替换。先把所有业务 ADT 迁移到 sealed class同时补final、补私有构造函数、补toJson。这一步改完整个工程会大面积编译报错因为原有的 match 调用点还没动。不用慌报错反而能帮我们定位所有依赖旧 ADT 定义的地方。第四步匹配调用点逐个替换。拿第 4 章的例子把每个match改成 switch 表达式。这一步最费时间但也是行政价值最高的步骤替换过程中能发现不少“原来覆盖了但逻辑根本没用到”的死分支顺手清理掉。第五步处理序列化边界。在鸿蒙平台通道的入口处加白名单校验。每一个从鸿蒙侧进入 Flutter 的 Map先按 ADT 的fromJson结构检查字段多出来的字段直接丢弃并打日志而不是带进 Dart 层。第六步跑全量单测。我们特意在测试里加了一个“穷尽性巡检”用例遍历所有 ADT 子类型在 switch 表达式上做一次全量匹配断言。即使编译器已经保证了穷尽性这个用例也能确保后续新增子类型时团队不会绕过规范硬加default。第七步鸿蒙真机验证。分别在 debug、profile、release 三种模式下跑完整业务流程重点观察之前反射崩溃的路径是否还会触发。5.3 验证结果与性能对比迁移完成后我们做了一组对比。这里的数字是我们工程内测的基线不同项目会有差异但趋势基本一致。指标dartenic 版本Flutter鸿蒙原生适配版说明运行时反射调用有无崩溃风险点消除漏分支检测debug 断言编译期报错AOT/release 下依旧有效订单状态匹配耗时万次约 18ms约 3msswitch 走编译期分派无运行时查表依赖数量dartenic build_runner 等0少一层间接依赖编译产物体积基线减少约 9%剥离运行时匹配器与生成代码最直观的体感是 release 包稳了。之前偶发的“某个状态没人覆盖导致闪退”问题在迁移后的一次迭代里直接被编译器拦住了新同事加了一个Reviewing状态顺手在所有 switch 分支里都补了 case但漏了某一个编译器当场报错而不是等用户点进售后页才炸。6. 沉淀与工程治理鸿蒙侧的 ADT 代码规范6.1 团队内部约定什么场景必须用 sealed class迁移之后我们把“必须用 ADT”的场景写成了一条硬性规范网络请求的返回状态成功、失败、超时、未授权必须建模为 sealed class。模块间的页面跳转意图必须建模为 sealed class不允许用字符串路由名裸传。多状态实体的生命周期订单、任务、工单必须是 sealed class 加 switch 表达式处理。禁止在 ADT 匹配点使用_兜底分支除非有显式注释和 review 记录。这些规范不是新发明的其实就是 dartenic 当初教我们的那一套只不过现在完全绑定在语言原生机制上不需要额外依赖了。6.2 CI 检查与 FastLane 脚本为了让规范可执行我们写了个简单的 CI 脚本。逻辑很简单把工程里所有 ADT 相关目录约定为lib/core/adt和lib/features/*/domain扫一遍禁止出现switch表达式里的_分支禁止 ADT 定义出现class而不是final class的派生。#!/bin/bash # 检查 ATD 匹配点是否使用了兜底分支 # 在 CI 中运行发现 case _ 直接失败 mapfile -t files (grep -rln sealed class lib/ --include*.dart) for file in ${files[]}; do if grep -n case _ $file /dev/null; then echo ERROR: $file 中存在未穷尽的兜底分支 exit 1 fi done echo ADT 检查通过这个方法很粗暴但足够有效。真正想绕过的同事总有办法但至少它把“无意间引入兜底分支”的概率降到最低。6.3 平台通道序列化的配套方案最后单独说下鸿蒙平台通道的序列化配套。Flutter 和鸿蒙侧交互时ADT 不直接跨语言而是转成标准 Map。我们约定每个 ADT 的toJson里必须包含一个type字段fromJson时严格按type白名单反序列化遇到未注册的type直接抛异常而不是返回一个空对象。static OrderState fromJson(MapString, Object? json) { return switch (json[type]) { Pending Pending(DateTime.fromMillisecondsSinceEpoch(json[createdAt] as int)), Paid Paid(json[transactionId] as String), Sent Sent(json[logisticsNo] as String), Cancelled Cancelled(json[reason] as String), final String type throw ArgumentError(未知的 OrderState 类型: $type), }; }这个fromJson里的final String type 不是兜底分支而是安全网它只处理“JSON 非法”的场景而不是接纳新增状态。二者有本质区别——前者保护运行时数据边界后者逃避编译期检查。我个人在整个迁移里最大的体会是适配三方库的价值不在于把库本身伺候得多好而在于借适配的机会重新审视它当初想解决的问题。dartenic 在标准 Flutter 里帮我们把逻辑拽回了函数式的轨道鸿蒙化只是换了一个更强大的“引擎”继续跑同一套理念。如果非要给后来者一条建议迁移前先做能力映射表迁移中坚持“先类后调用点”的顺序迁移后别急着删旧代码留一个版本观察期确认线上没有异常再剪掉脏依赖。这套打法我们后来用在其他几个三方库比如不可变集合、代码生成器的鸿蒙化上同样有效。
把一套重度使用三方库dartonic的 Flutter 工程往鸿蒙上迁移时最先翻车的地方往往不在页面也不在状态管理而是那些依赖运行时反射和代码生成的三方逻辑库。dartonic这种主打模式匹配与 ADT代数数据类型的库恰好就踩在这个点上。这篇文章讲的是我们团队怎么把它“鸿蒙化”的不是硬着头皮去改它的源码也不是用一堆if/else把逻辑重新糊一遍而是借鸿蒙侧 Flutter SDK 的现代化 Dart 能力把模式匹配和 ADT 治理沉淀成一套可复用的中台方案。如果你也在做 Flutter 应用向鸿蒙迁移或者正在为团队的业务逻辑越来越难维护而头疼这篇适配指南应该能给你一条可落地的路径。先说清楚我们说的“ADT”是什么。ADT 是 Algebraic Data Type 的缩写翻译过来是代数数据类型核心就两种积类型比如一个数据类同时有多个字段和和类型一个数在多个互斥的子类型中取其一。Dart 里的sealed class加上final class其实就是在表达和类型。而 ADT 治理指的是用这种类型建模业务状态、约束非法组合、通过模式匹配把分支逻辑收敛到一处。dartonic这个三方库干的正是这件事它提供了类似 Scala 或 Haskell 风格的模式匹配器配合不可变数据类让业务逻辑保持“函数式纯粹”。听起来很美好但到了鸿蒙上问题就来了。1. 为什么鸿蒙应用需要 ADT 治理中台1.1 业务逻辑失控的根源if/else 泥潭我先讲一个真实的场景。我们团队之前维护一个电商 App 的 Flutter 版本订单模块的状态既有待支付、已支付、待发货、已发货、已取消还有售后中的各种子状态。这些状态本来应该是一个封闭的集合——在某一时刻订单只会处于其中一种状态。但代码里怎么写的散落各处的if (order.status 1)、if (order.status ! 4 order.canRefund)十几处地方各判断各的没人能说清楚到底有多少种组合是合法的。这种代码的问题在于状态的可视性被稀释了。单个字段的取值看起来无害但状态和状态之间的关联、状态和操作之间的约束全都被埋在命令式代码里。后来我们接入了dartonic把订单状态建模成一棵密封的继承树每个子类型自带不可变字段所有分支逻辑收敛到模式匹配器里。效果立竿见影新增一种状态编译器会提醒你哪些匹配点没覆盖非法状态组合在建模阶段就被类型系统挡住了。这就是 ADT 治理要解决的核心问题让业务状态可枚举、可穷尽、不可篡改。它不改变业务本身而是把“哪些情况是合法的”这件事从运行时错误变成了编译期约束。1.2 dartonic 在 Flutter 侧承担的职责dartonic这个库在我们工程里承担了三件事。第一它提供了类似sealed class的 ADT 定义方式甚至在某些旧版本 Dart 上也能模拟出密封继承的效果第二它提供了一套运行时模式匹配器匹配回调采用“回调表”的写法每个子类型对应一个回调函数第三它配套了一些不可变集合和构造函数工具帮我们减少样板代码。用了一段时间之后团队实际上已经形成了一套“代码组织纪律”领域对象一律用 ADT 建模UI 层和业务层之间的消息传递也用 ADT不允许直接用裸字符串或魔法数字在模块间传状态。这套纪律本身没有问题问题在于它绑定在dartonic这个具体的三方库上。当鸿蒙化任务提上日程后我们才意识到这把“函数式纯粹”的双刃剑另一面是三方库对运行时能力的依赖。那为什么要专门写鸿蒙化而不是直接换个库因为业务代码里已经有大量的dartonic调用点直接抛弃等于重写业务逻辑。我们需要的是一条迁移路径让代码能从dartonic的语义平滑过渡到鸿蒙侧可用的实现同时保住 ADT 治理的收益。2. dartonic 鸿蒙化的摩擦点三个真实拦路虎2.1 运行时反射与代码生成依赖第一个拦路虎是反射。dartonic的部分版本在匹配时依赖运行时类型信息比如通过dart:mirrors展开对象的真实类型或者在编译期用build_runner生成类型标签。鸿蒙侧的 Flutter SDK 并不是官方 Flutter 的完整拷贝我们对齐到社区版本时发现dart:mirrors被裁剪了AOT 编译模式下本身就不可用。dartonic 在标准 Flutter 上能跑是因为 Android 和 iOS 的运行时还留着对应的能力鸿蒙侧这套 Flutter 引擎直接把这个通道给断了。跑起来是什么表现不是编译报错而是运行时崩溃NoSuchMethodError找不到typeMirror之类的调用。这类错误在 Flutter 的 debug 模式还能看到一点堆栈一旦打了 release 包鸿蒙侧往往直接崩溃退出连堆栈都很难捞全。我们后续的结论是能不用反射就别用反射尤其在跨平台 SDK 的适配场景下。反射是隐性的运行时依赖平台裁剪一个能力你的整个逻辑层就要跟着遭殃。2.2 穷尽性检查的编译期通道不同第二个拦路虎是穷尽性检查的通道。dartonic的模式匹配是运行时分发它判断“你覆盖了所有子类型”靠的是运行时断言在匹配器的实现里遍历已知的子类型列表如果某个子类型没有对应回调就抛一个异常。这在普通 Flutter 上问题不大因为 debug 模式会触发断言。但鸿蒙侧我们通常会跑 release 包验证性能而 release 模式下的断言经常被抠掉。结果就是漏了某个分支开发环境从来不会报警线上某个用户走到了那个分支直接闪退。对比之下Dart 3 原生的switch表达式配合sealed class穷尽性是编译期检查的分支漏没漏编译器直接给你报错。把运行时断言升级为编译期检查这是这次适配最大的收益。2.3 序列化与平台通道的不可变破坏第三个拦路虎藏在数据边界。鸿蒙应用里Flutter 层和原生层之间要过平台通道PlatformChannel数据要和鸿蒙侧的应用组件交互。dartonic 定义的 ADT 在 Dart 侧是不可变的但一旦要序列化成 Map 传到鸿蒙侧不可变性就失效了那边是可变对象绕一圈回来字段多一个少一个Dart 侧根本不知道。我们当时排查过一个诡异问题消息推送回调里订单状态对象偶尔会多出一个未知字段导致模式匹配器走到兜底分支。后来定位发现是鸿蒙侧在序列化响应时把一些内部标记混进了 Map。这种在纯 Flutter 环境下不会出现的问题在跨语言边界上成了常态。这也逼着我们做了一件事在 ADT 定义里显式声明序列化白名单而不是让框架自动序列化所有字段。3. 适配策略与其修包不如还权给语言3.1 目标架构UI 层、逻辑层、平台层的三层治理既然 dartenic 在鸿蒙上有这些摩擦点我们的第一个想法是给 dartenic 打补丁改一版鸿蒙专用 fork。但评估下来工作量太大而且鸿蒙侧 Flutter 版本还在快速演进维护一个 fork 会让团队长期背上包袱。后来我们换了个思路借用 Dart 3 的原生模式匹配能力把 dartenic 的语义完整“翻译”过来然后在团队内部沉淀一套统一的 ADT 治理规范。这套规范分三层UI 层只消费 ADT不做状态判断通过模式匹配拿到要渲染的视图模型。逻辑层只依赖 sealed class 和 switch 表达式不引入任何三方匹配库。平台层负责 ADT 与鸿蒙平台通道之间的序列化、反序列化统一走白名单映射。说白了就是把“治理中台”这件事从某个库身上剥离出来变成团队自己的工程规范。dartenic 只是我们认识 ADT 价值的启蒙老师鸿蒙化之后它完成了历史使命可以优雅退场了。3.2 能力映射表dartonic 原语到 Dart 原生语法的对应关系适配之前我们先做了一张能力映射表把 dartenic 提供的每个能力和 Dart 3 原生语法的对应关系列清楚。这张表是整个迁移团队的“导航图”。dartenic 能力Dart 3 / 鸿蒙侧替代方案语义等价性备注密封类继承sealed 模拟sealed class关键字完全等价编译期强制同一文件内继承运行时模式匹配器switch表达式匹配能力等价穷尽性从运行时报错升级为编译期报错子类型回调表switch 的 case 分支写法不同逻辑等价注意回调表的顺序依赖切换成分支匹配守卫条件when子句完全等价例如case Paid(:final id) when id.isNotEmpty字段解构对象模式(:final field)完全等价比 dartenic 的 getter 写法更直观不可变约束final字段 私有构造函数需要手动补dartenic 可能自动生成原生需要约定运行时类型标签compile-time type promotion更优没有运行时开销序列化辅助手工toJson/fromJson需要补样板可配合代码生成但不再依赖 dartenic这张表做完团队的迁移任务就从“分析 dartenic 源码”变成了“按表抄作业”。3.3 分支策略按 SDK 能力选择适配方案你可能会问如果鸿蒙侧的 Flutter SDK 的 Dart 版本还不到 3.0没 sealed 和 switch 表达式怎么办这个问题我们提前探了口风也做了兜底方案。当时我们锁定的鸿蒙侧 Flutter SDK 已经对齐到 Dart 3.x所以主路线是直接上原生语法。但如果你的目标 SDK 更旧兜底方案是用一个抽象基类加一个taggetter 模拟和类型用静态工厂构造函数约束可创建的子类型匹配时先用if (state is Pending)做类型收窄然后用else if链模拟穷尽检查最后在else里抛异常兜底。这套兜底方案能保证语义等价只是失去编译期穷尽性检查开发时必须配合测试覆盖。好在以鸿蒙生态的迭代速度真正停留在 Dart 2 时代的 Flutter 发行版已经不多原生方案大概率能覆盖绝大多数团队。4. 实操把 dartonic 的 ADT 与匹配器改造成鸿蒙可编译代码4.1 ADT 定义迁移从 class matchable 到 sealed class先看迁移前dartenic 风格的 ADT 定义。我们原来的订单状态大概长这样// 迁移前dartonic 风格示意 import package:dartonic/dartonic.dart; ADT() abstract class OrderState {} class Pending extends OrderState with Matchable { final DateTime createdAt; Pending(this.createdAt); } class Paid extends OrderState with Matchable { final String transactionId; Paid(this.transactionId); } class Sent extends OrderState with Matchable { final String logisticsNo; Sent(this.logisticsNo); } class Cancelled extends OrderState with Matchable { final String reason; Cancelled(this.reason); }迁移后用 Dart 3 原生的 sealed class// 迁移后Dart 3 原生 sealed class sealed class OrderState { const OrderState(); // 序列化白名单供平台通道使用 MapString, Object? toJson(); } final class Pending extends OrderState { final DateTime createdAt; const Pending(this.createdAt); override MapString, Object? toJson() {type: Pending, createdAt: createdAt.millisecondsSinceEpoch}; } final class Paid extends OrderState { final String transactionId; const Paid(this.transactionId); override MapString, Object? toJson() {type: Paid, transactionId: transactionId}; } final class Sent extends OrderState { final String logisticsNo; const Sent(this.logisticsNo); override MapString, Object? toJson() {type: Sent, logisticsNo: logisticsNo}; } final class Cancelled extends OrderState { final String reason; const Cancelled(this.reason); override MapString, Object? toJson() {type: Cancelled, reason: reason}; }改动背后有几个关键点。第一sealed class要求所有直接子类必须在同一个文件里定义这看起来是个限制其实恰恰是 ADT 治理想要的你不知道系统的状态有多少但至少要能在同一个文件里数清它们。第二我们故意用final class断掉子类型继续派生的可能保证和类型的封闭性。第三序列化白名单直接放进 ADT 定义每个子类型自己负责自己的 JSON 映射而不是靠一个中心化的序列化器去猜字段。4.2 模式匹配调用点替换从 match 回调表到 switch 表达式这是改动量最大的部分。原来每个 dartenic 匹配点都长这样// 迁移前dartonic match 回调表示意 String orderDesc orderState.match( pending: (Pending p) 待支付创建于 ${p.createdAt}, paid: (Paid p) 已支付交易号 ${p.transactionId}, sent: (Sent s) 已发货物流单号 ${s.logisticsNo}, cancelled: (Cancelled c) 已取消${c.reason}, );迁移后用 switch 表达式// 迁移后Dart 3 switch 表达式 String orderDesc switch (orderState) { Pending(:final createdAt) 待支付创建于 $createdAt, Paid(:final transactionId) 已支付交易号 $transactionId, Sent(:final logisticsNo) 已发货物流单号 $logisticsNo, Cancelled(:final reason) 已取消$reason, };这里有个容易踩坑的地方dartenic 的 match 回调表是运行时遍历已知子类型分发回调之间的顺序不影响结果switch 表达式则是按 case 顺序匹配。如果你原来的回调表里对多个子类型有重叠逻辑迁移时要特别注意顺序。好在 ADT 建模要求子类型互斥正常写顺序无所谓。还有一种是全局兜底。dartenic 时代很多人习惯在最后加一个orElse处理未知类型// 不推荐的迁移写法 String orderDesc switch (orderState) { Pending(:final createdAt) 待支付创建于 $createdAt, Paid(:final transactionId) 已支付交易号 $transactionId, _ 未知状态, };这个_兜底分支会把编译期穷尽性检查彻底干掉跟 ADT 治理的初衷相悖。我们的团队规范是允许default存在但必须显式写// TODO: 处理新增状态并触发 code review。否则不允许使用兜底分支。4.3 守卫条件、递归结构与组合匹配的平移业务代码不可能只有最简单的子类型匹配。我们遇到三种高频进阶用法这里直接给迁移对照。守卫条件dartenic 时代用when回调参数或者自己写if。Dart 3 直接用when子句// 迁移前 orderState.match( paid: (Paid p) p.transactionId.isNotEmpty ? 已支付 : 异常支付, ); // 迁移后 switch (orderState) { case Paid(:final transactionId) when transactionId.isNotEmpty: return 已支付; case Paid(): return 异常支付; }注意when和 case 顺序的配合如果when不满足会继续往下匹配下一条 case这弥补了 dartenic 回调表里难以表达“某个子类型在满足条件时走 A否则走 B”的尴尬。递归结构ADT 经常用来表达树或链表。迁移前后对比如下// 递归 ADT一棵二叉树 sealed class Tree {} final class Leaf extends Tree { final int value; const Leaf(this.value); } final class Node extends Tree { final Tree left; final Tree right; const Node(this.left, this.right); } // 匹配时case 里继续嵌套模式 int sumTree(Tree tree) switch (tree) { Leaf(:final value) value, Node(:final left, :final right) sumTree(left) sumTree(right), };这里完全不需要 dartenic 的递归 match 机制Dart 3 的模式匹配本身支持嵌套编译器还能对嵌套的穷尽性做检查。组合模式有些场景要一次性匹配多个 ADT比如一个聚合里的状态。Dart 的 switch 也支持通过(obj1, obj2)这样的记录类型做组合匹配String describe(OrderState order, PaymentStatus payment) switch ((order, payment)) { (Paid(), PaymentStatus.success) 订单已支付且扣款成功, (Paid(), PaymentStatus.pending) 订单已置为已支付但扣款未确认, (Cancelled(), _) 订单已取消, _ 其他, };组合匹配的兜底分支往往无法避免因为两个 ADT 的笛卡尔积通常远大于真实业务状态。我们团队的约定是遇到这种组合先问自己“这个组合有没有可能违反业务约束”如果不可能说明建模有问题应该新建一个描述业务阶段的 ADT而不是用组合判断硬凑。5. 实战复盘订单状态机从 Flutter 到鸿蒙的完整迁移5.1 案例背景与迁移目标这里用订单状态机做完整复盘。这个模块有 4 个状态节点、6 条合法迁移路径涉及退款、售后、物流三个子域代码规模在 5000 行左右。迁移目标有三条第一解除对 dartenic 的依赖第二在鸿蒙侧 SDK 上编译通过并稳定运行第三保持原有的穷尽性约束打 release 包后不能出现“漏分支但不报错”。5.2 七个迁移步骤全过程第一步依赖隔离。先把pubspec.yaml里对 dartenic 的依赖标记为 deprecated并新增 Dart 3 的原生分析选项。这一步不动业务代码只是为了确认整个工程切换到鸿蒙 SDK 后编译器对这个库的报错范围。# pubspec.yaml 片段 environment: sdk: 3.3.0 4.0.0 dependencies: # dartonic: ^0.6.5 # 准备移除迁移后删除 flutter: sdk: flutter第二步手工盘点调用点。用脚本把所有match调用点列出来按模块分组排序。我们当时列出来 127 个调用点分布在订单、售后、库存三个 feature 里。这里建议不要用全局自动替换因为 dartenic 的回调参数和 switch case 的变量作用域差异很大自动替换容易改错。第三步ADT 定义层整体替换。先把所有业务 ADT 迁移到 sealed class同时补final、补私有构造函数、补toJson。这一步改完整个工程会大面积编译报错因为原有的 match 调用点还没动。不用慌报错反而能帮我们定位所有依赖旧 ADT 定义的地方。第四步匹配调用点逐个替换。拿第 4 章的例子把每个match改成 switch 表达式。这一步最费时间但也是行政价值最高的步骤替换过程中能发现不少“原来覆盖了但逻辑根本没用到”的死分支顺手清理掉。第五步处理序列化边界。在鸿蒙平台通道的入口处加白名单校验。每一个从鸿蒙侧进入 Flutter 的 Map先按 ADT 的fromJson结构检查字段多出来的字段直接丢弃并打日志而不是带进 Dart 层。第六步跑全量单测。我们特意在测试里加了一个“穷尽性巡检”用例遍历所有 ADT 子类型在 switch 表达式上做一次全量匹配断言。即使编译器已经保证了穷尽性这个用例也能确保后续新增子类型时团队不会绕过规范硬加default。第七步鸿蒙真机验证。分别在 debug、profile、release 三种模式下跑完整业务流程重点观察之前反射崩溃的路径是否还会触发。5.3 验证结果与性能对比迁移完成后我们做了一组对比。这里的数字是我们工程内测的基线不同项目会有差异但趋势基本一致。指标dartenic 版本Flutter鸿蒙原生适配版说明运行时反射调用有无崩溃风险点消除漏分支检测debug 断言编译期报错AOT/release 下依旧有效订单状态匹配耗时万次约 18ms约 3msswitch 走编译期分派无运行时查表依赖数量dartenic build_runner 等0少一层间接依赖编译产物体积基线减少约 9%剥离运行时匹配器与生成代码最直观的体感是 release 包稳了。之前偶发的“某个状态没人覆盖导致闪退”问题在迁移后的一次迭代里直接被编译器拦住了新同事加了一个Reviewing状态顺手在所有 switch 分支里都补了 case但漏了某一个编译器当场报错而不是等用户点进售后页才炸。6. 沉淀与工程治理鸿蒙侧的 ADT 代码规范6.1 团队内部约定什么场景必须用 sealed class迁移之后我们把“必须用 ADT”的场景写成了一条硬性规范网络请求的返回状态成功、失败、超时、未授权必须建模为 sealed class。模块间的页面跳转意图必须建模为 sealed class不允许用字符串路由名裸传。多状态实体的生命周期订单、任务、工单必须是 sealed class 加 switch 表达式处理。禁止在 ADT 匹配点使用_兜底分支除非有显式注释和 review 记录。这些规范不是新发明的其实就是 dartenic 当初教我们的那一套只不过现在完全绑定在语言原生机制上不需要额外依赖了。6.2 CI 检查与 FastLane 脚本为了让规范可执行我们写了个简单的 CI 脚本。逻辑很简单把工程里所有 ADT 相关目录约定为lib/core/adt和lib/features/*/domain扫一遍禁止出现switch表达式里的_分支禁止 ADT 定义出现class而不是final class的派生。#!/bin/bash # 检查 ATD 匹配点是否使用了兜底分支 # 在 CI 中运行发现 case _ 直接失败 mapfile -t files (grep -rln sealed class lib/ --include*.dart) for file in ${files[]}; do if grep -n case _ $file /dev/null; then echo ERROR: $file 中存在未穷尽的兜底分支 exit 1 fi done echo ADT 检查通过这个方法很粗暴但足够有效。真正想绕过的同事总有办法但至少它把“无意间引入兜底分支”的概率降到最低。6.3 平台通道序列化的配套方案最后单独说下鸿蒙平台通道的序列化配套。Flutter 和鸿蒙侧交互时ADT 不直接跨语言而是转成标准 Map。我们约定每个 ADT 的toJson里必须包含一个type字段fromJson时严格按type白名单反序列化遇到未注册的type直接抛异常而不是返回一个空对象。static OrderState fromJson(MapString, Object? json) { return switch (json[type]) { Pending Pending(DateTime.fromMillisecondsSinceEpoch(json[createdAt] as int)), Paid Paid(json[transactionId] as String), Sent Sent(json[logisticsNo] as String), Cancelled Cancelled(json[reason] as String), final String type throw ArgumentError(未知的 OrderState 类型: $type), }; }这个fromJson里的final String type 不是兜底分支而是安全网它只处理“JSON 非法”的场景而不是接纳新增状态。二者有本质区别——前者保护运行时数据边界后者逃避编译期检查。我个人在整个迁移里最大的体会是适配三方库的价值不在于把库本身伺候得多好而在于借适配的机会重新审视它当初想解决的问题。dartenic 在标准 Flutter 里帮我们把逻辑拽回了函数式的轨道鸿蒙化只是换了一个更强大的“引擎”继续跑同一套理念。如果非要给后来者一条建议迁移前先做能力映射表迁移中坚持“先类后调用点”的顺序迁移后别急着删旧代码留一个版本观察期确认线上没有异常再剪掉脏依赖。这套打法我们后来用在其他几个三方库比如不可变集合、代码生成器的鸿蒙化上同样有效。
