跨平台开发 / 系统课时

跑通首个生成模型

跑通首个生成模型

这一课用一个最小 User 模型把 JSON 序列化链路完整跑通:声明注解与 part 文件、执行代码生成,再验证 JSON → Dart 对象 → JSON。完成后,你会明确哪些代码由自己维护,哪些文件由生成器负责。

学习目标

  • 能创建可由 json_serializable 生成映射代码的最小模型
  • 能执行代码生成并确认 .g.dart 文件已经产出
  • 能完成一次双向转换,并区分源模型与生成文件的职责

准备代码生成依赖

在 Flutter 项目根目录加入运行时注解包和开发期生成工具:

bash
flutter pub add json_annotation dev:build_runner dev:json_serializable

预期输出:

text
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 文件;文件名必须与源文件基名对应。

dart
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 此时还不存在,因此必须先运行生成器。

源模型、生成代码与运行时 JSON 往返关系

执行代码生成

在项目根目录执行一次构建:

bash
dart run build_runner build

预期结果:命令以成功状态结束,并在 lib/models/ 下生成 user.g.dart。构建日志中的耗时和生成数量属于动态信息,实际值可能不同。

如果修改了模型字段后再次执行同一命令,生成器会根据最新源模型更新映射代码。不要手工编辑 user.g.dart,否则下一次生成时修改可能被覆盖。

验证 JSON 往返

创建 bin/roundtrip.dart,用固定输入验证解码和编码是否一致:

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。

bash
dart run bin/roundtrip.dart

预期输出:

text
7:Ada
{"id":7,"name":"Ada"}

如果这里出现 _$UserFromJson 未定义或找不到 user.g.dart,优先检查 part 文件名是否与源文件一致、@JsonSerializable() 是否存在,以及生成命令是否在包含 pubspec.yaml 的项目根目录执行。

源模型与生成文件的边界

user.dart 是模型契约:字段变化、构造方式和序列化策略都应从这里修改。user.g.dart 是根据契约推导出的机械映射实现,可以阅读它来排查键名和类型转换,但不应把业务逻辑写进去。

真正需要提交或忽略生成文件,应由团队的版本控制策略决定;无论采用哪种策略,都应保证源码变化后能稳定重新生成,并以往返测试确认 JSON 映射没有偏离接口约定。

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

目录与阅读设置

记录一个想法

跑通首个生成模型

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

登录哪都通