《构建高质量 Flutter 应用：从模块化基础模板到可扩展架构实践》- 适配开源鸿蒙版

• 个人首页： VON

• 鸿蒙系列专栏： 鸿蒙开发小型案例总结

• 综合案例 ：鸿蒙综合案例开发

• 鸿蒙6.0：从0开始的开源鸿蒙6.0.0

• 鸿蒙5.0：鸿蒙5.0零基础入门到项目实战

• Electron适配开源鸿蒙专栏：Electron for OpenHarmony

• 本文章所属专栏：Flutter for OpenHarmony

• 文章AtomGit地址：Template_V1.0

从模块化基础模板到可扩展架构实践

• • [🧱 一、整体架构设计理念](#🧱 一、整体架构设计理念)
  • [📁 二、目录结构详解](#📁 二、目录结构详解)
  • [🚪 三、入口文件：`main.dart`](#🚪 三、入口文件：main.dart)
  • [🎨 四、根组件：`app.dart`](#🎨 四、根组件：app.dart)
  • • 关键设计点：
  • [🎨 五、常量管理：`constants/app_colors.dart`](#🎨 五、常量管理：constants/app_colors.dart)
  • [🧩 六、可复用组件：`widgets/app_bar_title.dart`](#🧩 六、可复用组件：widgets/app_bar_title.dart)
  • [🏠 七、主页实现：`screens/home_screen.dart`](#🏠 七、主页实现：screens/home_screen.dart)
  • • 亮点细节：
  • [🛠️ 八、`pubspec.yaml` 配置说明](#🛠️ 八、pubspec.yaml 配置说明)
  • [🚀 九、未来扩展路线图（2.0+ 升级建议）](#🚀 九、未来扩展路线图（2.0+ 升级建议）)
  • [✅ 总结](#✅ 总结)

🧱 一、整体架构设计理念

该模板遵循 "清晰分层 + 预留扩展" 的原则，目标是：

• ✅ 快速启动一个符合 Flutter 最佳实践的项目；
• ✅ 模块职责分明，便于团队协作；
• ✅ 不引入冗余依赖，保持轻量；
• ✅ 为状态管理、国际化、深色模式、多页面等常见需求预留接口。

这种"骨架先行"的方式非常适合用于企业级项目或长期维护的 MVP（最小可行产品）开发。

---

📁 二、目录结构详解

lib/
├── main.dart               # 应用入口
├── app.dart                # 根组件：主题、路由、全局配置
├── constants/              # 全局常量（颜色、尺寸、字符串等）
│   └── app_colors.dart
├── screens/                # 页面级组件（每个屏幕一个文件）
│   └── home_screen.dart
├── widgets/                # 可复用 UI 组件
│   └── app_bar_title.dart
└── utils/                  # 工具类（日志、格式化、设备判断等）
    └── logger.dart         # 预留

💡 为什么这样分？

• screens/ 与 widgets/ 分离：页面负责业务逻辑，组件专注 UI 复用。
• constants/ 集中管理设计系统变量，便于后期接入 Design Token。
• utils/ 为通用逻辑（如时间格式、网络工具）提供存放地。

---

🚪 三、入口文件：main.dart

import 'package:flutter/material.dart';
import 'app.dart';

void main() {
  runApp(const MyApp());
}

• 使用 runApp() 启动应用；
• 传入根组件 MyApp（无状态，性能更优）；
• 未包裹任何状态管理器（如 ProviderScope），为后续按需引入留白。

🔜 扩展提示：未来若使用 Riverpod，只需在此处改为：

runApp(ProviderScope(child: MyApp()));

---

🎨 四、根组件：app.dart

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  static bool get isDarkMode => false; // ← 预留开关

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(...),
      darkTheme: ThemeData(...),
      themeMode: isDarkMode ? ThemeMode.dark : ThemeMode.light,
      home: const HomeScreen(),
    );
  }
}

关键设计点：

1. 双主题支持：

   • theme：浅色主题；
   • darkTheme：深色主题；
   • themeMode：动态切换依据（当前硬编码为 false，但结构已支持动态切换）。

2. Material 3 支持：

   • useMaterial3: true 确保使用最新 Material Design 规范。

3. 路由预留：

   • 注释中提示可添加 routes 或未来改用 GoRouter。

🔜 扩展路径：

• 将 isDarkMode 改为从 SharedPreferences 读取；
• 通过状态管理（如 Riverpod）监听用户切换操作，动态更新 themeMode。

---

🎨 五、常量管理：constants/app_colors.dart

class AppColors {
  static const primary = Color(0xFF1976D2);
  static const secondary = Color(0xFF424242);
}

• 虽然当前未在主题中使用，但为将来自定义 ThemeData 提供统一颜色源；
• 避免"魔法值"散落在代码各处，提升可维护性。

✅ 最佳实践：后续可结合 Figma 设计系统，生成完整的 AppColors、AppSpacing、AppTextStyles。

---

🧩 六、可复用组件：widgets/app_bar_title.dart

class AppBarTitle extends StatelessWidget {
  final String title;
  const AppBarTitle({super.key, required this.title});

  @override
  Widget build(BuildContext context) {
    return Text(
      title,
      style: Theme.of(context).textTheme.titleLarge?.copyWith(
            fontWeight: FontWeight.bold,
          ),
    );
  }
}

• 抽离 AppBar 标题为独立组件，避免重复写样式；
• 自动适配当前主题（亮/暗）下的文字风格；
• 使用 required 参数确保调用时不会遗漏标题内容。

💡 这种"小而专"的组件是构建大型应用 UI 的基石。

---

🏠 七、主页实现：screens/home_screen.dart

这是一个典型的 StatefulWidget 示例，包含：

• 计数器状态 _counter；
• setState 触发 UI 更新；
• 响应式布局（Center + Column 适配手机/平板）；
• 同时提供 ElevatedButton 和 FloatingActionButton 两种交互方式。

亮点细节：

• 主题感知文本：

  style: Theme.of(context).textTheme.headlineMedium

  确保字体大小、颜色随主题自动变化。

• 语义化结构：

  • 使用 SizedBox 控制间距，而非硬编码 padding；
  • 按钮使用 ElevatedButton.icon，符合 Material 指南。

⚠️ 当前局限：状态仅限本地。一旦页面重建或跳转，计数会重置。

✅ 解决方案：引入状态管理（见下文）。

---

🛠️ 八、pubspec.yaml 配置说明

environment:
  sdk: '>=3.0.0 <4.0.0'  # 使用 Dart 3，支持 records、patterns 等新特性

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.6  # iOS 风格图标（虽未用，但保留兼容性）

dev_dependencies:
  flutter_lints: ^3.0.0   # 官方推荐代码规范检查

• 不预装 Dio、SharedPrefs 等：避免"过度工程"，按需添加；
• 启用 uses-material-design: true：确保 Material 图标可用。

---

测试

🚀 九、未来扩展路线图（2.0+ 升级建议）

功能	实现方式
状态管理	在 main.dart 包裹 ProviderScope，创建 counterProvider（Riverpod）
深色模式切换	将 isDarkMode 改为 StateProvider<bool>，AppBar 添加切换按钮
多页面导航	使用 GoRouter 或 Navigator 2.0 实现命名路由
网络请求	在 utils/api/ 下创建 ApiClient，集成 dio + retrofit
本地存储	引入 shared_preferences，配合 FutureProvider 初始化用户设置
国际化	添加 l10n.yaml，运行 flutter gen-l10n，支持多语言

---

✅ 总结

这个 Flutter 1.0 基础模板虽小，却"五脏俱全"：

• 结构清晰：分层合理，职责单一；
• 主题友好：原生支持亮/暗模式；
• 扩展性强：每一处都为未来升级埋下伏笔；
• 零冗余：没有为了"可能用到"而提前引入复杂库。

它不是功能最全的脚手架，而是最干净、最克制、最面向未来的起点。无论是个人项目、创业 MVP，还是企业级应用，都可以以此为基础，稳步演进。

🌟 建议：将此模板保存为公司/团队的 Flutter Starter Kit，统一开发规范，提升交付效率。