flutter-pos-system项目架构解析:从目录结构看Flutter POS收银系统分层设计
flutter-pos-system项目架构解析:从目录结构看Flutter POS收银系统分层设计
flutter-pos-system 是一个开源的 Flutter POS 收银系统,专为小型餐厅与商户设计。本文带你逐层拆解它的目录结构,用零门槛的方式看懂「UI – Models – Services」三层分层设计,帮你快速建立对一个完整 Flutter 项目的整体认知。
一、项目目录结构全景图
先看根目录。项目采用标准的 Flutter 工程布局,核心业务代码集中在 lib/,测试目录与它一一镜像:
.
├── lib/ - 核心逻辑(全部业务代码都在这里)
├── test/ - 单元与组件测试,结构与 lib/ 镜像
├── android/ - Android 平台配置与商店素材
├── ios/ - iOS 平台配置
├── assets/ - 图片与多语言资源
├── docs/ - 项目文档(含架构说明)
└── pubspec.yaml - 依赖与项目配置
主要依赖在 pubspec.yaml 中声明:go_router 负责路由、provider 负责状态管理、sqflite 是关系型数据库、sembast 是 NoSQL 存储——这几个包基本决定了整个项目的架构形态。
二、入口层:4个文件撑起应用骨架
lib/ 根下只有 4 个文件,各司其职,是理解整个架构的最佳起点:
| 文件 | 职责 |
|---|---|
| main.dart | 初始化 Firebase、三大存储服务与各数据仓库,再用 MultiProvider 注入全局 |
| app.dart | 构建 MaterialApp.router,绑定主题与多语言设置 |
| routes.dart | 集中管理全部路由,并按屏幕宽度切换导航布局 |
| translator.dart | 提供全局翻译变量 S,避免每处都写冗长的本地化调用 |
main.dart 是观察分层设计的最好窗口:它先初始化 Database、Storage、Cache(Services 层),再逐个初始化 Models 下的 Menu、Stock、Cashier 等仓库(Repository),最后才 runApp。这个「自底向上」的启动顺序,正是分层解耦的直接证据。
三、UI 层:ui/ 按功能特性组织
ui/ 目录按业务功能划分子目录,每个功能遵循「一个主页面 + widgets/ 子组件」的统一约定:
ui/
├── analysis/ - 销售分析:折线图、饼图、历史订单
├── cashier/ - 收银与找零计算
├── home/ - 主页与设置页
├── menu/ - 菜单、产品、配料管理
├── order/ - 点单页、购物车、结账
├── order_attr/ - 顾客设定(订单属性)
├── printer/ - 蓝牙打印机与小票模板
├── stock/ - 库存成分与补货
└── transit/ - 导入导出:CSV、Excel、纯文本、Google Sheets
一个值得注意的细节 📱💻:这套 POS 收银系统并没有为不同设备写多套界面,而是靠一套「响应式宽度」逻辑。lib/helpers/breakpoint.dart 定义了从 compact 到 extraLarge 共 5 个 Material Design 断点,routes.dart 再根据断点选择不同的路由配置——手机用底部导航栏,平板和桌面则切换为侧边抽屉。同一个应用因此能自适应任意屏幕:
四、共享组件层:components/ 复用库
components/ 是一组不属于任何单一业务的通用积木 🧩:
dialog/—— 确认、删除、文本输入、滑块等各类对话框scaffold/—— 通用页面脚手架,如reorderable_scaffold.dart(拖拽排序)style/—— 按钮、加载动画、空状态等视觉组件loading_wrapper.dart、imageable_container.dart等小型通用件
UI 层的核心纪律:业务页面只与 Models 对话,绝不直接触碰 Services。重复操作统一沉淀到 components/,避免各页面各写一套。
五、数据层 models/:分层设计的核心
models/ 是整个项目的「业务大脑」🧠,内部分为四个层次:
models/
├── model.dart - 基类 Model,所有业务对象都继承它
├── repository.dart - 基类 Repository,封装统一 CRUD 与状态通知
├── menu/ stock/ order/ analysis/ - 具体业务对象(产品、库存、订单…)
├── objects/ - I/O 对象:导入导出用的纯数据结构
└── repository/ - 各业务的仓库:menu、stock、seller、cashier…
关键设计是 Model + Repository 双件套:
- Model(如
Product、Ingredient)表示单个业务对象,例如菜单里一个产品的图片、成分与份量; - Repository(如 lib/models/repository/menu.dart)是「仓库管理员」,负责把对象读写进存储,并维护一份内存中的对象缓存。lib/models/repository.dart 的基类已实现
addItem、removeItem、hasItem等通用能力; - Repository 同时是 Flutter 的
ChangeNotifier,UI 层通过provider监听它即可——数据一变,页面自动刷新。
这套设计让 UI 完全不用关心「数据从哪来、怎么持久化」,只需向 Repository 要结果。
六、服务层 services/:唯一对外出口
services/ 是唯一被允许触碰「外部世界」的层 🔌——文件系统、网络、第三方平台都从这里进出:
| 文件 | 职责 | 技术选型 |
|---|---|---|
| database.dart | 订单、收银等高频多行数据 | SQLite(sqflite),带版本迁移机制 |
| storage.dart | 菜单、库存等高变动配置数据 | NoSQL(sembast 文件存储) |
| cache.dart | 用户行为与小设置 | shared_preferences |
| auth.dart | Google 账号登录 | Firebase / Google Sign In |
| bluetooth.dart | 连接蓝牙热敏打印机 | 原生蓝牙通道 |
| image_dumper.dart | 图片的统一读写管理 | 本地文件系统 |
「双存储」是按业务特性做的取舍:订单数据行数多、需要聚合查询,用 SQL 合适;菜单与库存是少量、高频变更的结构化数据,用 NoSQL 文件存储更轻快。
七、设置、工具与常量:三大「管道层」
剩下三个小目录职责单一,但缺一不可:
settings/—— 主题、语言、币种等用户可调设置,由settings_provider.dart统一托管,设置变更后界面自动重建helpers/—— 日志、断点判断、输入校验等通用函数constants/—— 主题色、图标、间距等「定死」的标准值l10n/与assets/l10n/—— 应用内文字,按语言分目录存放(assets/l10n/zh/ 为中文文案)
八、测试层:test/ 镜像 lib/
test/ 的目录结构几乎与 lib/ 完全镜像——ui/ 下每个模块都有对应测试,models/ 配有 repository_test.dart 与 object_test.dart。配合 test/mocks/mock_database.dart 这类替代真实存储的 mock 对象,测试可以在不触碰磁盘和数据库的情况下运行。这是「架构能长期维护」的工程保障。
九、总结:一图看懂数据流向
把各层关系串起来:
UI(ui/、components/)
↓ 监听
Models(Model + Repository)
↓ 调用
Services(database / storage / cache / auth)
↓ 读写
本地文件系统 / 网络
flutter-pos-system 的分层设计可以归纳为三条核心原则 ✅:
- 单向依赖:UI 只依赖 Models,Models 只依赖 Services,下层永远不引用上层;
- 存储可替换:换数据库或存储引擎,只需要改
services/一个目录; - 功能自包含:每个业务在
ui/里自成一体,新增功能只需「加一个目录」,不动骨架。
对于想入门 Flutter 的读者,这是一个难得的完整范例:从真实收银业务出发,目录结构里就能看到职责如何划分、依赖如何约束、一个应用如何同时适配手机与大屏。
延伸阅读:项目官方架构文档 docs/about/structure.md 与中文版 docs/about/structure.zh.md 有逐目录的详细说明,适合作为你深入源码的下一站。


