跨平台开发 / 系统课时

处理字段名与类型不一致

处理字段名与类型不一致

接口字段经常与 Dart 模型不完全一致:可能是 snake_case,数字可能是字符串,布尔值还可能用 0、1 或 yes 表示。本节先区分字段名与字段值差异,再分别用映射和显式转换建立稳定、可验证的类型边界。

学习目标

  • 区分字段名不一致与字段值类型不一致,并选择对应处理方式
  • 使用 JsonKey.name、fromJson 和 toJson 建立稳定的 JSON 边界
  • 为数字字符串和布尔值变体设计可验证、失败可见的转换规则

先判断差异发生在哪一层

字段名不一致只影响“从哪个 key 取值”,例如接口给出 user_id,模型希望使用 id。这种情况不需要改字段类型,用 @JsonKey(name: 'user_id') 即可。若整类字段都稳定采用 snake_case,也可以在 json_serializable 的统一配置层使用 FieldRename.snake,减少重复注解。

值类型不一致则是另一类问题。json_serializable 不会因为目标字段是 int 就自动把 "42" 当成 42,也不会自行判断 "yes" 是否代表 true。这类规则属于接口契约的一部分,应由显式转换函数负责。

接口差异 典型输入 合适处理
key 名不同 user_id → id JsonKey.name
数字被编码成字符串 "42" → 42 JsonKey.fromJson
布尔值有多种表达 1、"yes" → true JsonKey.fromJson
字段缺失或可为 null 无 key、null 调整可空性或默认值

JSON 字段差异的处理决策流

用映射解决名字,用转换器解决类型

片段示例:下面是完整的 lib/models/user.dart 模型文件,但它依赖 Freezed 和 json_serializable 生成的 user.freezed.dart、user.g.dart,因此需要先运行代码生成器再参与编译。

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

part 'user.freezed.dart';
part 'user.g.dart';

@freezed
abstract class User with _$User {
  const factory User({
    @JsonKey(name: 'user_id', fromJson: _parseInt, toJson: _writeInt)
    required int id,
    @JsonKey(name: 'is_active', fromJson: _parseBool, toJson: _writeBool)
    required bool isActive,
  }) = _User;

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}

int _parseInt(Object? value) {
  if (value is int) return value;
  if (value is String) {
    final parsed = int.tryParse(value);
    if (parsed != null) return parsed;
  }
  throw FormatException('Expected int or integer string, got: $value');
}

int _writeInt(int value) => value;

bool _parseBool(Object? value) {
  if (value is bool) return value;
  if (value == 1 || value == '1') return true;
  if (value == 0 || value == '0') return false;

  if (value is String) {
    switch (value.toLowerCase()) {
      case 'true':
      case 'yes':
        return true;
      case 'false':
      case 'no':
        return false;
    }
  }

  throw FormatException('Expected boolean variant, got: $value');
}

bool _writeBool(bool value) => value;

这里故意让 _parseInt 只接受真正的整数或可解析的整数字符串,而没有把 42.7 强制截断为 42。转换器越“聪明”,越可能吞掉后端数据错误;只有接口契约明确允许的变体才应该被接受。

生成代码:

bash
dart run build_runner build --delete-conflicting-outputs

预期结果:

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

构建日志中的耗时和任务数量会随项目规模变化,判断是否成功应以退出码和生成文件为准。

验证输入与规范化输出

下面的验证程序假设前面的模型文件已经生成代码。将它保存为 bin/check_user.dart;程序故意输入数字字符串和 "yes",再观察模型值以及重新序列化后的 JSON。

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

void main() {
  final user = User.fromJson({
    'user_id': '42',
    'is_active': 'yes',
  });

  print('${user.id},${user.isActive}');
  print(user.toJson());
}

运行:

bash
dart run bin/check_user.dart

预期输出:

text
42,true
{user_id: 42, is_active: true}

这里体现了一个重要边界:输入可以兼容历史变体,输出应尽量统一为单一规范格式。这样应用内部只处理 int 和 bool,下游序列化也不会继续扩散 "42"、"yes" 等多种表示。

哪些情况不该靠字段映射硬扛

字段映射只能解决名称问题,不能修复值语义。如果后端有时返回对象、有时返回字符串,或者同一个字段的含义会随另一个字段变化,就应该设计专用 JsonConverter、联合类型或独立 DTO,而不是继续堆叠 JsonKey 参数。

对 null 也要单独决定策略:字段本来允许缺失,就把模型设计为可空或提供明确默认值;字段业务上必须存在,就让解析失败暴露契约破坏。类型安全的目标不是“所有 JSON 都能吃下去”,而是把允许的兼容范围写清楚,并让异常数据尽早可见。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理字段名与类型不一致

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

登录哪都通