跨平台开发 / 系统课时
处理动态键与 Map 字段
处理动态键与 Map 字段
接口有时返回一个对象,但对象里的键名并不写死,而是由指标名、地区码或业务 ID 在运行时决定。此时关键不是把所有字段都降级成 dynamic,而是让“键动态、值强类型”,把不确定性限制在 JSON 解码边界。
学习目标
- 判断动态键字段应该建模为
Map、固定值对象还是自定义转换器 - 使用
Map<String, T>解析运行时键名,同时保持值对象类型安全 - 控制
dynamic只出现在 JSON 边界,避免扩散到业务逻辑
动态键变化的是键名,不是整个结构
下面的 metrics 不是固定字段集合。后端可以新增 queue-lag、region-west 等键,但每个键对应的值都保持同一结构。
{
"metrics": {
"cpu": {"value": 0.72, "unit": "ratio"},
"region-east": {"value": 42.0, "unit": "ms"}
}
}如果把 cpu、region-east 分别做成类字段,模型会随着服务端新增键不断修改;如果直接写成 Map<String, dynamic>,又会把类型检查推迟到每一次读取。更合适的边界通常是 Map<String, MetricValue>:键可以变化,值仍由编译器约束。

用 Map<String, T> 固定值类型
下面是可运行的项目内示例。前提是项目已经加入 freezed_annotation、json_annotation,以及开发依赖 freezed、json_serializable、build_runner。文件保存为 bin/example.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}');
}运行代码生成并执行示例:
dart run build_runner build --delete-conflicting-outputs
dart run bin/example.dart预期输出如下。代码生成阶段的日志会随 build_runner 版本变化,因此这里只固定程序本身的输出。
cpu=0.72 ratio
region-east=42.0 msMetricSnapshot.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> 等强类型结构。这样后端可以扩展键名,而字段类型错误、缺失值和转换规则仍集中在一个可测试的入口中。