离线优先：无网络权限的鸿蒙 Flutter 应用设计

在万物互联的时代，做一个"断网"应用反而是最激进、也最负责任的设计选择。本文以 E-Brufen 为例，从架构哲学、存储设计、代码实现到用户体验，全面探讨离线优先应用的构建方法。

一、为什么选择离线？

1.1 一句话：零权限

打开 E-Brufen 的 ohos/entry/src/main/module.json5，你会看到这样一行配置：

1"requestPermissions": []
2

一个空数组。没有 ohos.permission.INTERNET、没有 ohos.permission.READ_MEDIA、没有 ohos.permission.LOCATION——什么权限都没有。这是整个应用最引以为豪的设计决策。

对比一下常规鸿蒙应用的最小权限清单：

1// 常规社交/工具类 App
2"requestPermissions": [
3  { "name": "ohos.permission.INTERNET" },
4  { "name": "ohos.permission.GET_NETWORK_INFO" },
5  { "name": "ohos.permission.STORE_PERSISTENT_DATA" }
6]
7
8// E-Brufen
9"requestPermissions": []  // 零权限
10

1.2 三个核心理由

对于一款心理健康应用，离线设计不是妥协，而是深思熟虑后的主动选择：

第一，隐私信任。用户的情绪数据极其私密——你今天生气、昨天难过、上周疲惫——这些数据如果被上传到任何服务器，哪怕是"加密传输"，用户也会产生合理的不安。不联网意味着数据永不离设备，这是技术上最强的隐私承诺，没有之一。当用户看到 AppGallery 安装页面上"无需任何权限"的提示时，信任从安装前就建立了。

第二，使用场景决定架构。心理健康工具的使用场景高度敏感：用户可能在睡前最后一刻打开呼吸练习、可能在情绪崩溃时快速记录心情、可能在地铁无信号的隧道里听白噪音放松。这些场景的共同特征是——网络不可靠且用户不想等待。如果每次打开都要"加载中…"，应用就失去了作为即时情绪支持工具的意义。

第三，审核与分发。零权限应用在 AppGallery 的审核流程中几乎没有阻力——审核人员不需要审查你的网络请求目的、隐私政策、数据跨境传输。用户也不会在安装时产生"为什么一个情绪日记应用要联网"的疑虑，降低了卸载率。

★ Insight ─────────────────────────────────────
离线设计不是"功能缺失"，而是隐私优先的架构主动选择。把"不联网"当作特性宣传，比"我们加密了你的数据"更能建立用户信任——因为前者是可验证的，后者需要用户相信你的承诺。
─────────────────────────────────────────────────

二、隐私优先：心理健康数据的安全模型

2.1 数据模型设计——最小化原则

E-Brufen 的情绪数据模型非常克制。MoodEntry 只包含最必要的字段：

1// lib/models/mood_entry.dart
2class MoodEntry {
3  final int? id;
4  final MoodType moodType;    // 五种情绪枚举
5  final String? note;         // 可选文本笔记（最大500字）
6  final DateTime createdAt;
7  final DateTime updatedAt;
8}
9

它刻意不做的事情和它做的事情同样重要：

• 不收集用户身份信息（无用户名、无邮箱、无手机号）
• 不采集设备指纹（无 Device ID、无 OAID）
• 不记录地理位置
• 不追踪使用行为（无埋点、无分析 SDK）
• 没有账号体系——你不是"用户"，你只是这台设备的持有者

2.2 数据完全离线，零传输路径

整个应用的数据流是单向且封闭的：

1用户输入 → MoodStorage (Dart 对象)
2              ↓ ChangeNotifier 通知 UI
3              ↓ jsonEncode 序列化
4              ↓ Hive Box.put(id, jsonString)
5              ↓ 本地文件系统（二进制 Box 文件）
6              ↓
7          仅此而已，无任何下一步
8

验证方式很简单：你可以用 Wireshark 抓包、用鸿蒙的流量统计、甚至直接开启飞行模式——E-Brufen 在任何情况下都不会产生哪怕一个字节的网络流量。

2.3 ChangeNotifier——本地状态传播无需网络

MoodStorage 继承自 ChangeNotifier，而非使用 Provider/Riverpod/BLoC 等需要额外依赖的状态管理库：

1// lib/data/mood_storage.dart
2class MoodStorage extends ChangeNotifier {
3  Box? _box;
4
5  Future<int> insert(MoodEntry entry) async {
6    final id = _nextId++;
7    // ... 写入 Hive Box
8    notifyListeners();  // 通知所有监听者刷新 UI
9    return id;
10  }
11
12  List<MoodEntry> getAll() {
13    // 同步读取，毫秒级响应
14    // 直接从内存 Hive Box 遍历
15  }
16}
17

Flutter 框架自带的 ChangeNotifier + addListener 模式足以支撑这个规模的应用，无需引入任何第三方状态管理库——这本身就是离线哲学在依赖管理上的延伸。

三、本地存储架构深度解析

3.1 为什么是 Hive CE？

Hive CE（Community Edition）是当前鸿蒙 Flutter 生态中唯一成熟的纯 Dart 本地存储方案。与 SQLite 的对比：

对于情绪日记这种"按 ID 存取、按时间排序展示"的场景，键值存储比关系型数据库更合适——你不需要 JOIN、不需要复杂查询，Hive 的内存缓存保证了毫秒级的读写性能。

3.2 存储分层设计

E-Brufen 使用两个 Hive Box 实现关注点分离：

1Box "settings" (AppSettings)
2├── selectedScene: "雨中办公"     // 白噪音场景选择
3├── timerDuration: 30             // 倒计时分钟数
4├── breatheMode: "盒式呼吸"       // 呼吸模式
5└── breatheMinutes: 3             // 呼吸练习时长
6
7Box "moods" (MoodStorage)
8├── key: 1  → '{"id":1,"mood_type":5,"note":"今天不错","created_at":"...","updated_at":"..."}'
9├── key: 2  → '{"id":2,"mood_type":2,"note":"有点难过","created_at":"...","updated_at":"..."}'
10├── key: 3  → ...
11└── key: N  → ...
12

AppSettings 负责轻量级的键值配置（用户偏好），MoodStorage 负责结构化的情绪数据。两者互不干扰，各自独立打开/关闭，符合单一职责原则。

3.3 AppSettings——优雅的配置封装

1// lib/data/settings.dart
2class AppSettings {
3  static const String _boxName = 'settings';
4  Box? _box;
5
6  // 读：默认值兜底，避免空指针
7  String get selectedScene {
8    if (_box == null || !_box!.isOpen) return '雨中办公';
9    return _box!.get('selectedScene', defaultValue: '雨中办公');
10  }
11
12  // 写：静默忽略未初始化状态
13  set selectedScene(String v) {
14    if (_box != null && _box!.isOpen) _box!.put('selectedScene', v);
15  }
16}
17

关键设计点：

• 防御性读取：每次 getter 都检查 _box != null && _box!.isOpen，即使在初始化失败场景下也不会空指针崩溃
• 默认值内聚：'雨中办公'、30、'盒式呼吸'、3 这些默认值与业务逻辑同文件定义，修改时不会遗漏
• 静默写失败：如果 Box 未就绪，setter 不抛异常——这对非关键配置来说是合理的降级策略

3.4 MoodStorage——同步读取的极致体验

1// lib/data/mood_storage.dart
2List<MoodEntry> getAll() {
3  // 同步方法！无 await，无 FutureBuilder，无 loading spinner
4  if (_box == null) return [];
5  final entries = <MoodEntry>[];
6  for (final key in _box!.keys) {
7    if (key is int) {
8      final raw = _box!.get(key);
9      if (raw is String) {
10        entries.add(_parse(key, raw));
11      }
12    }
13  }
14  entries.sort((a, b) => b.createdAt.compareTo(a.createdAt));
15  return entries;
16}
17

这是 Hive 的杀手特性——内存缓存保证了同步读取的高性能。数据在 openBox() 时全部加载到内存中，后续的 get() 操作是纯粹的内存遍历。对于日级粒度的情绪数据（用户一天最多几十条记录），即使是几年的数据总量也在毫秒级完成。

★ Insight ─────────────────────────────────────
很多人习惯性地给所有数据访问加上 async/await，但 Hive 的键值读取在数据量不大的场景下可以安全地使用同步 API。这带来的 UX 提升是立竿见影的——列表页打开瞬间渲染，无需 CircularProgressIndicator。
─────────────────────────────────────────────────

四、零外部资源——程序化生成一切

4.1 程序化音频生成架构

传统白噪音应用通常有两条路径：(A) 打包 100MB+ 的音频文件；(B) 从网络流媒体播放。E-Brufen 选择了第三条路——用数学算法在构建时生成音频。

generate_audio.dart 是一个独立的 Dart 脚本（255 行），利用不同频率的噪声模拟四种自然音效：

1// 高斯噪声生成器——所有自然音效的数学基础
2double _gauss() {
3  final u1 = _rand.nextDouble();
4  final u2 = _rand.nextDouble();
5  return sqrt(-2 * log(max(u1, 0.0001))) * cos(2 * pi * u2);
6}
7

四种音效的算法原理：

WAV 文件的手写编码：

1void _writeWav(String path, int sampleRate, List<int> samples) {
2  // RIFF header → fmt chunk (PCM, mono, 16-bit) → data chunk
3  // 纯字节操作，不依赖任何音频库
4  bytes.addAll('RIFF'.codeUnits);
5  w32(36 + samples.length * 2);  // fileSize
6  bytes.addAll('WAVE'.codeUnits);
7  // ...
8}
9

每个文件采样率 22050Hz、单声道 16-bit PCM、30 秒时长，单个文件约 1.3MB，四个文件合计约 5.3MB——远小于打包外部音频的常见体积。

4.2 程序化图标生成架构

generate_icon.dart（187 行）用纯数学在 512x512 的画布上绘制应用图标，输出标准 PNG 格式：

1// 极坐标下的花瓣纹理
2final angle = atan2(cy, cx);
3final petalDist = dist * (1 + 0.3 * sin(angle * 3) * sin(dist * pi * 2));
4
5// 圆角方形边缘的抗锯齿 Alpha 混合
6final edgeDist = max(
7  (cx.abs() - width * 0.35).clamp(0, width.toDouble()),
8  (cy.abs() - height * 0.35).clamp(0, height.toDouble()),
9);
10if (edgeDist > 0 && edgeDist < 20) {
11  final edgeAlpha = (1 - edgeDist / 20.0).clamp(0.0, 1.0) * 0.6;
12  a = (255 * (1 - edgeAlpha)).toInt();
13}
14

PNG 编码完全手写——IHDR 块、IDAT 块（含手写 Deflate + Adler-32）、IEND 块、CRC32 校验。不依赖 dart:ui 的 toImage()、不依赖任何图片库。

4.3 最小化依赖清单

打开 pubspec.yaml，你会看到堪称极简主义的依赖列表：

1dependencies:
2  flutter:
3    sdk: flutter
4  cupertino_icons: ^1.0.8    # 仅用于 Material Design 中缺失的图标
5  hive_ce: ^2.19.0            # 纯 Dart 本地存储
6  hive_ce_flutter: ^2.3.0     # Flutter 适配层
7

4 个依赖。没有 http、dio、firebase_core、cloud_firestore、shared_preferences、sqflite、path_provider、permission_handler。

这是一种"依赖最小化"哲学：每一个你不引入的依赖，都意味着零个潜在的安全漏洞、零次 API 不兼容的升级痛苦、零个需要鸿蒙适配的原生插件。

五、离线 UX——为即时响应设计

5.1 无加载 Spinner

因为所有数据都在本地、所有读取都是同步的，应用中不存在"加载中"的状态：

1// diary_page.dart —— 用户切换到"时间线"Tab，数据瞬间就绪
2void _loadMoods() {
3  setState(() {
4    _allMoods = widget.moodStorage.getAll();   // 同步！无 await
5    _weekMoods = widget.moodStorage.getByWeek(DateTime.now());
6  });
7}
8

这不仅仅是技术实现的问题——它塑造了一种用户心智模型：“我的数据就在手边”。没有网络延迟的等待，用户的情绪记录行为从"提交-等待-确认"变成了"输入-完成"的瞬时闭环。

5.2 无网络错误提示

没有网络请求意味着永远不会出现这些用户深恶痛绝的 UI：

• "网络连接失败，请稍后重试"
• "请求超时，请检查网络设置"
• "服务器繁忙，请稍后再试"
• 灰色的 CircularProgressIndicator 无限旋转
• 自动重试的弹窗打断用户操作

E-Brufen 唯一可能的错误都在本地层面——Hive 初始化失败、磁盘空间不足——而这些错误在 main() 函数中就被统一捕获：

1// lib/main.dart
2try {
3  errorStep = 'Hive init';
4  await Hive.initFlutter();
5  // ...
6  runApp(EBrufenApp(settings: settings, moodStorage: moodStorage));
7} catch (e, _) {
8  debugPrint('[E-Brufen] INIT FAILED at $errorStep: $e');
9  runApp(_ErrorApp(errorStep ?? '?', e.toString()));  // 优雅降级
10}
11

_ErrorApp 显示一个友好的"初始化失败"界面，包含具体的错误步骤和消息，帮助用户和开发者定位问题——但这在正常使用中几乎不会触发。

5.3 触觉反馈——离线也可以"高级"

离线不等于交互简陋。E-Brufen 在白噪音倒计时中加入了触觉反馈：

1// soundscape_page.dart
2_countdown = Timer.periodic(const Duration(seconds: 1), (timer) {
3  // ...
4  if (_remainingSec > 0 && _remainingSec % 60 == 0) {
5    HapticFeedback.lightImpact();  // 每分钟轻震提醒
6  }
7});
8
9void _onTimerDone() {
10  HapticFeedback.heavyImpact();  // 时间到，重震通知
11}
12

HapticFeedback 是 Flutter 框架内置的触觉反馈 API，不依赖任何权限或许可。在用户闭眼放松时，这些触觉信号比视觉通知更自然、更少打扰。

5.4 响应式问候语——感知用户时间

1// home_page.dart
2String get _greeting {
3  final hour = DateTime.now().hour;
4  if (hour < 6)  return '夜深了，好好休息   ';
5  if (hour < 12) return '早上好，今天也要元气满满   ';
6  if (hour < 18) return '下午好，给自己一个深呼吸   ';
7  return '晚上好，让疲惫都散去吧   ';
8}
9

基于本地时钟的分时段问候——不需要 IP 定位、不需要时区 API、不需要任何网络请求。

六、数据导出——离线不等于数据孤岛

6.1 为什么需要导出

离线存储的优势也是它的劣势——数据困在单设备上。当用户换手机、想分享给医生、或需要做自我分析时，他们需要把数据"拿"出来。

6.2 当前数据格式——导出就绪

E-Brufen 的数据从一开始就以 JSON 格式存储，天然适合导出：

1{"id":1,"mood_type":5,"note":"今天阳光很好","created_at":"2025-07-01T10:30:00.000","updated_at":"2025-07-01T10:30:00.000"}
2

MoodEntry.toJson() 方法已定义好了标准 Map 结构，导出功能只需遍历 Hive Box 的所有记录，组装成数组后用 JsonEncoder.withIndent() 格式化即可。

6.3 规划中的导出方案

1导出路径设计：
2  情绪数据 → JSON 数组 → 系统分享 Sheet → 用户选择目标
3                                          ├── 保存到文件
4                                          ├── 发送到微信/邮件
5                                          └── 其他系统分享渠道
6

关键设计原则：

• 用户主动触发：导出按钮明确在设置或统计页面，不存在自动导出
• 无中间服务：生成的文件直接通过系统分享 API 传递，不经过任何第三方服务器
• 格式开放：JSON（机器可读）+ CSV（Excel 兼容）双格式，用户可自行处理

七、完整性设计——从初始化到错误恢复

7.1 分步初始化流水线

main() 函数的初始化不是"一把梭"，而是明确分步、每步可追踪：

1// lib/main.dart — 第 1-53 行
2void main() async {
3  WidgetsFlutterBinding.ensureInitialized();
4
5  String? errorStep;
6
7  try {
8    errorStep = 'Hive init';           // 步骤1
9    await Hive.initFlutter();
10
11    errorStep = 'Settings init';       // 步骤2
12    final settings = AppSettings();
13    await settings.init();
14
15    errorStep = 'MoodStorage init';    // 步骤3
16    final moodStorage = MoodStorage();
17    await moodStorage.init();
18
19    errorStep = null;                  // 全部成功
20    runApp(EBrufenApp(settings: settings, moodStorage: moodStorage));
21  } catch (e, _) {
22    debugPrint('[E-Brufen] INIT FAILED at $errorStep: $e');
23    runApp(_ErrorApp(errorStep ?? '?', e.toString()));
24  }
25}
26

每步都设置 errorStep，崩在哪一步一清二楚——这对离线应用的远程支持至关重要：当用户报告"应用打不开"时，errorStep 告诉你问题在 Hive 层还是 Settings 层还是 MoodStorage 层。

7.2 优雅降级：initFlutter 失败也能跑

1try {
2  await Hive.initFlutter();
3} catch (e) {
4  debugPrint('[E-Brufen] initFlutter failed, using temp dir: $e');
5  Hive.init(Directory.systemTemp.path);  // 退回到临时目录
6}
7

在鸿蒙设备上，如果 Flutter 插件包装的路径初始化失败，回退到系统临时目录——用户的数据不会丢（只是临时存储），应用不会白屏。

7.3 资源释放

1// mood_storage.dart
2@override
3void dispose() {
4  _box?.close();  // 关闭 Hive Box
5  super.dispose();
6}
7
8// settings.dart
9void dispose() {
10  _box?.close();
11}
12

每个存储层都实现了 dispose()，确保应用退出或页面销毁时 Hive Box 被正确关闭，避免文件句柄泄露。

八、离线应用的局限性与诚实面对

对于 E-Brufen 的定位——个人情绪记录与放松工具——这些局限是有意识接受的设计取舍，而非技术不足。隐私保护的价值远大于云端同步的便利性，这是产品的核心价值主张。

九、设计哲学：数字极简主义

E-Brufen 代表的是一种"数字极简主义"的应用设计理念。它用代码证明了几个反直觉的事实：

1. 不联网的应用可以更强大——因为所有功能在离线状态下都能完整运行，不受网络质量影响
2. 依赖越少越稳定——4 个依赖 vs 典型 Flutter 项目的 30+ 个依赖，升级断链的风险趋近于零
3. 隐私保护最好的方式是物理隔离——不联网比任何加密算法都更安全，因为数据根本不在传输通道上
4. 程序化生成比打包文件更灵活——算法可以调参，而打包的音频文件只能替换

好的软件不是功能的堆砌，而是知道什么不该做。

不联网、不收集数据、不依赖外部服务——这看似"少做"，实则是对用户隐私最深层的尊重，也是对应用稳定性的最严格保障。

当你把 requestPermissions 设为空数组时，你给用户的不是"功能受限的应用"，而是一个完全由用户掌控的数字空间。

十、关键文件速查

项目源码：https://gitcode.com/PengXiansheng/E-Brufen

《离线优先：无网络权限的鸿蒙 Flutter 应用设计》 是转载文章，点击查看原文。