【 Flutter 学习笔记】PC端工程化目录架构实战指南

最新推荐文章于 2026-08-29 17:50:32 发布

原创

最新推荐文章于 2026-08-29 17:50:32 发布 · 198 阅读

Flutter PC 端工程化目录架构实战指南

适用版本：Flutter 3.24+ / Dart 3.5+
核心范式：Feature-First + MVVM + 平台适配层
目标场景：Windows / macOS / Linux 桌面级应用

1. 为什么 PC 端需要独立的架构范式？

直接将移动端架构平移到 PC 端是绝大多数桌面项目的“原罪”。PC 端与移动端在交互模型、信息密度和运行环境上存在本质差异，这决定了其目录架构必须解决三个移动端不存在的问题：

多窗口与状态隔离：移动端 App 是单实例的，而 PC 端天然支持多窗口/多标签。全局 Store 的设计必须区分“跨窗口共享”与“窗口私有”两种生命周期。
键鼠优先的交互契约：Hover、Focus、键盘快捷键、右键菜单是一等公民，而非移动端的附加功能。这要求组件层和快捷键系统有独立的组织空间。
原生能力的深度集成：系统托盘、文件对话框、窗口标题栏拖拽、注册表/Keychain 访问等平台能力，若散落在业务代码中，将彻底摧毁可测试性和跨平台兼容性。

本指南提供的架构并非对移动端架构的修补，而是从 PC 端第一性原理出发的重新设计。

2. 完整目录结构

project_root/
├── assets/                     # 🎨 静态资源（根目录，非 lib 内）
│   ├── icons/                  # SVG 矢量图标（按模块分组）
│   ├── images/                 # 位图（含 @2x/@3x 多倍率）
│   ├── fonts/                  # 自定义字体（UI + 等宽）
│   ├── animations/             # Rive/Lottie 动画
│   └── data/                   # 预置配置/协议文件
│
├── lib/
│   ├── core/                   # 🔩 基础设施层（零业务依赖）
│   │   ├── constants/          # 编译期常量、断点、尺寸令牌
│   │   ├── utils/              # 纯函数工具类
│   │   ├── errors/             # 统一异常定义
│   │   └── extensions/         # Dart 扩展方法
│   │
│   ├── platform/               # 💻 平台适配层（PC 专属核心）
│   │   ├── channels/           # Platform Channel 原始封装
│   │   ├── services/           # 业务语义化平台服务接口
│   │   └── platform_module.dart # 统一导出 + DI 配置
│   │
│   ├── shortcuts/              # ⌨️ 快捷键系统（PC 专属核心）
│   │   ├── intents.dart        # Intent 定义（Sealed Class）
│   │   ├── actions.dart        # Action 处理器
│   │   └── registry.dart       # 快捷键绑定表
│   │
│   ├── layouts/                # 📐 响应式布局系统（PC 专属核心）
│   │   ├── breakpoints.dart    # 断点枚举
│   │   ├── adaptive_scaffold.dart # 自适应脚手架
│   │   └── panel_layout.dart   # 可拖拽/折叠面板
│   │
│   ├── shared/                 # 🧩 全局共享层
│   │   ├── components/         # 原子 UI 组件（含 Hover/Focus）
│   │   ├── stores/             # 跨窗口共享状态（Auth/AppConfig）
│   │   └── api/                # HTTP 客户端 + 拦截器
│   │
│   ├── features/               # 📦 业务功能模块（Feature-First）
│   │   ├── auth/
│   │   │   ├── data/           # Repository 实现、数据源
│   │   │   ├── logic/          # ViewModel / Provider
│   │   │   ├── ui/             # Page + 局部 Widget
│   │   │   └── auth_feature.dart # 模块统一导出
│   │   ├── dashboard/
│   │   │   ├── data/
│   │   │   ├── logic/
│   │   │   ├── ui/
│   │   │   │   ├── dashboard_page.dart
│   │   │   │   └── panels/     # ⭐ 面板化子区域
│   │   │   └── dashboard_feature.dart
│   │   └── settings/
│   │       └── ...
│   │
│   ├── routing/                # 🧭 路由系统
│   │   ├── app_router.dart     # GoRouter 主配置
│   │   ├── window_router.dart  # ⭐ 多窗口/对话框路由
│   │   └── guards.dart         # 路由守卫
│   │
│   ├── app.dart                # MaterialApp.router + Shortcuts 根挂载
│   └── main.dart               # 入口 + 多窗口初始化 + DI 组装
│
├── pubspec.yaml
└── analysis_options.yaml