从零构建可扩展 Flutter 应用：v1.0 到 v2.0 架构演进详解

将 AppBar 标题封装为独立 widget，提高复用性。使用 Theme.of(context) 获取当前主题样式，自动适配深浅色。通过 required this.title 强制传参，避免空值错误。

4. lib/screens/home_screen.dart —— 主页面

import 'package:flutter/material.dart';
import '../widgets/app_bar_title.dart';

class HomeScreen extends StatefulWidget {
  const HomeScreen({super.key});

  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  int _counter = 0;

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const AppBarTitle(title: 'My App'),
        centerTitle: true,
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text('Welcome to My App v1.0!', style: TextStyle(fontSize: 20, fontWeight: FontWeight.w500)),
            const SizedBox(height: 24),
            const Text('You have pushed the button this many times:'),
            Text('$_counter', style: Theme.of(context).textTheme.headlineMedium),
            const SizedBox(height: 32),
            ElevatedButton.icon(
              onPressed: _incrementCounter,
              icon: const Icon(Icons.add),
              label: const Text('Increment'),
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

使用 StatefulWidget 管理局部计数器状态。_counter 是私有变量，通过 setState 触发 UI 更新。页面结构清晰：AppBar + Body + FloatingActionButton。局限性：状态无法跨页面共享，重启后丢失——这正是 v2.0 要解决的问题。

⚙️ 第二阶段：v2.0 —— 引入 Riverpod，实现可扩展架构

✅ 升级目标

• 状态全局可访问
• 支持深色/浅色/系统主题动态切换
• 计数器数据持久化（重启不丢失）
• 解耦 UI 与逻辑

📦 新增依赖（pubspec.yaml）

dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: ^2.5.1 # 状态管理
  shared_preferences: ^2.2.2 # 本地存储

运行命令 flutter pub get 安装依赖。

📁 v2.0 项目结构

lib/
├── main.dart
├── app.dart
├── constants/app_colors.dart (可选)
├── providers/
│   ├── app_theme_provider.dart
│   └── counter_provider.dart
├── screens/home_screen.dart
├── widgets/
│   ├── app_bar_title.dart
│   └── theme_toggle_button.dart
└── utils/logger.dart (预留)

1. lib/main.dart —— 包裹 ProviderScope

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // 必须在使用 shared_preferences 前调用
  runApp(const ProviderScope(
    // Riverpod 的根容器
    child: MyApp(),
  ));
}

ProviderScope 是 Riverpod 的上下文提供者，必须包裹整个应用。WidgetsFlutterBinding.ensureInitialized() 是使用平台通道（如 SharedPreferences）的必要步骤。

2. lib/providers/app_theme_provider.dart —— 主题状态管理

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

enum AppThemeMode { light, dark, system }

// 用户选择的主题模式（可持久化）
final appThemeModeProvider = StateProvider<AppThemeMode>((ref) {
  return AppThemeMode.light;
  // TODO: 未来从 SharedPreferences 读取
});

// 计算实际生效的 ThemeMode
final effectiveThemeModeProvider = Provider<ThemeMode>((ref) {
  final mode = ref.watch(appThemeModeProvider);
  switch (mode) {
    case AppThemeMode.light:
      return ThemeMode.light;
    case AppThemeMode.dark:
      return ThemeMode.dark;
    case AppThemeMode.system:
      return ThemeMode.system;
  }
});

StateProvider 用于简单状态（如枚举、bool、int）。effectiveThemeModeProvider 是一个派生状态，根据用户选择计算出 ThemeMode。未来可轻松扩展：将初始值从 SharedPreferences 读取，实现'记住用户偏好'。

3. lib/providers/counter_provider.dart —— 持久化计数器

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:shared_preferences/shared_preferences.dart';

final counterProvider = StateNotifierProvider<CounterNotifier, int>((ref) {
  return CounterNotifier();
});

class CounterNotifier extends StateNotifier<int> {
  CounterNotifier() : super(0) {
    _loadFromPrefs(); // 初始化时加载
  }

  Future<void> _loadFromPrefs() async {
    final prefs = await SharedPreferences.getInstance();
    final saved = prefs.getInt('counter') ?? 0;
    state = saved; // 触发 UI 更新
  }

  Future<void> increment() async {
    state++; // 自动通知监听者
    final prefs = await SharedPreferences.getInstance();
    await prefs.setInt('counter', state); // 保存
  }

  Future<void> reset() async {
    state = 0;
    final prefs = await SharedPreferences.getInstance();
    await prefs.setInt('counter', state);
  }
}

StateNotifierProvider 适合管理复杂状态逻辑（如异步、验证、副作用）。state = newValue 会自动通知所有监听者重建 UI。数据在 increment() 和 reset() 中自动持久化到设备存储。

4. lib/widgets/theme_toggle_button.dart —— 主题切换按钮

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../providers/app_theme_provider.dart';

class ThemeToggleButton extends ConsumerWidget {
  const ThemeToggleButton({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final currentMode = ref.watch(appThemeModeProvider);
    return PopupMenuButton<AppThemeMode>(
      onSelected: (mode) => ref.read(appThemeModeProvider.notifier).state = mode,
      itemBuilder: (context) => [
        PopupMenuItem(
          value: AppThemeMode.light,
          child: Row(
            children: [
              Icon(Icons.light_mode, color: Colors.yellow[700]),
              const SizedBox(width: 8),
              const Text('Light'),
            ],
          ),
        ),
        PopupMenuItem(
          value: AppThemeMode.dark,
          child: Row(
            children: [
              Icon(Icons.dark_mode, color: Colors.blue[300]),
              const SizedBox(width: 8),
              const Text('Dark'),
            ],
          ),
        ),
        PopupMenuItem(
          value: AppThemeMode.system,
          child: Row(
            children: [
              Icon(Icons.settings, color: Colors.grey),
              const SizedBox(width: 8),
              const Text('System'),
            ],
          ),
        ),
      ],
      child: IconButton(
        icon: currentMode == AppThemeMode.dark
            ? const Icon(Icons.dark_mode)
            : const Icon(Icons.light_mode),
        tooltip: 'Switch theme',
      ),
    );
  }
}

ConsumerWidget 允许使用 ref.watch 监听状态变化。ref.read(...) 用于写入状态（不监听变化，性能更好）。图标根据当前主题动态切换，提升用户体验。

5. lib/app.dart —— 使用 Riverpod 主题

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'screens/home_screen.dart';
import 'providers/app_theme_provider.dart';

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

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final themeMode = ref.watch(effectiveThemeModeProvider); // 监听主题变化
    return MaterialApp(
      title: 'My App',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(useMaterial3: true, colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue)),
      darkTheme: ThemeData(
        useMaterial3: true,
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue, brightness: Brightness.dark),
      ),
      themeMode: themeMode,
      home: const HomeScreen(),
    );
  }
}

关键点：MyApp 从 StatelessWidget 变为 ConsumerWidget，以便监听 effectiveThemeModeProvider。当用户切换主题时，MaterialApp 自动重建，应用新主题。

6. lib/screens/home_screen.dart —— 使用 Riverpod 状态

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../providers/counter_provider.dart';
import '../widgets/app_bar_title.dart';
import '../widgets/theme_toggle_button.dart';

class HomeScreen extends ConsumerWidget {
  const HomeScreen({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider); // 自动监听计数器变化
    return Scaffold(
      appBar: AppBar(
        title: const AppBarTitle(title: 'My App v2.0'),
        centerTitle: true,
        actions: [const ThemeToggleButton()], // 主题切换按钮
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Text('Welcome to My App!', style: TextStyle(fontSize: 20, fontWeight: FontWeight.w500)),
            const SizedBox(height: 24),
            const Text('Counter (persisted):'),
            Text('$count', style: Theme.of(context).textTheme.headlineMedium),
            const SizedBox(height: 32),
            ElevatedButton.icon(
              onPressed: () => ref.read(counterProvider.notifier).increment(),
              icon: const Icon(Icons.add),
              label: const Text('Increment'),
            ),
            TextButton.icon(
              onPressed: () => ref.read(counterProvider.notifier).reset(),
              icon: const Icon(Icons.refresh),
              label: const Text('Reset'),
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => ref.read(counterProvider.notifier).increment(),
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

关键改进：不再使用 StatefulWidget，UI 与状态完全解耦。ref.watch(counterProvider) 自动更新计数显示。按钮通过 ref.read(...).increment() 触发状态变更。重启应用后，计数器值依然保留！

🔮 未来扩展路径

这个 v2.0 架构已为以下能力预留'插槽'：

例如，添加天气 API 只需：

// providers/weather_provider.dart
final weatherProvider = FutureProvider<Weather>((ref) async {
  final res = await http.get(Uri.parse('https://api.weather.com/...'));
  return Weather.fromJson(json.decode(res.body));
});

然后在 UI 中优雅处理加载/错误/数据状态：

ref.watch(weatherProvider).when(
  data: (weather) => Text('${weather.temp}°C'),
  loading: () => CircularProgressIndicator(),
  error: (err, _) => Text('Failed to load'),
);

✅ 总结

• v1.0 是一个规范、可交付的起点，避免'脏快糙'陷阱。
• v2.0 通过 Riverpod + 模块化设计，实现了状态集中管理、UI 逻辑解耦、数据持久化。
• 所有代码均可直接复制使用，并具备良好的扩展性。

好的架构不是一开始就复杂的，而是从第一天起就为'变化'做好准备。

📥 附录：完整文件清单

你可以按以下顺序创建文件：

1. lib/main.dart
2. lib/app.dart
3. lib/constants/app_colors.dart（可选）
4. lib/providers/app_theme_provider.dart
5. lib/providers/counter_provider.dart
6. lib/screens/home_screen.dart
7. lib/widgets/app_bar_title.dart
8. lib/widgets/theme_toggle_button.dart
9. lib/utils/logger.dart（可留空）

然后更新 pubspec.yaml 并运行 flutter pub get。