跨平台开发 / 系统课时
管理 part 文件与生成代码
管理 part 文件与生成代码
Freezed 与 json_serializable 会把一个模型拆成手写源文件和两个生成文件。管理重点不是记住后缀,而是明确谁引用谁、谁可以修改,以及团队是否把生成产物提交到仓库,避免生成文件被误改或长期失配。
学习目标
- 理解
.freezed.dart、.g.dart与源模型文件的引用关系 - 建立不手改生成文件的目录与维护规则
- 根据应用仓库、CI 和发布方式选择生成代码的提交策略
三个文件如何组成一个模型
假设模型文件是 lib/models/user.dart。user.dart 是唯一需要手写和评审的来源;user.freezed.dart 由 Freezed 生成不可变模型、copyWith 等实现;user.g.dart 由 JSON 生成器提供 fromJson、toJson 辅助代码。两份生成文件通过 part 声明加入同一个 Dart library。

片段示例:下面是完整的 lib/models/user.dart 模型文件,前提是项目已经配置 freezed_annotation、json_annotation、freezed、json_serializable 与 build_runner。
import 'package:freezed_annotation/freezed_annotation.dart';
part 'user.freezed.dart';
part 'user.g.dart';
@freezed
abstract class User with _$User {
const factory User({
required String id,
required String name,
}) = _User;
factory User.fromJson(Map<String, dynamic> json) =>
_$UserFromJson(json);
}这里最容易出错的是文件名。源文件改名后,两个 part 路径也要同步改;不要把生成文件移到另一个目录后继续手写路径,因为生成器会按照源文件与 Builder 规则管理输出位置。
让生成器拥有生成文件
修改模型后运行一次生成:
dart run build_runner build预期结果:
命令以退出码 0 结束;对应的 .freezed.dart 与 .g.dart 文件被创建或更新。具体构建日志会随 build_runner 版本和项目规模变化。如果生成代码不符合预期,应先修改注解、字段声明或生成器配置,然后重新生成。直接编辑 .freezed.dart 或 .g.dart 只能得到短暂效果,下次运行生成器时改动会被覆盖。
目录约定与提交策略
最稳妥的目录约定是让源模型和它的生成 part 文件保持同一目录、同一基础文件名。例如 user.dart 对应 user.freezed.dart 与 user.g.dart。这样重命名、搜索和代码评审都更容易,也与 part 的相对路径保持一致。
生成代码是否提交 Git 没有唯一答案,但团队必须统一。应用仓库可以选择提交生成文件,这样拉取后即可分析和构建;也可以忽略生成文件,但 CI 必须在 analyze、测试或打包前执行代码生成。若发布 Dart/Flutter package,则运行时或编译时必需的生成源码必须包含在实际发布内容中,不能假设使用者会替你执行生成器。
如果选择提交生成文件,推荐在 CI 里重新生成后检查仓库是否仍有差异;如果选择不提交,则应在 .gitignore 和 CI 脚本中明确这一点。最不稳定的做法是部分开发者提交、部分开发者忽略,最终会产生大量无意义冲突。
遇到异常先检查引用关系
出现“找不到 _$UserFromJson”“找不到 _$User”或生成文件缺失时,优先检查源文件里的 part 声明、注解和生成命令是否一致,再看依赖版本与 Builder 配置。只要坚持“源文件负责声明,生成器负责实现,生成文件不手改”,大多数 part 文件问题都能在源头解决。