跨平台开发 / 系统课时

处理字段名与 Dart 属性不同

处理字段名与 Dart 属性不同

本篇解决接口 JSON 字段命名与 Dart 编码规范不一致的问题。通过 json_serializable 注解,可以将 snake_case、特殊字段名以及接口默认值映射到清晰的 Dart 属性中。

学习目标

  • 掌握 JSON 字段和 Dart 属性之间的映射方式
  • 使用注解处理特殊字段名和默认值
  • 理解模型转换中的兼容策略

为什么字段映射是必要的

实际接口通常使用后端命名规范,例如 user_name、created_at。而 Dart 社区更推荐使用 lowerCamelCase,例如 userName、createdAt。

如果直接按照 JSON 字段命名创建属性,会降低 Dart 代码可读性。json_serializable 提供注解,让模型属性保持符合语言习惯,同时正确解析接口数据。

使用 JsonKey 映射字段名

使用 @JsonKey 可以指定 JSON 中真实存在的字段名。

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

part 'profile.g.dart';

@JsonSerializable()
class Profile {
  final int id;

  @JsonKey(name: 'user_name')
  final String userName;

  Profile({required this.id, required this.userName});

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

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

生成器会读取 name 配置,在转换时自动完成字段替换。

处理缺失字段和默认值

接口返回的数据可能缺少字段。对于可接受缺失的字段,可以使用默认值。

dart
@JsonSerializable()
class Settings {
  final String language;

  Settings({this.language = 'zh-CN'});

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

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

如果需要让 JSON 缺失字段时使用默认值,可以配置 JsonKey:

dart
@JsonKey(defaultValue: 'zh-CN')
final String language;

生成代码会在字段不存在时采用指定默认值。

处理特殊字段名

部分接口可能存在 Dart 不方便直接使用的字段,例如带连字符的字段名。

dart
@JsonSerializable()
class Device {
  @JsonKey(name: 'device-id')
  final String deviceId;

  Device({required this.deviceId});

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

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

预期结果

text
JSON 字段 device-id 会映射到 Dart 属性 deviceId

映射策略的选择

常见场景可以按以下方式处理:

接口情况 推荐方式
snake_case 字段 JsonKey(name:)
字段可能缺失 defaultValue 或可空类型
字段需要转换 自定义转换函数
字段名称可直接匹配 不添加额外注解

不要为了统一风格给所有字段添加注解。只有 JSON 名称和 Dart 属性存在差异时才需要映射,这样模型更容易维护。

字段映射的目标不是隐藏接口差异,而是在数据边界处完成转换,让业务代码始终使用稳定、符合 Dart 规范的数据模型。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理字段名与 Dart 属性不同

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

登录哪都通