跨平台开发 / 系统课时

管理 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。

Freezed 源文件与生成文件关系

片段示例:下面是完整的 lib/models/user.dart 模型文件,前提是项目已经配置 freezed_annotation、json_annotation、freezed、json_serializable 与 build_runner。

dart
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 规则管理输出位置。

让生成器拥有生成文件

修改模型后运行一次生成:

bash
dart run build_runner build

预期结果:

text
命令以退出码 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 文件问题都能在源头解决。

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

目录与阅读设置

记录一个想法

管理 part 文件与生成代码

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

登录哪都通