Flutter鸿蒙跨端开发：JSON工具核心实现与工程实践

前阵子我在处理后台日志时，反复要做同一件事：把一段压缩成一行的 JSON 格式化、核对结构、提取某个字段。在电脑上靠编辑器插件还能忍，到了手机上就特别别扭。正好手头有一台鸿蒙平板，我就决定把这个自建 JSON 解析工具 App 用 Flutter 移植到 HarmonyOS 6 上。整个过程踩了不少坑，也把 JSON 工具该有的几个能力重新梳理了一遍。这篇博文会从环境搭建讲到数据层架构，再讲到格式化、校验、字段提取这些核心功能的实现，最后是真机调试和打包的注意事项，希望能给同样在做 Flutter + HarmonyOS 方向的开发者一些参考。

1. 为什么这个 JSON 工具值得做成 Flutter + HarmonyOS 的 App

1.1 一个从"自己复制粘贴到手软"开始的真实需求

很多人低估了一个 JSON 格式化工具的价值，觉得浏览器里随便开个网页就行。但在实际开发中，我经常要处理的是后端接口返回的"一行式 JSON"——几百上千个字符挤在一起，键值对看不清、嵌套层级找不到，最要命的是一旦里面混入了异常数据，肉眼根本定位不出来。

更麻烦的是场景。很多时候我是在外面、在地铁上、在客户现场看日志，电脑不在手边。手机上用网页工具也不是不行，但要联网、要忍受广告，更重要的是数据要从手里过一遍第三方服务器，这在处理公司接口日志时是明显不能接受的。我需要的工具其实很朴素：完全离线运行、支持格式化、能告诉我哪一行语法错了、还能按路径快速取字段，打开就能用，不卡不弹广告。

于是这个 App 的定位就定了：一个本地优先的 JSON 解析工具，数据不出设备，核心能力就是格式化、校验、字段提取，再加一个文件读取和剪贴板交互。

1.2 为什么选 Flutter 而不是 ArkTS 或 Web 套壳

拿到鸿蒙设备后，第一反应是先看原生方案。HarmonyOS 上最正统的思路是用 ArkTS 写一个原子化服务或应用，这条路本身没有问题，Ark 语言的声明式 UI 用得顺手的话开发效率也不低。但对我这个项目来说有个现实问题：我后续会在 Android 和 iOS 上也需要同样一个工具。如果只在 ArkTS 里写一遍，等于之后要重写两遍；如果选 Flutter，核心解析逻辑、界面结构、状态管理都能复用，鸿蒙只是打包目标之一。

有人会问，Web 套壳不是更省事吗？把网页包进 WebView 就能跑。这个方案我实际试过，做工具类 App 有两个硬伤：一是文件读取、剪贴板、系统分享这些系统能力的体验依赖桥接层，做起来并不比原生少；二是冷启动速度和页面切换流畅度，跟 Flutter 编译出来的原生代码还是有差距。作为一个高频使用的开发工具，响应速度本身就是核心体验。

Flutter 在鸿蒙上的现状是：虽然官方主干对 OpenHarmony 的适配还在推进，但社区分支已经可以把 Flutter 工程跑到鸿蒙设备上，DevEco Studio 负责底层构建，Flutter 层负责 UI 和业务逻辑。我实际跑下来的感受是，常规的 dart:convert、async、File IO 这些能力都没问题，社区常用插件也有对应兼容版本。到现在这个工具在我平板上稳定跑了快两个月，没出现过明显兼容性问题。

1.3 这个项目适合谁跟练

如果你属于下面三类人，这篇内容会比较有参考价值：第一类是已经在做 Flutter、手里有鸿蒙设备、想试试跨端落地的开发者；第二类是准备用鸿蒙版 Flutter 开发小工具类 App 的人，可以照着我这个项目结构去做功能规划；第三类是对 JSON 解析细节感兴趣，特别是想搞清楚 jsonDecode 之外还需不需要做更多设计的人。

不管你是只想要一个能用的 JSON 工具，还是想学 Flutter + HarmonyOS 的工程化链路，这篇文章都会按实际开发顺序来讲，不是那种只讲思路不给代码的泛泛而谈。

2. 工程接入：Flutter 连上鸿蒙构建链路的那些坑

2.1 工具链组合与基本环境准备

先把我的工具链组合列出来，方便对照：

环境准备阶段最容易踩的第一个坑是 Flutter SDK 的版本。不要随便从官网拉一个最新稳定版就跑，鸿蒙适配分支的版本号和官方不是完全同步的。我一开始用官方分支跑，果不其然 flutter build hap 这个命令根本不认识。换成社区适配分支之后，还需要在 flutter doctor 里检查一下有没有识别到鸿蒙开发环境。

然后是你本机的镜像配置。为了下载依赖更快更稳，建议把 PUB_HOSTED_URL 和 FLUTTER_STORAGE_BASE_URL 这两个环境变量指向国内可用的镜像源。这一步不是可选项，至少在我所处的网络环境下，不配置的话下载 Dart 包和 Flutter 引擎产物会非常折磨，而且经常卡到中断。配置完之后，flutter doctor 会显示通过，说明依赖下载路径已经通了。

DevEco Studio 这边，安装后要打开 SDK Manager 确认 HarmonyOS SDK 组件已经下载完整。很多人在这里会漏掉 Native 相关组件，导致后面编译时报找不到 SDK 的奇葩错误。

2.2 Gradle 插件管理的兼容性坑

工程搭建后半段，我遇到了这篇项目里最想吐槽的一个问题：Gradle 插件依赖冲突。这个报错在开发者社区里也很常见，大致意思是说你正在用命令式 apply 的方式引入 Flutter 主插件，但项目配置里又走了声明式 plugins DSL，两边打架了。我那次实际看到的报错长这样：

text复制you are applying flutter's main gradle plugin imperatively using the apply script method, which is not supported

这个问题的根源是 Flutter 鸿蒙分支对 Gradle 插件加载方式做了调整。老项目里常见的写法是：

gradle复制apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle"

在鸿蒙分支的构建链路上，这段逻辑被要求改成 plugins DSL 方式，也就是说要在 settings.gradle 里通过 id 'dev.flutter.flutter-plugin-loader' 先声明插件，再在各模块里引用。直接写 apply from 就会触发上面的报错。

解决办法，一是检查你新建工程时模板是不是最新的，如果是从旧工程迁移，一定要把插件声明方式统一改成 DSL；二是检查 dev.flutter.flutter-plugin-loader 的版本号跟 Flutter 分支是否匹配，版本不一致会出现依赖解析失败，报错信息通常是一大段 Gradle 依赖树，几百行里藏着真正的冲突项。

如果你的工程里还有其他原生插件，也要一并检查它们的 Gradle 配置。我遇到过一个第三方插件还在用老式 apply 方式，最后只能在插件源码里手动把它改成 DSL 才能继续。所以一个建议是：插件尽量选维护活跃的，导入前先看一眼它的 android/build.gradle 用了哪种方式。

2.3 跑通第一个 Demo 页面的过程

环境问题解决之后，第一次把空 Flutter 页面跑到鸿蒙设备上，那种顺畅的体验还是让我挺惊喜的。这里分享下我的检查顺序：先用 flutter doctor 确认环境，然后 flutter create demo_app 新建工程，再用 flutter devices 看鸿蒙设备是否被识别为可用目标。如果设备出现在列表里，直接 flutter run，DevEco Studio 会在后台完成 HAP 构建，首次构建会比较慢，经常需要拉取原生依赖，几分钟到十几分钟不等，属于正常现象。

第一次跑通之后，我建议立刻做一次最小化改动验证：在脚手架的计数器页面里加一行中文文本，改个颜色，确认热重载在鸿蒙目标上能用。因为 Flutter 跨端开发一半的效率在热重载上，如果这一步有问题，后面写界面会非常痛苦。我实测下来，鸿蒙设备上的热重载整体可用，偶尔碰到改原生插件类情况会要求全量重启，这个跟 Android 上的体验基本一致。

到这里，工程链路已经跑通了，接下来就是 JSON 工具本身的设计。

3. 数据层设计：不该把 jsonDecode 的返回值直接丢给界面

3.1 你看到的 jsonDecode 只是第一步

很多 Flutter 新手做 JSON 解析，上来就是一个 jsonDecode，拿到 Map 之后直接当成全局变量到处用，功能是能跑的，但项目一旦变大就会出问题。Dart 的 dart:convert 提供的 jsonDecode 本质上是一个把字符串变成 dynamic 对象的方法，结果是 Map<String, dynamic>、List<dynamic>、数字、字符串还是 null，完全取决于 JSON 里的内容，编译器帮你做不了任何检查。

对 JSON 工具这类 App 来说，危险点在于你解析的数据是不可信的输入。用户可能粘贴一个有语法错误的字符串、一段数组、一个裸字符串，甚至一个巨大的文件。如果数据层不做封装，界面上就要到处写 as Map<String, dynamic>，一旦类型不对，就直接崩给用户看。

我当时给自己的设计原则是：JSON 工具应该分两层。底层是通用解析内核，专门处理"任意合法 JSON 文本"的读取、校验、格式化和字段遍历；上层才是针对具体业务模型的强类型解析。前者面向人来服务，后者面向代码来服务。

3.2 用泛型 Parser 封装模型转换逻辑

在做一个需要把 JSON 转成强类型模型的业务模块时，我写了这样一个通用基类：

dart复制typedef ItemBuilder<T> = T Function(Map<String, dynamic> json);

class JsonModelParser<T> {
  JsonModelParser(this.fromJson);

  final ItemBuilder<T> fromJson;

  T parseObject(String text) {
    final decoded = jsonDecode(text);
    if (decoded is! Map<String, dynamic>) {
      throw const FormatException('JSON 顶层必须是对象');
    }
    return fromJson(decoded);
  }

  List<T> parseArray(String text) {
    final decoded = jsonDecode(text);
    if (decoded is! List<dynamic>) {
      throw const FormatException('JSON 顶层必须是数组');
    }
    return decoded
        .whereType<Map<String, dynamic>>()
        .map(fromJson)
        .toList();
  }
}

这里有一个 Dart 开发者容易忽略的细节：泛型 T 在运行时是会被擦除的，你没办法在方法内部通过 T 的类型去做自动转换，所以必须由调用方把 fromJson 构造函数传进来。这个设计是用空间换安全，换来的是调用方代码非常清晰：

dart复制final parser = JsonModelParser<User>((json) {
  return User(id: json['id'] as String, name: json['name'] as String);
});
final user = parser.parseObject(text);

如果 JSON 结构变了，报错会被收敛到 fromJson 这一行，而不是散落在业务代码的各个解引用点。这是我在重构多个项目之后体会很深的一点：JSON 数据入口如果像漏斗一样收窄，整个项目的容错能力都会提高。

3.3 容错策略：把"解析失败"当成一种数据来处理

既然工具类 App 要接收不干净的输入，那么"解析失败"就不能靠异常抛出完事，那会让 UI 层很被动。我的做法是定义一个解析结果对象，把成功和失败的路径统一收口：

dart复制class ParseResult {
  const ParseResult.success({required this.data, this.errorText})
      : success = true;

  const ParseResult.failure({required this.errorText, this.offset})
      : success = false,
        data = null;

  final bool success;
  final dynamic data;
  final String? errorText;
  final int? offset;
}

解析函数的核心逻辑先做语法校验，再做结构校验，最后才做业务模型转换：

dart复制ParseResult parseJsonString(String raw) {
  try {
    final decoded = jsonDecode(raw);
    return ParseResult.success(data: decoded);
  } on FormatException catch (e) {
    return ParseResult.failure(
      errorText: e.message,
      offset: e.offset,
    );
  }
}

把结果对象返回给 UI，界面就不用关心 JSON 解析的内部细节了，什么数据该展示、什么错误文案该出现，都由这个结果驱动。包括后面的格式化功能，也是先走一遍 parseJsonString，如果成功了就拿到 data，再把它格式化成字符串。这样避免了一段文本被解析两次，性能上是净赚。

这个数据层设计的核心思路：让解析器成为整个 App 唯一真正接触 JSON 字符串的地方，然后用统一的结果类型把成功和失败的语义传递出去。后续加功能，不管是导出、比较、还是生成代码，都只需要在这个数据层上面叠加，不会把解析逻辑散到页面里。

4. 三大核心功能拆解：格式化、校验、字段提取

4.1 格式化：不只是加个缩进那么简单

格式化是 JSON 工具最基础也最常用的功能。你拿到的一行压缩 JSON，可能是这样：

json复制{"name":"dev","tags":["flutter","harmony"],"profile":{"age":12,"active":true}}

想让它变成方便阅读的样子，最省事的做法是用 JsonEncoder.withIndent：

dart复制const encoder = JsonEncoder.withIndent('  ');
final pretty = encoder.convert(decodedValue);

这个方案能用，但有局限：第一，它不能控制键的排序，Map 的遍历顺序来自解码顺序，而解码顺序取决于输入文本；第二，它对空 Map、空数组的展示比较朴素，有时候会输出让人困惑的内容；第三，它无法定制数字格式，某些解析器会把 1.0 变成 1.0，再编码可能变成 1.0 或 1，这种细微差异在比对场景下很敏感。

所以我干脆写了一个自定义的递归格式化器，核心思路是按类型分派处理：

dart复制String formatJson(dynamic value, {int indentSize = 2}) {
  final buffer = StringBuffer();
  _writeValue(buffer, value, 0, indentSize);
  return buffer.toString();
}

void _writeValue(StringBuffer out, dynamic value, int depth, int indentSize) {
  if (value is Map) {
    if (value.isEmpty) {
      out.write('{}');
      return;
    }
    out.writeln('{');
    final keys = value.keys.toList();
    for (var i = 0; i < keys.length; i++) {
      final key = keys[i];
      out
        ..write(' ' * ((depth + 1) * indentSize))
        ..write('"')
        ..write(key)
        ..write('"')
        ..write(': ');
      _writeValue(out, value[key], depth + 1, indentSize);
      if (i < keys.length - 1) out.write(',');
      out.writeln();
    }
    out
      ..write(' ' * (depth * indentSize))
      ..write('}');
  } else if (value is List) {
    // 数组类型与 Map 类似，这里省略重复代码
  } else if (value is String) {
    out.write('"${_escapeString(value)}"');
  } else {
    out.write(value);
  }
}

这里一定要注意字符串转义，JsonEncoder 会把引号、反斜杠、换行符都做转义，自己写格式化器时不能漏。我一开始图省事直接 "$value"，结果内容里有引号时输出直接坏掉，变成了一个看似合法但复制出去会解释错位的 JSON。修补之后才稳定。

键排序也是个加分项。自然阅读习惯里，按字母序排列键比保留原始顺序更容易找字段，但有些人又希望保留原始顺序来对照原文件，所以我在设置里加了一个开关，默认关闭按键排序，满足不同习惯。

4.2 语法校验：把错误定位到行和列

格式化成功的链路可以不需要做额外校验，因为如果 JSON 不合法，格式化前那道 jsonDecode 就会失败了。只要把异常里的 offset 利用好，就能给用户一个非常友好的错误定位体验。

FormatException 的 offset 字段表示出错位置在字符串中的索引。但人看文本是按行看的，所以我需要一个把 offset 换算成行号和列号的方法：

dart复制({int line, int column}) lineColumnAt(String text, int offset) {
  var line = 1;
  var column = 0;
  for (var i = 0; i < offset && i < text.length; i++) {
    final code = text.codeUnitAt(i);
    if (code == 0x0A) {
      line++;
      column = 0;
    } else {
      column++;
    }
  }
  return (line: line, column: column);
}

这个算法本身很简单，就是遍历到 offset 为止，数一数换行符。真正的难点在于 offset 往往不是 100% 精确地指向出错字符，比如多了一个逗号，解析器可能会在下一个 key 的位置才报错，偏移会比直觉上靠后一些。所以 UI 上我不会宣称"错误就在这个字符"，而是展示"错误在某个范围附近"，再结合错误信息一起看，这样体验更好。

界面上的呈现我给了一个简单实用的方案：把错误提示显示在输入框上方，文案类似"第 12 行、第 30 列附近：Expected ':' after key"，同时把输入框的选区设置到出错位置附近的高亮区域。这样用户一眼就能顺着高亮找到问题。用 TextField 的 TextEditingController 配合 selection 属性就能做到，并不需要自己写复杂的语法高亮编辑器。

4.3 字段提取：比肉眼扒嵌套快得多

格式化只解决"看得清"，字段提取解决"找得到"。实际用日志的时候，我经常要拿到类似 data.items[0].orderInfo.price 这样的深层路径。用肉眼在格式化后的 JSON 里一层一层点开，效率太低。

我实现了一个叶子路径收集器，把 JSON 树里所有叶子节点的路径和值抽出来，平铺成一个列表：

dart复制List<MapEntry<String, dynamic>> collectLeaves(
  dynamic value, {
  String prefix = '',
}) {
  final result = <MapEntry<String, dynamic>>[];
  if (value is Map) {
    value.forEach((key, child) {
      final path = prefix.isEmpty ? '$key' : '$prefix.$key';
      if (child is Map || child is List) {
        result.addAll(collectLeaves(child, prefix: path));
      } else {
        result.add(MapEntry(path, child));
      }
    });
  } else if (value is List) {
    for (var i = 0; i < value.length; i++) {
      final path = '$prefix[$i]';
      final child = value[i];
      if (child is Map || child is List) {
        result.addAll(collectLeaves(child, prefix: path));
      } else {
        result.add(MapEntry(path, child));
      }
    }
  }
  return result;
}

这段代码跑完，一个多层嵌套 JSON 会变成长得像这样的列表：

text复制name: dev
tags[0]: flutter
tags[1]: harmony
profile.age: 12
profile.active: true

每个条目旁边放一个复制按钮，点击就把值复制到剪贴板。路径本身也做成了可复制的，方便拿去做其他场景的查询关键字。这个功能上线后，我的实际使用频率比格式化还高，因为查日志时大部分诉求是"我要到某一个值，别让我一层层翻"。

如果要更进一步，可以做一个按路径取值的方法，支持 a.b[0].c 这样的表达式。实现思路就是把路径字符串按 . 和 [] 拆成分段，再用循环或递归往下走，每一步都判断类型。这种简易版 JSONPath 足够覆盖 90% 的日常场景，没必要引入沉重的第三方库。

5. 体验优化：大文件解析、剪贴板、多端界面适配

5.1 把解析扔进 isolate，告别卡顿

JSON 工具遇到的第一个性能瓶颈是：如果粘贴了一段好几 MB 的 JSON，主线程上的 jsonDecode 会把 UI 卡住。我在测试里放了一个 5MB 左右的日志文件，解析加格式化在主线程上执行时，界面会明显掉帧，按键都要等一会儿才响应，这个体验是绝对不合格的。

Dart 的异步不等于并行，同一次事件循环里的 CPU 密集任务推不进队列就还是会阻塞 UI。所以必须用 isolate，把解析和格式化这两个 CPU 密集操作挪到后台线程。Dart 这边最省事的方式是 Isolate.run：

dart复制Future<ParseResult> parseInBackground(String raw) async {
  return Isolate.run(() {
    return parseJsonString(raw);
  });
}

这个用法有一点要提醒：Isolate.run 传入的闭包会把数据拷贝到新的 isolate，所以 raw 字符串和返回的对象都必须是可拷贝的类型。好消息是 Dart 字符串和 JSON 解析出来的 Map、List、num、bool 都是可拷贝的，不需要额外处理。但如果你返回了一个自定义对象，里面持有 File 或者 Socket 之类的资源，就会报错。我这里的 ParseResult 只持有可序列化的数据，所以没问题。

实测下来，5MB 的 JSON 在后台 isolate 里解析加格式化，耗时约在 300 到 500 毫秒之间，主线程完全不会被阻塞。界面上加一个 loading 状态提示，体验一下子就上来了。如果以后遇到更大的文件，可以把结果缓存起来，避免用户每次切换功能都重新解析。

还有个小细节：JSON 解析和格式化这两步可以合成一次做。解析成功的 data 对象已经存在，格式化只是把它再转成字符串，没必要读两次原文。这个在第一节数据层设计里已经埋下伏笔了，现在正好用上。

5.2 剪贴板与文件读写的几个坑

JSON 工具的两个高频输入来源，一是剪贴板粘贴，二是从文件读取。剪贴板这块，Flutter 官方提供了 Clipboard API，基本是开箱即用：

dart复制final data = await Clipboard.getData(Clipboard.kTextPlain);
if (data != null && data.text != null) {
  _inputController.text = data.text!;
  _parseInput(data.text!);
}

需要提醒的是，在鸿蒙和部分 Android 版本上，剪贴板读写会触发系统提示，这是隐私保护的一部分，不是 bug。

文件读取用的是 file_picker 这类社区插件。鸿蒙分支对第三方插件的适配情况参差不齐，我在选插件时的标准是：优先看 issue 里有没有人提交过 OpenHarmony/HarmonyOS 相关的适配请求，其次看最近一次更新日期。file_picker 目前有鸿蒙适配版本，但不同小版本 API 差异较大，建议锁定到你在真机上验证过的版本，不要在发版前随手升级。

权限模型这块，Android 的存储权限和鸿蒙不完全一样。鸿蒙有自己的一套权限申请机制，但 Flutter 插件层一般已经封装好了，应用层只需要在流程里触发一下授权请求。我在真机上第一次读取外部存储文件时系统弹了授权窗，点允许之后 file_picker 返回了正确的文件路径，之后就没有再弹过。不要花太多时间纠结底层权限差异，优先把业务逻辑跑通。

5.3 界面布局：从手机到折叠屏的通用方案

这个工具最舒服的使用场景其实是折叠屏或平板：左边输入 JSON，右边看格式化结果，不用来回切。但如果只在手机小屏上做两栏，内容会挤到没法看。我的方案是用 LayoutBuilder 判断可用宽度，超过某个阈值就分栏，否则就上下堆叠：

dart复制LayoutBuilder(builder: (context, constraints) {
  final wide = constraints.maxWidth >= 700;
  if (wide) {
    return Row(
      children: [
        Expanded(child: _buildInputPanel()),
        SizedBox(width: 12),
        Expanded(child: _buildOutputPanel()),
      ],
    );
  }
  return SingleChildScrollView(
    child: Column(
      children: [
        _buildInputPanel(),
        _buildOutputPanel(),
      ],
    ),
  );
})

这个方案简单可靠，不用引入第三方自适应库。再配合 MediaQuery.of(context).size.width 在 AppBar 上展示当前布局模式，排错时也能一目了然。

深色模式也是 JSON 开发者很在意的点。长时间盯着一片白底黑字会累，但如果自己做语法高亮又容易在深色模式下照顾不到。我的做法是遵循 Material 3 的 ColorScheme.fromSeed，从主题种子色生成整套配色，然后所有自定义颜色的地方都引用 Theme.of(context).colorScheme 里的变量，而不是写死色值。这样系统切到深色模式后，整个界面自动适配。

6. 真机调试与发布：从 HDB 到 HAP 的最后一公里

6.1 HDB 连接与无线调试

在鸿蒙设备上调试 Flutter 应用，常规链路是通过 HDB（HarmonyOS Debug Bridge）连接设备。先要在设备上开启开发者模式：进系统设置，连续点击版本号，直到出现开发者选项。然后打开"USB 调试"，用数据线连上电脑，在终端里敲 hdb list targets 看设备能不能被识别。

如果设备没有出现，最常见的原因是驱动问题或者没授权。电脑端会弹出确认框，在手机上点允许即可。之后的安装、日志查看就是常规操作：

bash复制hdb install -r your_app.hap
hdb shell hilog

无线调试的场景也很有用，尤其是我经常要在平板上测试，不想一直挂着数据线。鸿蒙的无线调试在开发者选项里开启后，会用 Wi-Fi 连接设备。注意两点：电脑和设备必须在同一局域网；IP 地址变化后需要重新配对。我实测下来稳定性尚可，真机长时间跑 Flutter 热重载时比 USB 线稍慢，但方便程度完全能接受。

6.2 构建 HAP：命令、签名和产物

Flutter 工程在鸿蒙侧构建出的是 HAP 包。鸿蒙适配分支的 Flutter 工具链提供了 hap 这个构建目标，命令大概是这样：

bash复制flutter build hap --release

首次构建会自动调用 DevEco 的后端工具链完成 HAP 打包，过程中会检查签名配置。真机调试时可以直接用 DevEco Studio 的自动签名功能，它会生成一个调试证书，不需要手工处理。发布版则需要基于正式签名证书，这个流程通常在 DevEco Studio 的 Project Structure 里配置。

我遇到过一个典型坑：HAP 包明明构建成功，但安装到真机上报签名错误。排查了很久，最后发现是 DevEco Studio 里默认的调试证书过期了。解决办法是重新生成证书，同时删掉旧的签名配置再填一次。所以建议在动手打包之前，先到签名配置界面确认证书有效期，别等到报错才去排查。

HAP 产物路径一般在项目的 build 目录下，跟 Android 的 app-release.apk 路径结构差不多。如果你以后还要发布到应用市场，一般还会要求做一次安全扫描，把权限表梳理清楚，避免申请不必要的高危权限。

6.3 发布前 Checklist 与实测效果

最后分享一份我在发布前的自测清单，虽然不是标准答案，但每次迭代后我都会过一遍：

这些条目看着简单，但每一条背后都对应我写代码时的一个取舍。比如空输入要提示而不是直接静默失败，这是从用户视角出发的细节；超大 JSON 要能在后台跑是性能底线；分栏适配是工具类应用在不同设备上都好用的前提。

回想这个项目的整个过程，我的体会是：把 Flutter 接到 HarmonyOS 上没有想象中那么玄乎，它更像是一个工程链路的整合问题，只要你愿意花时间把 SDK、Gradle 插件、签名这些底层环节一个个摸透，上层用 Flutter 写业务逻辑的体验和写 Android/iOS 并没有本质区别。而 JSON 解析工具这个选题，虽然功能边界很清晰，却恰好能覆盖你从数据层设计到性能优化的每一个技术点，练完这个项目再去看别的 App 需求，很多套路都是相通的。最后再提醒一句：如果你也要在鸿蒙设备上做 Flutter 应用，先把 Gradle 插件版本和签名证书这两个"隐藏大坑"提前排掉，后面的开发会顺畅很多。