跨平台开发 / 系统课时
跑通首个生成模型
跑通首个生成模型
这一课用一个最小 User 模型把 JSON 序列化链路完整跑通:声明注解与 part 文件、执行代码生成,再验证 JSON → Dart 对象 → JSON。完成后,你会明确哪些代码由自己维护,哪些文件由生成器负责。
学习目标
- 能创建可由
json_serializable生成映射代码的最小模型 - 能执行代码生成并确认
.g.dart文件已经产出 - 能完成一次双向转换,并区分源模型与生成文件的职责
准备代码生成依赖
在 Flutter 项目根目录加入运行时注解包和开发期生成工具:
flutter pub add json_annotation dev:build_runner dev:json_serializable预期输出:
Resolving dependencies...
Changed <N> dependencies!<N> 是本次依赖解析实际变更的包数量,可能因项目已有依赖而不同。最终应在 pubspec.yaml 中看到 json_annotation,并在 dev_dependencies 中看到 build_runner 与 json_serializable。
创建最小 User 模型
创建 lib/models/user.dart。part 'user.g.dart'; 表示当前库会包含同目录下由生成器产出的 part 文件;文件名必须与源文件基名对应。
import 'package:json_annotation/json_annotation.dart';
part 'user.g.dart';
@JsonSerializable()
class User {
const User({
required this.id,
required this.name,
});
final int id;
final String name;
factory User.fromJson(Map<String, dynamic> json) =>
_$UserFromJson(json);
Map<String, dynamic> toJson() => _$UserToJson(this);
}这里真正由你维护的是字段、构造函数、注解以及 fromJson、toJson 的入口声明。_$UserFromJson 和 _$UserToJson 此时还不存在,因此必须先运行生成器。

执行代码生成
在项目根目录执行一次构建:
dart run build_runner build预期结果:命令以成功状态结束,并在 lib/models/ 下生成 user.g.dart。构建日志中的耗时和生成数量属于动态信息,实际值可能不同。
如果修改了模型字段后再次执行同一命令,生成器会根据最新源模型更新映射代码。不要手工编辑 user.g.dart,否则下一次生成时修改可能被覆盖。
验证 JSON 往返
创建 bin/roundtrip.dart,用固定输入验证解码和编码是否一致:
import 'dart:convert';
import '../lib/models/user.dart';
void main() {
const input = <String, dynamic>{
'id': 7,
'name': 'Ada',
};
final user = User.fromJson(input);
print('${user.id}:${user.name}');
print(jsonEncode(user.toJson()));
}预期结果:使用下面的命令执行时,对象字段能正确读取,并能重新编码为 JSON。
dart run bin/roundtrip.dart预期输出:
7:Ada
{"id":7,"name":"Ada"}如果这里出现 _$UserFromJson 未定义或找不到 user.g.dart,优先检查 part 文件名是否与源文件一致、@JsonSerializable() 是否存在,以及生成命令是否在包含 pubspec.yaml 的项目根目录执行。
源模型与生成文件的边界
user.dart 是模型契约:字段变化、构造方式和序列化策略都应从这里修改。user.g.dart 是根据契约推导出的机械映射实现,可以阅读它来排查键名和类型转换,但不应把业务逻辑写进去。
真正需要提交或忽略生成文件,应由团队的版本控制策略决定;无论采用哪种策略,都应保证源码变化后能稳定重新生成,并以往返测试确认 JSON 映射没有偏离接口约定。