跨平台开发 / 系统课时

处理动态键与 Map 字段

处理动态键与 Map 字段

接口有时返回一个对象,但对象里的键名并不写死,而是由指标名、地区码或业务 ID 在运行时决定。此时关键不是把所有字段都降级成 dynamic,而是让“键动态、值强类型”,把不确定性限制在 JSON 解码边界。

学习目标

  • 判断动态键字段应该建模为 Map、固定值对象还是自定义转换器
  • 使用 Map<String, T> 解析运行时键名,同时保持值对象类型安全
  • 控制 dynamic 只出现在 JSON 边界,避免扩散到业务逻辑

动态键变化的是键名,不是整个结构

下面的 metrics 不是固定字段集合。后端可以新增 queue-lag、region-west 等键,但每个键对应的值都保持同一结构。

json
{
  "metrics": {
    "cpu": {"value": 0.72, "unit": "ratio"},
    "region-east": {"value": 42.0, "unit": "ms"}
  }
}

如果把 cpu、region-east 分别做成类字段,模型会随着服务端新增键不断修改;如果直接写成 Map<String, dynamic>,又会把类型检查推迟到每一次读取。更合适的边界通常是 Map<String, MetricValue>:键可以变化,值仍由编译器约束。

动态键 JSON 从解码边界进入强类型 Map 的数据流

用 Map<String, T> 固定值类型

下面是可运行的项目内示例。前提是项目已经加入 freezed_annotation、json_annotation,以及开发依赖 freezed、json_serializable、build_runner。文件保存为 bin/example.dart,生成代码后即可执行。

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

part 'example.freezed.dart';
part 'example.g.dart';

@freezed
abstract class MetricValue with _$MetricValue {
  const factory MetricValue({
    required double value,
    required String unit,
  }) = _MetricValue;

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

@freezed
abstract class MetricSnapshot with _$MetricSnapshot {
  const factory MetricSnapshot({
    required Map<String, MetricValue> metrics,
  }) = _MetricSnapshot;

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

void main() {
  const source = '''
  {
    "metrics": {
      "cpu": {"value": 0.72, "unit": "ratio"},
      "region-east": {"value": 42.0, "unit": "ms"}
    }
  }
  ''';

  // dynamic 只出现在 JSON 解码边界。
  final raw = jsonDecode(source) as Map<String, dynamic>;
  final snapshot = MetricSnapshot.fromJson(raw);

  final cpu = snapshot.metrics['cpu']!;
  final east = snapshot.metrics['region-east']!;
  print('cpu=${cpu.value} ${cpu.unit}');
  print('region-east=${east.value} ${east.unit}');
}

运行代码生成并执行示例:

bash
dart run build_runner build --delete-conflicting-outputs
dart run bin/example.dart

预期输出如下。代码生成阶段的日志会随 build_runner 版本变化,因此这里只固定程序本身的输出。

text
cpu=0.72 ratio
region-east=42.0 ms

MetricSnapshot.fromJson 会遍历 metrics 中的每个条目,并把值交给 MetricValue.fromJson。运行时新增键不会要求修改 Dart 类;读取某个键时得到的是 MetricValue?,所以未知键仍然必须处理缺失情况,不能无条件使用 !。

什么时候不用 Map

选择模型时可以先看“键是否稳定”和“值是否同构”。

JSON 形态 更合适的模型 原因
键运行时变化,值结构一致 Map<String, MetricValue> 保留动态键,同时约束值类型
键集合稳定且每个字段语义不同 普通强类型对象 字段名本身就是领域语义
键动态,值还需要特殊格式转换 JsonConverter 或 @JsonKey(fromJson: ...) 在边界集中完成归一化
服务端结构完全未知 Map<String, dynamic> 只能暂时保留原始结构,后续读取要显式校验

自定义转换器适合“值结构可确定,但原始 JSON 不是目标类型”的情况,例如服务端把数字写成字符串、把空对象表示为 null,或者需要过滤非法键。转换完成后,业务层仍应拿到稳定的 Map<String, T>,而不是继续传递原始 dynamic。

把不确定性留在数据边界

动态键不等于动态类型。解码层负责面对 Map<String, dynamic>,模型层负责把值转换成明确类型,业务层只消费 Map<String, MetricValue> 等强类型结构。这样后端可以扩展键名,而字段类型错误、缺失值和转换规则仍集中在一个可测试的入口中。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理动态键与 Map 字段

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

登录哪都通