Streak开发者指南:Flutter + Dart架构、Hive本地存储与按功能分模块设计完整深度剖析

原创2026-10-25 20:42:481,427 阅读

Streak开发者指南:Flutter + Dart架构、Hive本地存储与按功能分模块设计完整深度剖析

Streak 是一款完全离线、无广告、无账号的开源习惯打卡应用,使用 Flutter + Dart 开发,采用 Hive 本地存储保存全部数据,并以按功能分模块(feature-first)的方式组织代码。对于想学习 Flutter 应用架构的开发者来说,它是一个非常干净的参考样板:没有网络请求、没有账号体系,却能支撑习惯追踪、番茄钟专注、待办事项、统计图表、桌面小组件等一整套功能。本文将从目录结构、启动流程、数据存储、状态管理、服务分层等角度,带你完整读懂这个项目。

Streak习惯追踪应用官方Banner:Flutter开发的多平台习惯打卡工具

如果你想动手阅读源码,可以先获取项目:

git clone https://gitcode.com/gh_mirrors/streak2/streak

一、项目全貌:一个"小而全"的Flutter应用

Streak 支持 Android、Windows、Linux 三个平台,当前版本 2.5.0(pubspec.yaml 中声明 SDK 要求为 ^3.9.2)。它的核心卖点是"数据全部留在设备本地",这直接决定了技术选型——没有后端,所以没有 Retrofit、没有 GraphQL,依赖列表里看不到任何网络库。

Streak应用界面概览:今日打卡、专注计时与统计热力图三个核心页面

打开 pubspec.yaml,几个关键依赖就能勾勒出应用的能力版图:

依赖 职责
hive_ce_flutter 本地数据库,所有数据的落盘位置
provider 状态管理,配合 ChangeNotifier 控制器
fl_chart 统计页的折线图、环形图、柱状图
flutter_local_notifications 每个习惯的独立提醒通知
flutter_timezone / timezone 时区感知的"今日"判定与提醒调度
home_widget Android 桌面小组件(打卡不打开App)
audioplayers 专注模式的白噪音/音乐
local_auth PIN 码或指纹应用锁
archive + crypto 单文件备份归档与校验
lucide_icons_flutter 图标体系

可以看到一个规律:依赖都是"离线友好"的。理解这一点,是理解 Streak 架构的第一把钥匙。


二、目录结构:四层分工的模块化设计

Streak 的 Dart 代码全部位于 lib/ 目录,按"外壳 → 基础 → 功能 → 服务"四层组织,这是它最值得学习的地方:

lib/
├── main.dart            # 入口:启动流程 + 全局状态注入
├── app/                 # 外壳层:MaterialApp、导航壳、主题、应用锁
│   ├── streak_app.dart
│   ├── home_shell.dart
│   └── theme/           # 调色板、主题、设计令牌
├── core/                # 基础层:谁都能依赖,谁都不依赖业务
│   ├── database/        # LocalStore(Hive封装)、DataLocation
│   ├── routing/         # 全局导航
│   ├── i18n/            # 国际化
│   ├── widgets/         # 通用UI组件
│   ├── express/         # "Express"视觉风格组件
│   └── minimal/         # "Minimal"视觉风格组件
├── features/            # 功能层:每个功能一个自包含模块
│   ├── habits/          # 习惯(核心模块)
│   ├── focus/           # 专注计时
│   ├── todos/           # 待办事项
│   ├── statistics/      # 统计
│   ├── island/          # 小岛养成
│   ├── settings/        # 设置
│   └── onboarding/      # 新手引导
├── services/            # 服务层:跨功能的系统能力
└── l10n/                # 28种语言的翻译文件

功能层内部再统一切四刀,以最大的 habits 模块为例:

  • data/:纯数据模型,如 habit.dart,不依赖 UI
  • state/:状态控制器,如 habits_controller.dart
  • pages/:页面级 Widget
  • widgets/:模块内的可复用组件

这种"data / state / pages / widgets"四件套在 focus、todos、settings、statistics 等所有功能模块中完全一致。新增一个功能 = 新建一个目录、复制四件套,模块之间几乎零耦合,这就是"按功能分模块"的实际落地方式。


三、启动流程:从 main.dart 看懂应用如何拼装

入口文件 main.dart 不到 300 行,却展示了完整的启动编排。核心启动序列(_startup(),L85-L146)可以概括为五步:

  1. 初始化数据库:LocalStore.init() 打开全部 Hive 数据箱
  2. 拉取外部备份:FolderSync.pull() 检查共享文件夹中其他设备推送的备份
  3. 初始化通知系统:注册点击通知后的跳转回调
  4. 注册 MethodChannel:让桌面小组件能反向调用 App 逻辑(打卡、开始专注)
  5. 注入全局状态:_run()(L148-L179)用 MultiProvider 一次注入 8 个 ChangeNotifier 控制器——SettingsController、HabitsController、TodosController、FocusController、IslandController 等

还有一个精巧的细节:文件末尾定义了带 @pragma('vm:entry-point') 的独立入口 widgetActionEntrypoint()(L274-L293)。它让 Android 小组件在不启动完整 App 进程的情况下完成打卡并同步小组件画面,是性能优化的典范。


四、Hive本地存储:LocalStore如何管理7个数据箱

4.1 七个Box的分工

所有持久化逻辑集中在 local_store.dart。LocalStore 是一个静态门面类,用 Hive 管理 7 个数据箱(L19-L25):

Box 名称 存储内容
habits 习惯及其全部打卡历史
settings 全部应用设置项
categories 习惯分类
notes 每日笔记(含照片路径)
focus 专注会话记录
todos 待办事项
todo_tags 待办标签

数据模型的序列化刻意放弃了 Hive 的代码生成器(TypeAdapter + build_runner),而是让每个模型手写 toMap() / fromMap(),直接存普通 Map。好处是模型文件可以独立阅读、序列化行为完全可控;代价是字段多时略显繁琐——Habit 模型一个文件就有 1100+ 行,但换来了零代码生成依赖。

4.2 打卡历史就住在模型里

Habit 数据模型(habit.dart)是理解数据设计的最佳样本。它的字段划分很有讲究:

  • 基础信息:名称、颜色、图标、分类、排序
  • 调度规则:HabitInterval 枚举支持 每日/每周/每月/指定星期/每N天 五种频率(L14)
  • 三种习惯类型:HabitKind 枚举分为 正向、避免(记录"没做")、量化(如喝水杯数、阅读页数),量化类还有 QuantKind 细分子类型
  • 打卡历史:Map<String, Completion> completions —— 以日期字符串为键,历史直接内嵌在习惯对象里,一次读取即得全部数据

这种"历史内嵌"设计配合 Hive 的整键读写,使得统计页计算"连续天数、完成率"时不需要任何 JOIN。

4.3 多设备同步的"时间戳账本"

Streak 没有服务器,但提供了文件夹备份同步。LocalStore 内部维护三本时间戳账本(L26-L29):syncChanges(谁改过)、syncDeleted(谁删过)、syncCleared(谁清空过),每次写操作都打时间戳,合并时按时间戳裁决冲突;删除记录保留 120 天后自动遗忘。配合 folder_sync.dart 和 backup_service.dart,多设备数据交换完全靠"共享文件夹里的备份文件"完成。

4.4 数据目录可迁移

data_location.dart 负责"数据住在哪"。它支持用户把全部数据目录搬到任意位置(包括便携模式:L37-L41 允许数据就存放在可执行文件旁的 StreakData 文件夹),迁移时逐条重写数据中记录的文件路径(rewrite() 方法递归改写 Map/List 里的路径字符串),并校验每个文件复制后的字节数一致才算成功。这套"数据位置与数据内容解耦"的做法,是桌面应用少见的严谨实现。


五、状态管理:provider + ChangeNotifiersimple套路,做到极致

Streak 选择了 Flutter 生态最轻量的方案:provider 包 + ChangeNotifier,没有 Riverpod、没有 Bloc。

以核心控制器 habits_controller.dart 为例,它展示了几个值得抄的作业:

  • 构造函数即加载数据:_habits = LocalStore.readHabits(),控制器是"内存中的工作副本"
  • 懒缓存:habits、withArchived 等 getter 用 ??= 缓存排序后的列表,任何修改都会调用 notifyListeners() 并清空缓存(L39-L45)
  • 跨日自动重算:refresh() 检测到"今天"变了就整体重算一次打卡状态(L98-L101)
  • 写前安全备份:像 clearProgress() 这类破坏性操作,先调用 BackupService.safetyCopy() 落一份保险

页面侧只需 context.watch<HabitsController>(),数据一变,UI 自动重建。UI 从不直接读写 Hive,只跟控制器打交道;控制器是唯一读写 LocalStore 的人——这条单向数据流贯穿全项目,是它"简单却不乱"的根本原因。


六、services/ 目录:跨功能的能力中枢

功能模块管"业务",services/ 目录管"系统能力",共 19 个文件,按职责可分为四类:

① 通知与小组件

Streak桌面小组件活动热力图预览:GitHub风格习惯打卡网格

② 数据安全

③ 系统权限

④ 资源维护


七、专注模式与桌面视觉:架构之外的两个亮点

focus 模块(lib/features/focus/)是功能层的一个完整样板:data/ 里是 FocusSession 会话模型,state/ 里是管理倒计时的 FocusController,pages/ 里是计时器页面。更特别的是平台自适应渲染——桌面端用 focus_video_scene.dart 播放本地视频场景,而 Linux 版单独实现于 linux_video_scene.dart,直接调用 video_scene.cc 的 C++ 原生层,绕开了跨平台视频插件在 Linux 上的坑。这种"Dart 为主、原生补刀"的务实分层,是跨平台项目的常见真招。

Streak专注模式桌面场景cabin_rain:雨夜小屋插画背景

专注模式的视频场景素材就存放在 desktop/scenes/ 目录,每段 1080p 视频配一张同帧封面图:

Streak专注模式桌面场景fireplace_room:壁炉暖光插画背景


八、三套视觉皮肤与28种语言

Streak 把"主题"做成了架构级能力:同一个 features/ 数据源之上,并存三套完整视觉体系——

  • Classic(经典):app/classic_nav_bar.dart + 传统 Material 组件
  • Minimal(极简):core/minimal/ 独立的一套排版、导航、控件
  • Express(灵动):core/express/ 14 个文件的动效组件库

切换皮肤只改一个设置项,页面在各风格间"换装",数据与逻辑零改动——这是"UI 与数据彻底分离"能带来的最大红利。主题定义集中在 lib/app/theme/(调色板、主题、设计令牌三件套)。

国际化方面,l10n/ 目录收纳了 28 种语言的 .arb 文件(从阿拉伯语到中文繁简),配合 flutter_localizations 与 l10n.yaml 自动生成。


九、测试:60多个测试文件守住重构底线

test/ 目录下有 60+ 个测试文件(test/),几乎每个功能点都有对应测试:dst_test.dart 专测夏令时切换对"今日"判定的影响、backup_roundtrip_test.dart 验证备份-恢复的数据一致性、import_race_test.dart 测试导入过程的竞态。公共夹具抽在 app_harness.dart 中,用内存环境替代真实文件系统。对一个无后端的本地应用来说,这套测试让"随便重构"变成了"放心重构"。


十、总结:从Streak学到的5个架构要点

Streak习惯追踪应用社交分享卡片:极简隐私的Flutter打卡工具

  1. 离线优先决定一切依赖:没有网络库,数据全在本地,功能复杂度由存储层吸收
  2. 四层目录 + 功能四件套:app / core / features / services 分工清晰,新模块可模板化复制
  3. Hive 数据箱按域划分:7 个 Box 各司其职,模型手写序列化换取可读性与可控性
  4. 单向数据流:UI → 控制器 → LocalStore,notifyListeners 驱动刷新,缓存随修改失效
  5. 服务层隔离系统能力:通知、小组件、备份、导入各自成文件,功能模块无需感知平台细节

Streak 证明了一件事:架构的复杂度应该花在数据结构与模块边界上,而不是状态管理框架的花活上。如果你想找一个"每一层都看得懂、每一处都敢改"的 Flutter 项目来学习,它值得完整地读一遍。

登录后查看全文
streak