跨平台开发 / 系统课时

配置类级 JSON 生成规则

配置类级 JSON 生成规则

@JsonSerializable 不只是“开启生成”的标记,它还可以在单个模型上覆盖项目级默认策略。本课用键名转换和空值输出两个规则演示配置优先级,并通过生成代码与运行结果反查配置是否真正生效。

学习目标

  • 能区分 build.yaml 项目默认值与 @JsonSerializable 类级显式配置
  • 能使用常见类级选项控制 JSON 键名和空值输出
  • 能从 .g.dart 与运行结果判断生成规则是否生效

先设置项目默认策略

当大多数模型都遵循同一规则时,可以在项目根目录的 build.yaml 给 json_serializable 设置默认值。下面让字段默认转为 snake_case,并省略值为 null 的字段:

yaml
targets:
  $default:
    builders:
      json_serializable:
        options:
          field_rename: snake
          include_if_null: false

这段配置本身不会生成代码;保存后需要重新运行生成器。未在类注解中显式指定的选项,会继续使用这里的项目默认值。

用类级配置覆盖默认值

创建 lib/models/user_profile.dart。这个模型显式要求 kebab-case,并要求即使字段为 null 也输出,因此会覆盖 build.yaml 中对应的两个默认值。

dart
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。如果生成结果仍是旧键名,通常说明代码生成还没有重新执行。

重新生成并反查结果

运行生成器:

bash
dart run build_runner build

预期结果:命令成功完成,并生成或更新 lib/models/user_profile.g.dart。

打开生成文件时,关键映射应体现类级配置。生成器版本可能调整排版或临时代码形式,因此排查时应关注键名和是否包含字段,而不是逐字符比较整份文件。例如编码结果的核心含义应等价于:

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:

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 和保留空值两个类级规则。

bash
dart run bin/check_profile.dart

预期输出:

text
{"user-id":42,"display-name":null}

如果输出成 user_id,先检查类注解中的 fieldRename 是否保存并重新生成;如果 display-name 消失,则检查 includeIfNull 是否仍为 true。排查生成配置时,最可靠的路径是“看源注解 → 重新生成 → 看 .g.dart → 跑一个最小输入输出”,而不是只凭注解表面判断。

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

目录与阅读设置

记录一个想法

配置类级 JSON 生成规则

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

登录哪都通