Flutter: Phase 2 综合练习 — ShopApp 核心版
散落的零件组装成引擎——Phase 2 把独立知识组装成完整的应用架构。
📋 前置知识：需要先掌握以下内容
- 第1课：Flutter 简介与环境搭建
- 第2课：Dart 语言速览
- 第3课：Widget 基础
- 第4课：布局系统
- 第5课：StatefulWidget 与交互
- 第6课：Material Design 与常用组件
- 第7课：Phase 1 综合练习 — ShopApp 入门版
- 第8课：导航与路由
- 第9课：表单与输入
- 第10课：列表与滚动
- 第11课：网络请求与 REST API
- 第12课：状态管理 — Riverpod
- 第13课：本地存储
1. 你将学到
- 架构分层：Presentation(Widget) → Application(Notifier) → Infrastructure(Dio+Hive)
- Riverpod 全局状态：cartProvider + authProvider + productProvider 联动
- Dio 拦截器：自动附加 Bearer Token + 401 自动刷新
- Hive 离线缓存：网络失败时展示缓存商品数据
- 完整用户流：浏览 → 加购 → 登录 → 结账 → 订单确认（USD 结算）
2. 一个架构混乱的真实故事
(1) 痛点：面条代码
Bob 的 Phase 1 ShopApp 入门版上线了，但代码一团糟：网络请求散落在 Widget 里，状态管理一半 setState 一半回调，缓存逻辑写在 build 方法里。新增一个功能要改 5 个文件，每次上线都怕改出 bug。100 thousand DAU 的应用用面条代码撑不住了。
(2) 三层架构的解法
Clean Architecture 把代码分为三层：Presentation（UI）、Application（业务逻辑/状态）、Infrastructure（数据源），依赖方向从外到内。
(3) 收益：可维护、可测试、可扩展
Bob 重构为三层架构后，新增支付模块只需加 Notifier + Repository，不动 UI 层。单元测试可以 mock Repository 测试 Notifier，不依赖网络。
3. 三层架构设计
graph TD
subgraph Presentation
HP2[HomePage]
DP2[DetailPage]
CP2[CartPage]
CK[CheckoutPage]
end
subgraph Application Layer
PN2[ProductNotifier]
CN2[CartNotifier]
AN[AuthNotifier]
end
subgraph Infrastructure
DR2[DioRepository]
HR[HiveCache]
SS2[SecureStorage]
end
HP2 --> PN2
DP2 --> CN2
CP2 --> CN2
CK --> AN
PN2 --> DR2
AN --> SS2
PN2 --> HR
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
(1) 分层职责
| 层 | 目录 | 职责 | 依赖 |
|---|---|---|---|
| Presentation | screens/, widgets/ |
UI 渲染 + 用户交互 | Application |
| Application | notifiers/, providers/ |
状态管理 + 业务逻辑 | Infrastructure |
| Infrastructure | repositories/, storage/, network/ |
数据获取 + 持久化 | models |
(2) 项目结构
TEXT
📖 仅展示
lib/
├── main.dart
├── app.dart # MaterialApp.router
├── core/
│ ├── router.dart # GoRouter config
│ ├── network/
│ │ ├── dio_client.dart # Dio instance + interceptors
│ │ └── api_exception.dart # Unified error
│ └── storage/
│ ├── secure_storage.dart
│ ├── hive_cache.dart
│ └── shared_prefs.dart
├── models/
│ ├── product.dart
│ ├── cart_item.dart
│ ├── order.dart
│ └── user.dart
├── notifiers/
│ ├── auth_notifier.dart
│ ├── product_notifier.dart
│ └── cart_notifier.dart
├── repositories/
│ ├── product_repository.dart
│ ├── auth_repository.dart
│ └── order_repository.dart
└── screens/
├── home_page.dart
├── detail_page.dart
├── cart_page.dart
├── checkout_page.dart
└── login_page.dart
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
4. Infrastructure 层实现
▶ 示例
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
：Dio 客户端封装
DART
import 'package:dio/dio.dart';
// ⚙️ **安装依赖**：flutter pub add dio
// 自定义类定义来源：
// - SecureStorage: 见第13课 Flutter Secure Storage
// - AuthInterceptor: 见第11课 Dio Auth 拦截器
class DioClient {
late final Dio _dio;
DioClient({required String baseUrl, required SecureStorage storage}) {
_dio = Dio(BaseOptions(
baseUrl: baseUrl,
connectTimeout: const Duration(seconds: 10),
receiveTimeout: const Duration(seconds: 30),
));
_dio.interceptors.addAll([
AuthInterceptor(storage: storage, dio: _dio),
LogInterceptor(requestBody: true, responseBody: true),
]);
}
Future<Response> get(String path, {Map<String, dynamic>? queryParams}) =>
_dio.get(path, queryParameters: queryParams);
Future<Response> post(String path, {dynamic data}) =>
_dio.post(path, data: data);
Future<Response> put(String path, {dynamic data}) =>
_dio.put(path, data: data);
Future<Response> delete(String path) => _dio.delete(path);
}
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
▶ 示例
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
：Product Repository
DART
import 'package:dio/dio.dart';
// ⚙️ **安装依赖**：flutter pub add dio
// 自定义类定义来源：
// - DioClient: 见本课第4节 Dio 客户端封装
// - ProductCache: 见第13课 Hive 商品缓存
// - Product: 见第11课 json_serializable 模型
class ProductRepository {
final DioClient _client;
final ProductCache _cache;
ProductRepository(this._client, this._cache);
Future<List<Product>> getProducts({int page = 1, String? category}) async {
try {
final response = await _client.get('/products', queryParams: {
'page': page, 'limit': 20, if (category != null) 'category': category,
});
final products = (response.data['items'] as List)
.map((j) => Product.fromJson(j)).toList();
await _cache.saveProducts(products);
return products;
} on DioException {
// Offline fallback
final cached = await _cache.getProducts();
if (cached.isNotEmpty) return cached;
rethrow;
}
}
Future<Product> getProductById(int id) async {
final cached = await _cache.getProductById(id);
if (cached != null) return cached;
final response = await _client.get('/products/$id');
return Product.fromJson(response.data);
}
}
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
5. Application 层实现
▶ 示例
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
：Auth Notifier
DART
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';
// ⚙️ **安装依赖**：flutter pub add flutter_riverpod riverpod_annotation
// ⚙️ **开发依赖**：flutter pub add --dev riverpod_generator build_runner
// 自定义类定义来源：
// - User: 见第12课 @riverpod Auth 示例
// - secureStorageProvider/authRepoProvider: 见第13课存储层
@riverpod
class Auth extends _$Auth {
@override
AsyncValue<User?> build() {
// Check stored token on app start
_checkStoredToken();
return const AsyncData(null);
}
Future<void> _checkStoredToken() async {
final storage = ref.read(secureStorageProvider);
final token = await storage.getAccessToken();
if (token != null) {
state = await AsyncValue.guard(() => ref.read(authRepoProvider).validateToken(token));
}
}
Future<void> login(String email, String password) async {
state = const AsyncLoading();
state = await AsyncValue.guard(() async {
final result = await ref.read(authRepoProvider).login(email, password);
await ref.read(secureStorageProvider).saveTokens(
accessToken: result.accessToken, refreshToken: result.refreshToken, userId: result.user.id,
);
return result.user;
});
}
Future<void> logout() async {
await ref.read(secureStorageProvider).clearAll();
state = const AsyncData(null);
}
}
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
▶ 示例
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
：Cart Notifier（持久化版）
DART
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';
// ⚙️ **安装依赖**：flutter pub add flutter_riverpod riverpod_annotation
// ⚙️ **开发依赖**：flutter pub add --dev riverpod_generator build_runner
// 自定义类定义来源：
// - CartItem: 见第12课 CartNotifier 示例
// - Product: 见第11课 json_serializable 模型
// - cartStorageProvider: 见第13课 Hive 购物车持久化
@riverpod
class Cart extends _$Cart {
@override
List<CartItem> build() {
// Load from local storage on init
_loadFromStorage();
return [];
}
Future<void> _loadFromStorage() async {
final storage = ref.read(cartStorageProvider);
final items = await storage.loadCart();
if (items.isNotEmpty) {
state = items;
}
}
Future<void> _persist() async {
final storage = ref.read(cartStorageProvider);
await storage.saveCart(state);
}
void addItem(Product product) {
final idx = state.indexWhere((i) => i.product.id == product.id);
if (idx >= 0) {
state = [...state]..[idx] = state[idx].copyWith(quantity: state[idx].quantity + 1);
} else {
state = [...state, CartItem(product: product, quantity: 1)];
}
_persist();
}
void updateQuantity(int productId, int qty) {
if (qty <= 0) { removeItem(productId); return; }
state = [for (final i in state) i.product.id == productId ? i.copyWith(quantity: qty) : i];
_persist();
}
void removeItem(int productId) {
state = state.where((i) => i.product.id != productId).toList();
_persist();
}
void clear() { state = []; _persist(); }
}
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
6. Presentation 层实现
▶ 示例
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
：GoRouter 鉴权守卫
DART
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:go_router/go_router.dart';
// ⚙️ **安装依赖**：flutter pub add flutter_riverpod go_router
// 自定义类定义来源：
// - authProvider: 见本课第5节 Auth Notifier
// - MainScaffold: 自定义 Shell 路由容器 Widget
final router = GoRouter(
initialLocation: '/',
redirect: (context, state) {
final authState = ProviderScope.containerOf(context).read(authProvider);
final isLoggedIn = authState.valueOrNull != null;
final isLoginRoute = state.matchedLocation == '/login';
if (!isLoggedIn && !isLoginRoute) return '/login';
if (isLoggedIn && isLoginRoute) return '/';
return null;
},
routes: [
ShellRoute(
builder: (_, __, child) => MainScaffold(child: child),
routes: [
GoRoute(path: '/', builder: (_, __) => const HomePage()),
GoRoute(path: '/cart', builder: (_, __) => const CartPage()),
GoRoute(path: '/profile', builder: (_, __) => const ProfilePage()),
],
),
GoRoute(path: '/product/:id', builder: (_, s) => DetailPage(id: int.parse(s.pathParameters['id']!))),
GoRoute(path: '/checkout', builder: (_, __) => const CheckoutPage()),
GoRoute(path: '/login', builder: (_, __) => const LoginPage()),
],
);
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
▶ 示例
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
：HomePage 消费 Provider
DART
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:go_router/go_router.dart';
// ⚙️ **安装依赖**：flutter pub add flutter_riverpod go_router
// 自定义类定义来源：
// - productProvider/cartItemCountProvider/cartProvider: 见第12课
// - ProductCard: 自定义商品卡片 Widget
class HomePage extends ConsumerWidget {
const HomePage({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final productsAsync = ref.watch(productProvider);
final cartCount = ref.watch(cartItemCountProvider);
return Scaffold(
appBar: AppBar(title: const Text('ShopApp'), actions: [
Badge(count: cartCount, child: IconButton(icon: const Icon(Icons.shopping_cart),
onPressed: () => context.go('/cart'))),
]),
body: productsAsync.when(
loading: () => const Center(child: CircularProgressIndicator()),
error: (err, _) => Center(child: Column(mainAxisAlignment: MainAxisAlignment.center, children: [
Text('Error: $err'), const SizedBox(height: 16),
FilledButton(onPressed: () => ref.read(productProvider.notifier).refresh(), child: const Text('Retry')),
])),
data: (products) => RefreshIndicator(
onRefresh: () => ref.read(productProvider.notifier).refresh(),
child: GridView.builder(gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
crossAxisCount: 2, mainAxisSpacing: 8, crossAxisSpacing: 8, childAspectRatio: 0.7),
itemCount: products.length,
itemBuilder: (_, i) => ProductCard(product: products[i], onAddToCart: () {
ref.read(cartProvider.notifier).addItem(products[i]);
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text('${products[i].name} added to cart'), duration: const Duration(seconds: 1)));
}),
),
),
),
);
}
}
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
7. 完整示例：main.dart 启动流程
DART
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:shared_preferences/shared_preferences.dart';
// ⚙️ **安装依赖**：flutter pub add flutter_riverpod shared_preferences
// 自定义类定义来源：
// - DioClient: 见本课第4节
// - SecureStorage: 见第13课
// - initHive(): 见第13课 Hive 初始化
// - ShopApp: 自定义 MaterialApp Widget
// - sharedPreferencesProvider/dioClientProvider: Riverpod Provider
void main() async {
WidgetsFlutterBinding.ensureInitialized();
// Initialize storage
await initHive();
final prefs = await SharedPreferences.getInstance();
final dioClient = DioClient(baseUrl: 'https://api.shopapp.com/v1', storage: SecureStorage());
runApp(ProviderScope(
overrides: [
sharedPreferencesProvider.overrideWithValue(prefs),
dioClientProvider.overrideWithValue(dioClient),
],
child: const ShopApp(),
));
}
class ShopApp extends ConsumerWidget {
const ShopApp({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
return MaterialApp.router(
title: 'ShopApp',
debugShowCheckedModeBanner: false,
theme: ThemeData(colorSchemeSeed: Colors.blue, useMaterial3: true),
routerConfig: router,
);
}
}
TEXT
📖 仅展示
> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。
❓ 常见问题
Q 三层架构是不是过度设计？
A 小型项目可直接在 Widget 里写逻辑。当项目超过 5 个页面或有多个数据源时，三层架构让代码可维护。
Q Repository 和 Notifier 之间怎么传递错误？
A Repository 抛出 ApiException，Notifier 用 AsyncValue.guard 捕获，UI 用 .when(error:) 展示。
Q 离线缓存过期策略怎么做？
A Hive 存数据时同时存时间戳，读取时检查是否过期（如 1 小时），过期则重新请求。
Q GoRouter 的 redirect 怎么访问 Riverpod 状态？
A 用
ProviderScope.containerOf(context).read(provider) 在 redirect 中读取 Provider。Q Hive 初始化失败怎么办？
A 用 try-catch 包裹 initHive()，失败时清除 Hive 数据重新初始化：
await Hive.deleteBoxFromDisk('products')。Q Token 刷新时并发请求怎么处理？
A 用 Completer 锁：第一个 401 触发刷新，其他 401 请求等 Completer 完成后重试，避免多次刷新。
📖 小节
- 三层架构：Presentation → Application → Infrastructure，依赖方向单向
- Riverpod Notifier 管理业务逻辑和状态，Repository 管理数据获取
- Dio 拦截器统一处理 Token 和 401 刷新
- Hive 缓存实现离线回退，网络失败时展示缓存数据
- GoRouter redirect 实现路由鉴权守卫
📝 作业
- 基础题（难度⭐）：按三层架构重构 Phase 1 项目，将网络请求从 Widget 抽到 Repository。
- 进阶题（难度⭐⭐）：添加 Auth Notifier + SecureStorage，实现登录状态持久化和 401 自动刷新。
- 挑战题（难度⭐⭐⭐）：实现完整用户流：浏览商品(离线缓存) → 加购(持久化) → 登录(Token刷新) → 结账(表单验证) → 订单确认，任何环节网络失败都有优雅降级。
