跨平台开发 / 系统课时
配置类级 JSON 生成规则
配置类级 JSON 生成规则
@JsonSerializable 不只是“开启生成”的标记,它还可以在单个模型上覆盖项目级默认策略。本课用键名转换和空值输出两个规则演示配置优先级,并通过生成代码与运行结果反查配置是否真正生效。
学习目标
- 能区分
build.yaml项目默认值与@JsonSerializable类级显式配置 - 能使用常见类级选项控制 JSON 键名和空值输出
- 能从
.g.dart与运行结果判断生成规则是否生效
先设置项目默认策略
当大多数模型都遵循同一规则时,可以在项目根目录的 build.yaml 给 json_serializable 设置默认值。下面让字段默认转为 snake_case,并省略值为 null 的字段:
targets:
$default:
builders:
json_serializable:
options:
field_rename: snake
include_if_null: false这段配置本身不会生成代码;保存后需要重新运行生成器。未在类注解中显式指定的选项,会继续使用这里的项目默认值。
用类级配置覆盖默认值
创建 lib/models/user_profile.dart。这个模型显式要求 kebab-case,并要求即使字段为 null 也输出,因此会覆盖 build.yaml 中对应的两个默认值。
import 'package:json_annotation/json_annotation.dart';
part 'user_profile.g.dart';
@JsonSerializable(
fieldRename: FieldRename.kebab,
includeIfNull: true,
)
class UserProfile {
const UserProfile({
required this.userId,
required this.displayName,
});
final int userId;
final String? displayName;
factory UserProfile.fromJson(Map<String, dynamic> json) =>
_$UserProfileFromJson(json);
Map<String, dynamic> toJson() => _$UserProfileToJson(this);
}这里的 fieldRename 控制字段名到 JSON 键名的统一转换,includeIfNull 控制编码时是否保留空值字段。类级规则适合“某个模型与全局约定不同”的情况,不必为了一个例外修改整个项目。
理解配置优先级
同一个规则可能同时出现在字段、类和项目配置中。判断最终行为时,可以按下面的覆盖关系理解:
| 配置位置 | 典型用途 | 优先级 |
|---|---|---|
@JsonKey 字段级配置 |
单个字段例外 | 最高 |
@JsonSerializable 类级配置 |
单个模型例外 | 中 |
build.yaml |
项目统一默认策略 | 较低 |
| 包自身默认值 | 没有任何显式配置时使用 | 最低 |
例如项目默认是 snake_case,但 UserProfile 显式声明 FieldRename.kebab,那么生成结果必须出现 user-id,而不是 user_id。如果生成结果仍是旧键名,通常说明代码生成还没有重新执行。
重新生成并反查结果
运行生成器:
dart run build_runner build预期结果:命令成功完成,并生成或更新 lib/models/user_profile.g.dart。
打开生成文件时,关键映射应体现类级配置。生成器版本可能调整排版或临时代码形式,因此排查时应关注键名和是否包含字段,而不是逐字符比较整份文件。例如编码结果的核心含义应等价于:
Map<String, dynamic> _$UserProfileToJson(UserProfile instance) =>
<String, dynamic>{
'user-id': instance.userId,
'display-name': instance.displayName,
};display-name 即使为 null 仍会进入 Map,说明 includeIfNull: true 已覆盖项目默认的 false;键名使用短横线,说明 fieldRename: FieldRename.kebab 已覆盖项目默认的 snake_case。
用运行结果做最终验证
创建 bin/check_profile.dart:
import 'dart:convert';
import '../lib/models/user_profile.dart';
void main() {
const profile = UserProfile(
userId: 42,
displayName: null,
);
print(jsonEncode(profile.toJson()));
}预期结果:执行下面的命令后,JSON 同时体现 kebab-case 和保留空值两个类级规则。
dart run bin/check_profile.dart预期输出:
{"user-id":42,"display-name":null}如果输出成 user_id,先检查类注解中的 fieldRename 是否保存并重新生成;如果 display-name 消失,则检查 includeIfNull 是否仍为 true。排查生成配置时,最可靠的路径是“看源注解 → 重新生成 → 看 .g.dart → 跑一个最小输入输出”,而不是只凭注解表面判断。