跨平台开发 / 系统课时

定义 Freezed 数据类

定义 Freezed 数据类

Freezed 的核心不是简单减少字段代码,而是把模型声明与重复实现分开:你维护构造参数和类型约束,生成器负责不可变实现、copyWith 等样板代码。本节用一个最小模型跑通声明、生成、实例化与复制,并理清源文件、mixin 和生成类型之间的关系。

学习目标

  • 写出 Freezed 数据类的标准声明,理解 @freezed、with _$User 与工厂构造函数的职责。
  • 使用 build_runner 生成实现代码,并验证实例化和 copyWith 正常工作。
  • 分清开发者维护的源文件与不应直接修改的生成文件。

最小标准写法

在 Flutter 项目中需要运行时注解包 freezed_annotation,同时把代码生成器 freezed 和 build_runner 放入开发依赖。可以让 Pub 自动选择与当前 SDK 兼容的稳定版本。

bash
flutter pub add freezed_annotation dev:freezed dev:build_runner

预期结果

text
依赖解析成功,pubspec.yaml 中加入 freezed_annotation,并在 dev_dependencies 中加入 freezed 和 build_runner。

接着创建 lib/models/user.dart。这是片段示例,需要经过 Freezed 代码生成后再由应用引用。

dart
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 生成器:

bash
dart run build_runner build --delete-conflicting-outputs

预期结果

text
构建命令正常结束,lib/models/user.freezed.dart 已生成。

生成完成后,可以通过最小入口验证构造和不可变复制。下面的 lib/main.dart 可在已完成代码生成的项目中运行。

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);
}

执行:

bash
dart run lib/main.dart

预期输出

text
User(id: u-1, name: Ada, age: 20)
User(id: u-1, name: Ada, age: 21)

copyWith 返回的是新对象,而不是修改原对象。因此 user.age 仍为 20,next.age 为 21,这正是不可变模型用于状态快照时的重要基础。

源文件、mixin 与生成类型的关系

Freezed 源文件、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 支持,会让模型和生成链路都更清晰。

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

目录与阅读设置

记录一个想法

定义 Freezed 数据类

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

登录哪都通