Streak开发者指南:Flutter + Dart架构、Hive本地存储与按功能分模块设计完整深度剖析
Streak开发者指南:Flutter + Dart架构、Hive本地存储与按功能分模块设计完整深度剖析
Streak 是一款完全离线、无广告、无账号的开源习惯打卡应用,使用 Flutter + Dart 开发,采用 Hive 本地存储保存全部数据,并以按功能分模块(feature-first)的方式组织代码。对于想学习 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,依赖列表里看不到任何网络库。
打开 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,不依赖 UIstate/:状态控制器,如 habits_controller.dartpages/:页面级 Widgetwidgets/:模块内的可复用组件
这种"data / state / pages / widgets"四件套在 focus、todos、settings、statistics 等所有功能模块中完全一致。新增一个功能 = 新建一个目录、复制四件套,模块之间几乎零耦合,这就是"按功能分模块"的实际落地方式。
三、启动流程:从 main.dart 看懂应用如何拼装
入口文件 main.dart 不到 300 行,却展示了完整的启动编排。核心启动序列(_startup(),L85-L146)可以概括为五步:
- 初始化数据库:
LocalStore.init()打开全部 Hive 数据箱 - 拉取外部备份:
FolderSync.pull()检查共享文件夹中其他设备推送的备份 - 初始化通知系统:注册点击通知后的跳转回调
- 注册 MethodChannel:让桌面小组件能反向调用 App 逻辑(打卡、开始专注)
- 注入全局状态:
_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 个文件,按职责可分为四类:
① 通知与小组件
- notification_service.dart:为每个习惯的提醒独立排期
- home_widget_service.dart、todos_widget_service.dart:四个桌面小组件的数据同步
- widget_action_service.dart:处理"小组件上直接打卡"的异步动作队列
② 数据安全
- backup_service.dart / backup_archive.dart:单文件备份归档(
archive压缩 +crypto校验) - import_service.dart:从 Loop、Habitica 等应用及任意 CSV 导入历史
- vault_writer.dart / auto_sync.dart:自动备份节奏控制
③ 系统权限
- health_steps.dart:读取健康步数自动打卡
- desktop_window.dart:Windows 窗口行为
- portable_traces.dart:便携版退出时"不留痕迹"
④ 资源维护
- image_cleanup_service.dart:清理孤儿封面图
- reminder_schedule.dart:提醒时间的统一计算
七、专注模式与桌面视觉:架构之外的两个亮点
focus 模块(lib/features/focus/)是功能层的一个完整样板:data/ 里是 FocusSession 会话模型,state/ 里是管理倒计时的 FocusController,pages/ 里是计时器页面。更特别的是平台自适应渲染——桌面端用 focus_video_scene.dart 播放本地视频场景,而 Linux 版单独实现于 linux_video_scene.dart,直接调用 video_scene.cc 的 C++ 原生层,绕开了跨平台视频插件在 Linux 上的坑。这种"Dart 为主、原生补刀"的务实分层,是跨平台项目的常见真招。
专注模式的视频场景素材就存放在 desktop/scenes/ 目录,每段 1080p 视频配一张同帧封面图:
八、三套视觉皮肤与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个架构要点
- 离线优先决定一切依赖:没有网络库,数据全在本地,功能复杂度由存储层吸收
- 四层目录 + 功能四件套:
app / core / features / services分工清晰,新模块可模板化复制 - Hive 数据箱按域划分:7 个 Box 各司其职,模型手写序列化换取可读性与可控性
- 单向数据流:UI → 控制器 → LocalStore,
notifyListeners驱动刷新,缓存随修改失效 - 服务层隔离系统能力:通知、小组件、备份、导入各自成文件,功能模块无需感知平台细节
Streak 证明了一件事:架构的复杂度应该花在数据结构与模块边界上,而不是状态管理框架的花活上。如果你想找一个"每一层都看得懂、每一处都敢改"的 Flutter 项目来学习,它值得完整地读一遍。





