跨平台开发 / 系统课时

用 JsonKey 映射字段名

用 JsonKey 映射字段名

接口字段常常使用 snake_case、全大写缩写或历史遗留名称,而 Dart 字段仍应保持 lowerCamelCase。JsonKey 可以把“代码里的名字”和“线上 JSON 的键”分开,既保持模型可读性,也明确字段改名时哪些变化会影响接口兼容性。

学习目标

  • 使用 @JsonKey(name: ...) 映射 snake_case、缩写和历史 JSON 键。
  • 验证自定义键名同时作用于 fromJson 与 toJson。
  • 判断 Dart 字段重命名和 JSON 键重命名对兼容性的不同影响。

把 Dart 名称与 JSON 键拆开

片段示例:下面是完整的 lib/models/profile.dart,它依赖 json_annotation 与后续生成的 profile.g.dart;模型保留符合 Dart 习惯的字段名,把接口键写在 JsonKey.name 中:

dart
import 'package:json_annotation/json_annotation.dart';

part 'profile.g.dart';

@JsonSerializable()
class Profile {
  const Profile({
    required this.userId,
    required this.apiVersion,
    required this.nickname,
  });

  @JsonKey(name: 'user_id')
  final String userId;

  @JsonKey(name: 'API_VERSION')
  final String apiVersion;

  @JsonKey(name: 'nick_name_v1')
  final String nickname;

  factory Profile.fromJson(Map<String, dynamic> json) =>
      _$ProfileFromJson(json);

  Map<String, dynamic> toJson() => _$ProfileToJson(this);
}

JsonKey 用于定制单个字段的序列化规则,name 指定该字段在 JSON 中使用的键。生成器会把这个键同时用于读取和输出,因此 Dart 字段名不需要跟接口命名风格保持一致。([Dart packages][2])

看生成代码实际用了哪个键

生成代码后,profile.g.dart 的核心映射会体现这些名称。片段示例:下面内容依赖 profile.dart,用于阅读生成结果,不应手工修改。

dart
part of 'profile.dart';

Profile _$ProfileFromJson(Map<String, dynamic> json) => Profile(
      userId: json['user_id'] as String,
      apiVersion: json['API_VERSION'] as String,
      nickname: json['nick_name_v1'] as String,
    );

Map<String, dynamic> _$ProfileToJson(Profile instance) => <String, dynamic>{
      'user_id': instance.userId,
      'API_VERSION': instance.apiVersion,
      'nick_name_v1': instance.nickname,
    };

关键点不是注解改变了 Dart 成员,而是生成代码改用了指定 JSON 键。业务代码仍访问 profile.userId、profile.apiVersion 和 profile.nickname,只有序列化边界知道外部字段名。

生成并验证映射

先在项目根目录生成代码:

bash
dart run build_runner build

预期结果:

text
退出码:0
生成文件:lib/models/profile.g.dart

片段示例:然后创建 bin/check_profile.dart,它依赖前面的 Profile 模型及已经生成的 profile.g.dart:

dart
import 'dart:convert';

import '../lib/models/profile.dart';

void main() {
  final source = <String, dynamic>{
    'user_id': '42',
    'API_VERSION': 'v2',
    'nick_name_v1': 'Neo',
  };

  final profile = Profile.fromJson(source);

  print('${profile.userId}|${profile.apiVersion}|${profile.nickname}');
  print(jsonEncode(profile.toJson()));
}

运行:

bash
dart run bin/check_profile.dart

预期输出:

text
42|v2|Neo
{"user_id":"42","API_VERSION":"v2","nick_name_v1":"Neo"}

如果输出仍出现 userId 或 apiVersion 作为 JSON 键,通常说明生成文件没有更新,或注解写在了没有参与当前序列化模型的字段上。

字段改名时先区分两种变化

仅修改 Dart 字段名,同时保留原来的 @JsonKey(name: ...),外部 JSON 契约可以保持不变;例如把 nickname 改成 displayName,只要继续映射到 nick_name_v1,接口仍读写旧键。

真正有兼容风险的是修改 JsonKey.name。把 nick_name_v1 改成 display_name 后,新生成的 fromJson 会读取新键,toJson 也会输出新键;仍发送旧键的客户端或缓存数据就可能让必填字段解析失败。JsonKey(name: ...) 表达的是一个确定键名,不等同于“新旧两个键都能自动识别”。

因此,JsonKey 最适合解决“内部命名保持 Dart 风格、外部键名保持接口契约”的问题。把 Dart 重构与 JSON 契约变更分开处理,才能避免一次看似简单的字段改名意外破坏双向序列化。

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

目录与阅读设置

记录一个想法

用 JsonKey 映射字段名

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

登录哪都通