跨平台开发 / 系统课时
定义接口状态联合类型
定义接口状态联合类型
接口请求通常只会处于一种状态:尚未开始、加载中、成功或失败。如果用多个布尔值和可空字段表示这些状态,就可能组合出“既成功又失败”之类的非法数据。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 的模式匹配直接识别。
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));
}
}运行代码生成并执行示例:
dart run build_runner build --delete-conflicting-outputs
dart run bin/state_example.dart预期输出如下。代码生成日志可能因工具版本不同而变化,程序输出应保持一致。
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 的所有分支。