网络、JSON 与本地存储：数据层怎么搭

发请求：http 还是 dio

官方的 http 包够做简单请求。但真实 App 有拦截器（自动加 token）、超时、重试、统一错误处理的需求，用 dio——它是 Flutter 生态的事实标准，相当于 Android 的 Retrofit + OkHttp：

final dio = Dio(BaseOptions(
  baseUrl: 'https://api.school.edu',
  connectTimeout: const Duration(seconds: 10),
));

// 拦截器：每个请求自动带上 token（≈ OkHttp Interceptor）
dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) {
    options.headers['Authorization'] = 'Bearer ${authStore.token}';
    handler.next(options);
  },
  onError: (e, handler) {
    if (e.response?.statusCode == 401) authStore.logout();  // 统一处理登录过期
    handler.next(e);
  },
));

// 用
final resp = await dio.get('/courses');   // resp.data 已经是解析好的 Map/List

dio 还自带 CancelToken——正好补上第 19 章说的「Future 不能取消」：给请求传一个 token，页面销毁时 cancel() 掉。

JSON → 对象：为什么必须代码生成

这是从 Android 过来必须调整的一处。你在 Android 用 Moshi/Gson，一个 @Serializable 或 @JsonClass 注解，运行时反射就把 JSON 转成对象了。Dart 不行，因为它默认没有运行时反射（反射会让 tree-shaking 失效、包体变大，Flutter 权衡后砍掉了它）。

这里值得停下来理解「为什么 Dart 甘愿放弃反射、换来这份麻烦」。反射（运行时读取类的结构）很方便，但它有两个 Dart 无法接受的代价：一是它让 tree-shaking 失效——编译器没法确定哪些类的哪些字段会被反射用到，就只能全部保留，包体积会失控；二是它有运行时开销，每次转换都要动态查类型信息。Flutter 要在手机上做到小包体和快启动，就必须砍掉反射。砍掉之后，「把 JSON 转对象」这件本来靠反射做的事，只能挪到编译期——由一个工具提前把转换代码生成出来。所以 build_runner 不是 Dart 生态不成熟的临时方案，而是「无反射」这个根本取舍的必然结果。想通这一点，你就不会再觉得它是负担，而会把它当成和 Android 的 KSP 一样理所当然的一环。

推荐 freezed——它顺带解决了第 2 章说的「Dart 没有 data class」的痛。一个模型长这样：

import 'package:freezed_annotation/freezed_annotation.dart';
part 'course.freezed.dart';
part 'course.g.dart';

@freezed
class Course with _$Course {
  const factory Course({
    required String id,
    required String name,
    @JsonKey(name: 'teacher_name') required String teacher,   // 字段名映射
    @Default(0) int credits,                                   // 默认值
  }) = _Course;

  factory Course.fromJson(Map<String, dynamic> json) => _$CourseFromJson(json);
}

你写上面这些，然后跑：

$ dart run build_runner build --delete-conflicting-outputs
# 开发时用 watch 模式，改完自动重新生成
$ dart run build_runner watch

它就生成了 Course 的 fromJson/toJson、==/hashCode/copyWith/toString。你调 Course.fromJson(resp.data) 就拿到对象，course.copyWith(credits: 3) 就能改。

本地存储：按数据形态选

不是所有东西都塞一个地方。按「存什么」选：

拼进 Repository：数据层完整长这样

把这一章的东西塞进第 17 章那个 Repository 骨架，一个真实的数据层就成型了：

class CourseRepository {
  CourseRepository(this._dio, this._db);
  final Dio _dio;
  final CourseDb _db;   // drift 生成的数据库

  Future<List<Course>> getCourses({bool refresh = false}) async {
    if (!refresh) {
      final cached = await _db.allCourses();
      if (cached.isNotEmpty) return cached;          // 先给缓存
    }
    try {
      final resp = await _dio.get('/courses');       // 打网络
      final courses = (resp.data as List)
          .map((j) => Course.fromJson(j))            // 生成的解析
          .toList();
      await _db.upsertCourses(courses);              // 回写缓存
      return courses;
    } on DioException catch (e) {
      final cached = await _db.allCourses();
      if (cached.isNotEmpty) return cached;          // 网络失败，退化到缓存
      rethrow;                                        // 缓存也没有，往上抛
    }
  }
}

这就是「离线优先 / 缓存优先」的雏形：能给缓存先给缓存，网络成功就更新，网络失败退回缓存。UI 层（第 19 章的 AsyncValue）只管订阅结果，完全不知道数据经历了这一路。这就是分层的回报。

错误处理：把网络异常变成 UI 能显示的东西

数据层最容易被新手忽略的一半是失败路径。网络会超时、会 401、会返回 500、会断网。如果你让 DioException 一路裸奔到 UI，用户看到的是一片空白或一个红屏。正确做法是在数据层把底层异常翻译成业务能理解的失败类型：

sealed class AppFailure {}
class NetworkFailure extends AppFailure {}      // 断网、超时
class AuthFailure extends AppFailure {}         // 401，该重新登录
class ServerFailure extends AppFailure { final int code; ServerFailure(this.code); }

// Repository 里翻译
Future<List<Course>> getCourses() async {
  try {
    final resp = await _dio.get('/courses');
    return (resp.data as List).map(Course.fromJson).toList();
  } on DioException catch (e) {
    throw switch (e.type) {                        // 第 3 章的 switch 表达式
      DioExceptionType.connectionTimeout ||
      DioExceptionType.connectionError => NetworkFailure(),
      _ when e.response?.statusCode == 401 => AuthFailure(),
      _ => ServerFailure(e.response?.statusCode ?? 0),
    };
  }
}

这样 UI 层拿到的是 AsyncError(:final error)（第 19 章），里面是一个 AppFailure，你就能用第 3 章的模式匹配分别显示「网络不给力，点击重试」「登录过期了」「服务器开小差」——而不是一句冷冰冰的 Exception: ...。好的错误文案是学校 App 口碑的一半，家长和老师对报错很敏感。

分页：列表数据不可能一次全拉

学生名单、历史通知、成绩记录——这些会越来越长，一次拉全会慢会费流量。分页是数据层的标配。最常见的是「翻页令牌 / 页码」模式，配合第 23 章的列表滚动触发：

Future<PageResult<Notice>> getNotices({int page = 1, int size = 20}) async {
  final resp = await _dio.get('/notices', queryParameters: {'page': page, 'size': size});
  return PageResult(
    items: (resp.data['list'] as List).map(Notice.fromJson).toList(),
    hasMore: resp.data['has_more'] as bool,
  );
}

UI 侧监听滚动，快到底时加载下一页（第 23 章会给触发代码）。Riverpod 有专门管分页的模式（把「已加载的页」累积在 Notifier 的 state 里）。别自己在 Widget 里手搓分页状态——「当前第几页、有没有更多、正在加载吗、加载失败了吗」这四个状态搅在一起，塞进 Widget 的 State 会很快失控，这正是第 17 章说的「该提升到 Notifier」的典型。

这一章的一句话

数据层 = dio 发请求 + 代码生成解析 JSON（Dart 无反射，且等了很久的 macro 已在 2025 年取消，就用 build_runner + freezed，顺带补回 data class）+ 按形态选本地存储；把它们拼进 Repository 就得到「缓存优先、网络更新、失败退化」的完整数据层，UI 只管订阅结果。

页面能跳、数据能取了。还剩一个每个 App 都逃不掉、又最容易写卡的东西——长列表。学校 App 里全是列表：课程、通知、学生、成绩。下一章讲 ListView.builder 的回收机制（你熟的 RecyclerView），带一台真的视口回收演示，让你看清「一进页面就卡半秒」是怎么来的、又怎么修。