跨平台开发 / 系统课时

定义接口状态联合类型

定义接口状态联合类型

接口请求通常只会处于一种状态:尚未开始、加载中、成功或失败。如果用多个布尔值和可空字段表示这些状态,就可能组合出“既成功又失败”之类的非法数据。Freezed 联合类型可以把每种状态做成独立分支,让字段集合与状态本身绑定。

学习目标

  • 用 Freezed 构造分支表达互斥的接口状态
  • 让每个状态只携带自己真正需要的数据
  • 使用 Dart 模式匹配穷举状态,减少遗漏和非法组合

让状态决定字段集合

一个常见反模式是给单个类塞入 isLoading、data、error、statusCode 等字段,再靠约定解释哪些字段能同时出现。类型系统并不知道这些约定,因此 isLoading == true 且 data != null 之类的组合仍然可以被创建。

联合类型把约束直接写进构造分支:

状态 允许携带的数据
idle 无
loading startedAt
success user
failure statusCode、message

接口请求联合类型的状态迁移关系

用 Freezed 定义互斥分支

下面示例保存为 bin/state_example.dart。前提是项目已经加入 freezed_annotation,并配置开发依赖 freezed 与 build_runner。各个构造分支使用公开的实现类型,便于 Dart 3 的模式匹配直接识别。

dart
import 'package:freezed_annotation/freezed_annotation.dart';

part 'state_example.freezed.dart';

class User {
  final String name;

  const User(this.name);
}

@freezed
sealed class ProfileRequestState with _$ProfileRequestState {
  const factory ProfileRequestState.idle() = ProfileIdle;

  const factory ProfileRequestState.loading({
    required DateTime startedAt,
  }) = ProfileLoading;

  const factory ProfileRequestState.success({
    required User user,
  }) = ProfileSuccess;

  const factory ProfileRequestState.failure({
    required int statusCode,
    required String message,
  }) = ProfileFailure;
}

String describe(ProfileRequestState state) => switch (state) {
      ProfileIdle() => 'idle',
      ProfileLoading(:final startedAt) =>
        'loading since ${startedAt.toIso8601String()}',
      ProfileSuccess(:final user) => 'success: ${user.name}',
      ProfileFailure(:final statusCode, :final message) =>
        'failure($statusCode): $message',
    };

void main() {
  final states = <ProfileRequestState>[
    const ProfileRequestState.idle(),
    ProfileRequestState.loading(
      startedAt: DateTime.parse('2026-09-18T01:00:00Z'),
    ),
    const ProfileRequestState.success(user: User('Ada')),
    const ProfileRequestState.failure(
      statusCode: 503,
      message: 'Service unavailable',
    ),
  ];

  for (final state in states) {
    print(describe(state));
  }
}

运行代码生成并执行示例:

bash
dart run build_runner build --delete-conflicting-outputs
dart run bin/state_example.dart

预期输出如下。代码生成日志可能因工具版本不同而变化,程序输出应保持一致。

text
idle
loading since 2026-09-18T01:00:00.000Z
success: Ada
failure(503): Service unavailable

这里无法创建“成功但没有 user”的 success,也无法给 idle 塞入错误信息。无效状态不是靠运行时判断排除,而是从构造方式上就不存在。

用穷举匹配承接状态变化

switch 没有默认分支,因此编译器可以检查是否覆盖了所有联合分支。以后新增 cancelled 状态时,原来的 describe 会变成非穷举匹配,编译错误会直接指出哪些处理位置需要同步更新。

这比在多个页面里判断 isLoading、error != null 更可靠,因为状态分支是有限集合,字段也跟随分支收窄。进入 ProfileSuccess 后可以直接访问 user;进入 ProfileFailure 后才会看到 statusCode 和 message。

划清请求状态与接口数据

联合类型适合表达互斥状态,但不要把所有接口字段都塞进状态类。success 应携带已经解析完成的领域模型,failure 只保留错误处理真正需要的信息;原始响应头、任意 JSON 或调试字段应停留在网络层。

如果服务端 JSON 本身也使用 type、status 之类的判别字段返回多种结构,可以再把“响应数据联合类型”单独建模,并在网络层转换为这里的请求状态。这样传输格式变化不会直接污染页面状态,页面也不需要理解原始 JSON 的所有分支。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

定义接口状态联合类型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通