跨平台开发 / 系统课时
定义 Freezed 数据类
定义 Freezed 数据类
Freezed 的核心不是简单减少字段代码,而是把模型声明与重复实现分开:你维护构造参数和类型约束,生成器负责不可变实现、copyWith 等样板代码。本节用一个最小模型跑通声明、生成、实例化与复制,并理清源文件、mixin 和生成类型之间的关系。
学习目标
- 写出 Freezed 数据类的标准声明,理解
@freezed、with _$User与工厂构造函数的职责。 - 使用
build_runner生成实现代码,并验证实例化和copyWith正常工作。 - 分清开发者维护的源文件与不应直接修改的生成文件。
最小标准写法
在 Flutter 项目中需要运行时注解包 freezed_annotation,同时把代码生成器 freezed 和 build_runner 放入开发依赖。可以让 Pub 自动选择与当前 SDK 兼容的稳定版本。
flutter pub add freezed_annotation dev:freezed dev:build_runner预期结果
依赖解析成功,pubspec.yaml 中加入 freezed_annotation,并在 dev_dependencies 中加入 freezed 和 build_runner。接着创建 lib/models/user.dart。这是片段示例,需要经过 Freezed 代码生成后再由应用引用。
import 'package:freezed_annotation/freezed_annotation.dart';
part 'user.freezed.dart';
@freezed
abstract class User with _$User {
const factory User({
required String id,
required String name,
@Default(0) int age,
}) = _User;
}@freezed 告诉生成器处理这个类;with _$User 让公开类型使用生成的 mixin;const factory User(...) = _User 把公开构造入口重定向到生成的具体实现 _User。@Default(0) 表示调用方省略 age 时使用默认值。
生成代码并验证
在项目根目录执行 Freezed 生成器:
dart run build_runner build --delete-conflicting-outputs预期结果
构建命令正常结束,lib/models/user.freezed.dart 已生成。生成完成后,可以通过最小入口验证构造和不可变复制。下面的 lib/main.dart 可在已完成代码生成的项目中运行。
import 'models/user.dart';
void main() {
const user = User(
id: 'u-1',
name: 'Ada',
age: 20,
);
final next = user.copyWith(age: 21);
print(user);
print(next);
}执行:
dart run lib/main.dart预期输出
User(id: u-1, name: Ada, age: 20)
User(id: u-1, name: Ada, age: 21)copyWith 返回的是新对象,而不是修改原对象。因此 user.age 仍为 20,next.age 为 21,这正是不可变模型用于状态快照时的重要基础。
源文件、mixin 与生成类型的关系

part 与普通 import 不同:生成文件会成为同一个 Dart library 的一部分,因此生成代码能够实现以 _ 开头的私有类型。源文件负责表达模型契约,生成文件负责提供 mixin、具体实现、copyWith、相等性等机械代码。
重新运行生成器时,user.freezed.dart 可能被覆盖。因此字段、注解和业务方法都应回到源文件维护;如果生成结果有问题,应修改声明或生成配置后重新生成,而不是直接修补生成文件。
什么时候加入 JSON 能力
仅构建 Freezed 数据类时,part 'user.freezed.dart'; 已经足够。只有模型真正需要与 JSON 互转时,才额外加入 part 'user.g.dart';、fromJson 工厂以及相应的 JSON 代码生成依赖。
可以把职责记成一句话:Freezed 负责模型能力,JSON 生成器负责序列化能力。当前只需要不可变数据对象时保持声明最小,等接口映射出现后再扩展 JSON 支持,会让模型和生成链路都更清晰。