跨平台开发 / 系统课时
处理字段名与 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 规范的数据模型。
按自己的节奏,确认真正理解。