在 Flutter 中，“可投入生产”到底意味着什么？

每个屏幕都需要的三种状态

过去，我在设计页面时总是只考虑成功的情况，而把加载数据和显示错误信息这些环节当作事后才需要处理的事情。这是一个错误的做法。任何需要从远程服务器获取数据的页面都需要这三种状态：

@override
Widget build(BuildContext context) {
  // 加载中：千万不要让用户看到空白的屏幕。旋转图标可以告诉他们数据正在加载中。
  if (isLoading) {
    return const Center(child: CircularProgressIndicator());
  }

  // 出现错误：向用户说明出了什么问题以及如何解决它。
  // 如果没有重试按钮，那么遇到错误时用户会感到非常沮丧。
  if (error != null) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Text(error!, style: const TextStyle(color: Colors.red)),
          const SizedBox(height: 16),
          ElevatedButton(
            onPressed: () => loadUserwidget.userId),
            child: const Text('重试'),
          ),
        ],
      ),
    );
  }

  // 请求成功：显示用户信息。
  return UserProfileView(user: user!);
}

带有重试按钮的错误提示功能其实并不是什么必备的功能。这种设计会使得用户产生截然不同的反应：有些用户能够在网络暂时中断后继续使用应用，而另一些用户则会认为你的应用出现了故障。

重试逻辑与生产环境中的请求处理流程

移动网络经常会出现短暂性的故障。比如用户在信号不佳的区域行走、进入电梯，或者在发送请求的过程中从WiFi切换到移动数据网络，这些情况都可能导致请求失败。但如果在两秒后重新尝试，请求很可能会成功。

如果没有重试机制，对于用户来说，每一次暂时性的网络故障都会被视作永久性的失败。这种设计显然并不可取。

Future withRetry(  
  Future Function() request, {  
    int maxAttempts = 3;  
    Duration delay = const Duration(seconds: 1);  
  } async {  
    for (int i = 0; i < maxAttempts; i++) {  
      try {  
        return await request();  
      } catch (e) {  
        // 在最后一次尝试时，停止重试并让错误直接传递给调用者。  
        if (i == maxAttempts - 1) rethrow;  

        // 在再次尝试之前等待一段时间，这样可以让暂时性的网络问题得到解决，同时避免给已经负担过重的服务器带来额外的压力。  
        await Future.delayed(delay);  
      }  
    }  

    throw Exception('重试失败');  
  }  

使用方法非常简单：

final user = await withRetry(  
  () => dio.get('/user/$userId'),  
  maxAttempts: 3,  
  delay: const Duration(seconds: 2),  
);  

对于那些流量较大的生产环境应用，可以考虑使用dio_smart_retry。该方案采用了指数级退避策略，每次重试时等待时间会翻倍，这样在网络真正出现故障时，能够更好地减轻服务器的负担。

远程数据的缓存

这里的处理策略非常简单：每当网络请求成功时，就将结果保存到本地。这样，如果下一次请求失败了，系统就可以直接使用之前保存的数据，而不会显示错误页面。

class UserRepository {  
  final Dio _dio;  
  final Box _cache; // 使用Hive缓存库  

  UserRepository(this._dio, this._cache);  

  Future getUser(String userId) async {  
    try {  
      final response = await _dio.get('/user/$userId');  
      final user = User.fromJson(response.data as Map.from(cached));  
      }  

      // 没有缓存数据，只能显示错误信息了。  
      rethrow;  
    }  
  }  
}

保留用户输入的内容

这就是我为之提到的那个入门问题所提供的解决方案：

每当字段内容发生变化时，都会保存用户所输入的所有内容。
_contentController.addListener(() async {
  await _cache.put('draft_post', _contentController.text);
});

// 当页面重新加载时，会恢复之前保存的草稿内容。
@override
void initState() {
  super.initState();
  final draft = _cache.get('draft_post') as String?;
  if (draft != null && draft.isNotEmpty) {
    _contentController.text = draft;
  }
}

// 当用户成功提交内容后，会清除之前的草稿。
Future _submit() async {
  await _repository.createPost(_contentController.text);
  await _cache.delete('draft_post');
}

这三行代码能够确保用户的输入不会丢失。对于任何需要花费超过一分钟才能填写完的表单来说，这种做法都是非常必要的。

我用于实现本地数据持久化的工具包包括：

1. Hive：适用于简单的键值存储场景

2. Isar：当我需要执行更复杂的查询时使用

3. sqflite：用于处理关系型数据

4. shared_preferences：专门用于存储用户设置，不适用于存储其他重要数据

大规模状态管理

setState这个方法本身是没有问题的。我之所以要明确说明这一点，是因为在Flutter社区中，有些人倾向于认为使用setState总是错误的。但对于那些仅用于处理简单的UI状态变化（比如按钮状态的切换、表单字段的验证提示等）来说，setState确实是最佳选择。

然而，当您将setState用于管理多个组件共同依赖的状态、异步操作，或者需要确保状态在页面导航过程中仍然有效的场景时，问题就会出现了。我曾经遇到过这些情况，下面是具体会出现的问题：

这段setState代码位于组件树的高层位置。
// 它下面的所有组件都会被重新构建——包括那些与这次状态变化无关的、计算成本较高的组件。
setState(() {
  currentUser = updatedUser;
});

随着应用程序规模的扩大，这种问题会变得更加严重。重新构建操作会在整个应用系统中传播开来，各种副作用也会以不可预测的方式出现。最终，您会花费更多的时间来调试状态变化相关的问题，而不是去开发新的功能。

转向Riverpod框架

在我的第二个项目中遇到了这些瓶颈之后，我立即改用了Riverpod框架，从此再没有后悔过这个决定。Riverpod的核心理念非常简单：状态数据被存储在组件之外，各个组件只需订阅自己真正需要的状态信息即可。

@riverpod
class UserNotifier extends _$UserNotifier {
  @override
  AsyncValue build(String userId) {
    _load();
    return const AsyncValue.loading();
  }

  Future _load() async {
    state = const AsyncValueLoading();

    // AsyncValue.guard会负责执行异步操作，并在操作成功时将结果封装到AsyncValue.data中，
    // 在操作失败时则抛出异常。这样就可以避免每次都需要编写try/catch代码了。
    state = await AsyncValue_guard(
      () => ref.read(userRepositoryProvider).getUser(userId),
    );
  }

  Future refresh() => _load();
}

在这个小部件中：

@override
Widget build(BuildContext context) {
  // ref.watch会使得这个小部件与通知机制关联起来。
  // 只有当userAsync的状态发生变化时，才会重新构建这个小部件；
  // 而应用程序其他地方的状态变化并不会导致它被重新构建。
  final userAsync = ref.watch(userNotifierProvider(widget.userId));

  return userAsync.when(
    // when()强制要求你必须处理加载、出错以及数据更新这些情况。
    // 如果忽略了其中任何一种情况，都会导致编译错误，而不会在运行时才出现问题。
    loading: () => const CircularProgressIndicator(),
    error: (e, _) => Text('Error: $e'),
    data: (user) => UserProfileView(user: user),
  );
}

我最喜欢的一点是：when()这个机制确保了如果忽略了加载状态或错误处理，就会产生编译错误。编译器会强制要求开发者必须处理好这些情况。

不可变的状态

在实时聊天功能中，有一件事让我遇到了很大的麻烦：那就是在应用程序的多个部分之间共享一个可变的列表。

List〈Message〉 messages = [];

// 后来，在不同的地方对这个列表进行了操作：
messages.add(newMessage);       // 在socket处理逻辑中
messages.removeAt(0);          // 在分页功能中
messages.insert(0, pinned);    // 在推送通知功能中

有时候，会有消息出现两次，或者随机地从列表中消失；要找出到底是哪种操作导致了这种问题，真的非常麻烦。解决办法就是永远不要修改这个列表的内容，而应该每次都需要创建一个新的列表：

// 旧的列表保持不变，新的状态就是一个新的列表。
// 所有的变化都是明確的，而且可以追踪到。
state = [...state, newMessage];

在刚开始的时候，你可能觉得这只是一件小事，但当你花了两个小时去调试那些由于列表状态改变而引发的错误时，你就会意识到这件事其实非常重要。

小部件的重新构建与渲染性能

Flutter的速度确实很快。但是，如果不必要的重新构建操作频繁发生，在低端设备上，这种影响就会变得非常明显。

常量小部件可以完全避免重新构建

const关键字告诉Dart，这个小部件可以在编译时就被创建出来，并且可以被无限次地重复使用。任何内容永远不会发生变化的小部件，都适合使用这种写法。

// 不使用const关键字时：每次父小部件重新构建时，都会创建一个新的Text实例，
// 虽然它的内容其实从未发生过变化。
Text('Welcome to the app')

// 使用const关键字时：Flutter会重复使用同一个Text实例。
// 因此不会发生重新构建操作，也不会有内存分配的开销。
const Text('Welcome to the app')

这听起来可能是一件小事，但在一个包含许多静态元素的大型小部件结构中，这种写法的累积效果是非常显著的。养成使用常量小部件的习惯是非常重要的。

尽量缩小重新构建的范围

当setState方法被调用在小部件结构的较高层级时，它下面的所有小部件都会被重新构建——即使这些小部件与状态变化无关也是如此。解决办法是将状态变更的信息尽可能向下传递，最好是将它们放入一个单独的小部件中进行处理。

// 问题在于：计数器的状态存储在父组件中，因此每次调用 setState 都会重新构建整个子树——包括与计数器无关的
// ExpensiveListWidget 组件。
class _BadExampleState extends State {
  int _counter = 0;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('计数：$_counter'),
        ElevatedButton(
          onPressed: () => setState(() => _counter++),
          child: const Text('增加'),
        ),
        const ExpensiveListWidget(), // 不必要的重新构建
      ],
    );
  }
}

现在，只有当计数值发生变化时，ExpensiveListWidget才会被重新构建，其他组件则不会受到影响。

适用于长度未知的列表的 ListView.builder

Column组件会预先创建列表中的所有项目，无论这些项目是否真正可见。对于一个包含200个项目的列表来说，在用户开始滚动之前，系统就会创建200个对应的 widgets。

// 这种方式会预先创建列表中的所有项目。
// 对于一个包含200个项目的列表，第一次渲染时就会创建200个 widgets，
// 而其中大部分在用户查看屏幕时其实并不可见。
Column(
  children: items.map((item) => ItemCard(item: item)).ToList(),
)

// 这种方式只会创建可见的项目，同时还会预留一些缓冲空间。
// 即使列表中有10,000个项目，使用 ListView.builder 也不会消耗比处理10个项目更多的内存。
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) {
    return ItemCard(items[index]);
  },
)

ListView.builder并不是为处理大型列表而设计的优化方案。对于那些长度未知或会变化的列表来说，它才是正确的默认选择。只有当我确定列表中的项目数量始终很少时，才会使用Column组件和映射列表。

异步操作中的陷阱以及被销毁的 widgets带来的问题

这种错误在开发阶段是完全看不到的，但一旦进入生产环境，就会频繁出现。

假设某个异步操作开始执行了，但在操作完成之前用户已经离开了当前页面，那么当操作最终完成并尝试调用 setState 时，会发现对应的 widget 已经被销毁了，从而导致错误发生。

Future _loadData() async {
  final data = await repository.fetchData();

  // 如果在等待数据的过程中用户离开了页面，
  // 这个 widget 就会消失，此时调用 setState 会抛出错误：
  // "setState() called after dispose()"
  setState(() => this.data = data);
}

解决这个问题的方法只需要一行代码：

Future _loadData() async {
  final data = await repository.fetchData();

  // 当 widget 还在页面上显示时，mounted 的值为 true；
  // 而在 widget 被销毁后，mounted 的值会变为 false。
  if (!mounted) return;

  setState(() => this.data = data);
}

现在，我在每次使用 await 后都会自动进行这个检查，然后再调用 setState。这种做法很快就成了我的习惯。

切勿在构建过程中创建Future对象

这是一个很容易被忽视的问题。当你在build方法内部直接创建Future对象时，每次重新构建应用时都会生成一个新的Future对象——这意味着FutureBuilder会将其视为每一次新的操作，并因此不必要的地重置到加载状态。

// 错误的做法：每次重建应用都会生成一个新的Future对象。
// FutureBuilder会认为每次都是不同的Future对象，
// 从而不必要的地重置到加载状态。
@override
Widget build(BuildContext context) {
  return FutureBuilder(
    future: repository.fetchUser(userId), // 每次重建都会生成新的Future对象
    builder: (context, snapshot) { ... },
  );
}

// 正确的做法：在 initState方法中只创建一次Future对象。
// FutureBuilder会在多次重建过程中使用同一个Future对象。
late final Future _userFuture;

@override
void initState() {
  super.initState();
  _userFuture = repository.fetchUser(widget.userId);
}

@override
Widget build(BuildContext context) {
  return FutureBuilder(
    future: _userFuture,
    builder: (context, snapshot) { ... },
  );
}

将耗时较长的操作从UI线程中分离出来

Dart会在主隔离线程上渲染用户界面。任何会占用大量CPU资源并导致渲染进程受阻的操作，都可能导致帧率下降。

// 在主隔离线程上同步解析庞大的API响应数据，
// 在性能较弱的设备上，这一操作可能会导致50到200毫秒的渲染延迟。
final users = (response.data as List)
    .map((json) => User.fromJson(json))
    .ToList();

// `compute()`方法会在单独的隔离线程中执行该函数。
// 这样主隔离线程就可以继续进行渲染工作。
// 注意：这个函数必须是顶级函数或静态函数，
// 因为捕获局部状态的闭包无法被发送到另一个隔离线程中。
final users = await compute.parseUsers, response.data);

List parseUsers(dynamic data) {
  return (data as List)
      .map((json) => User.fromJson(json as Map

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  // 捕捉 Flutter 框架中的错误——比如组件构建错误、渲染错误等
  FlutterError onError =
      FirebaseCrashlytics.instance.recordFlutterFatalError;

  // 捕捉 Flutter 无法捕捉到的异步代码中的错误——例如事件处理程序或定时器中出现的错误
  PlatformDispatcher.instance.onError = (error, stack) {
    FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
    return true;
  };

  runApp(const MyApp());
}

// 这是我以前编写代码的方式。如果 submitOrder 方法抛出异常，
// 用户根本不会知道发生了什么，我也不知道。
await api.submitOrder(order);

// 现在我是这样编写的：
try {
  await api.submitOrder(order);
  setState(() => orderStatus = OrderStatus.confirmed);
} catch (e, stackTrace) {
  // recordError 方法会将完整的异常信息及堆栈跟踪发送到 Crashlytics，
  // 并自动附加设备信息和用户的最近操作记录。
  FirebaseCrashlytics.instance.recordError(e, stackTrace);
  setState(() => orderStatus = OrderStatus_FAILED);
}

FirebaseCrashlytics.instance.log('用户打开了结账页面');
FirebaseCrashlytics.instance.log('支付页面已显示');
FirebaseCrashlytics.instance.log('用户完成了支付操作');
// 在这里发生了崩溃——现在我清楚地知道事件发生的具体顺序了

test('折扣百分比的计算是否正确', () {
  final result = calculateDiscountedPrice(
    price: 100.0,
    discountPercent: 10,
  );

  // 100.00 元打九折应该等于 90.00 元
  expect(result, equals(90.0));
});

test('当折扣百分比为负数时是否会抛出异常', () {
  expect(
    () => calculateDiscountedPrice(price: 100, discountPercent: -5),
    throwsA(isA<ArgumentError>>()),
  );
});

testWidgets('在加载失败时显示错误信息并提供重试按钮',
    (tester) async {
  final mockRepo = MockUserRepository();
  when(mockRepo.getUser(any)).thenThrow(Exception('网络错误'));
  
  await tester.pumpWidget(
    ProviderScope(
      overrides: [
        userRepositoryProvider.overrideWithValue(mockRepo),
      ],
      child: const MaterialApp(home: ProfileScreen(userId: 'test')),
    ),
  );

  // pumpAndSettle会等待所有动画效果及异步操作完成后再进行断言。
  await tester.pumpAndSettle();

  expect(find.text('无法加载个人资料，请重试。'), findsOneWidget);
  expect(find.text('再试一次'), findsOneWidget);
});

lib/
  features/
    profile/
      data/
        profile_repository.dart     # 负责网络请求与缓存逻辑
      domain/
        user.dart                   # 简洁的数据模型
      presentation/
        profile_screen.dart         # UI小部件
        profile notifier.dart       # 负责状态更新

class ProfileRepository {
  final Dio _dio;
  final Box _cache;

  ProfileRepository(this._dio, this._cache);

  Future getUser(String userId) async {
    try {
      final response = await withRetry(
        () => _dio.get('/users/$userId'),
      );

      final user = User.fromJson(
        response.data as Map,
      );

      // 将成功的响应结果缓存起来，以便在离线情况下使用。
      await _cache.put('user_$userId', user.toJson());

      return user;
    } on DioException catch (e) {
      final cached = _cache.get('user_$userId');

      if (cached != null) {
        return User.fromJson(Map.from(cached));
      }

      if (e.type == DioExceptionType.connectionError) {
        throw NoInternetException();
      }

      throw ServerException(e.response?.statusCode ?? 0);
    }
  }

  Future updateDisplayName(String userId, String name) async {
    await withRetry(
      () => _dio.patch('/users/$userId', data: {'displayName': name}),
    );

    // 清除缓存，以便下次读取时能够获取到最新数据。
    await _cache.delete('user_$userId');
  }
}

@riverpod
class ProfileNotifier extends _$ProfileNotifier {
  @override
  AsyncValue build(String userId) {
    _load();
    return const AsyncValue.loading();
  }

  Future _load() async {
    state = const AsyncValueloading();
    state = await AsyncValue.guard(
      () => ref.read(profileRepositoryProvider).getUser(userId),
    );
  }

  Future refresh() => _load();

  Future updateName(String newName) async {
    final current = state.valueOrNull;
    if (current == null) return;

    try {
      await ref
          .read(profileRepositoryProvider)
          .updateDisplayName(userId, newName);

      // 立即更新用户界面，无需等待页面重新加载。
      state = AsyncValue.data(current.copyWith(displayName:出新名));
    } catch (e, st) {
      FirebaseCrashlytics.instance.recordError(e, st);
      // 如果更新失败，恢复之前的状态。
      state = AsyncValue.data(current);
      rethrow;
    }
  }
}