跨平台开发 / 系统课时

设置默认值与必填字段

设置默认值与必填字段

接口字段“缺失”“为 null”和“有默认值”不是一回事。正确的模型应在反序列化阶段就表达这些差异,让异常尽早暴露,同时避免把本可安全兜底的问题拖到 UI 层处理。

学习目标

  • 区分 Dart 构造器的 required、可空类型与 JSON 字段必填语义
  • 使用 @Default 为缺失字段提供稳定默认值
  • 根据接口可靠性选择宽松解析或严格解析

三种语义不要混在一起

required String id 表示调用 Dart 构造器时必须传入 id,并且值不能为 null。它首先约束的是 Dart 调用方,不等同于“JSON 一定包含这个键”。

String? avatarUrl 表示业务允许没有值。JSON 缺少 avatarUrl,或它明确为 null,都可以映射为 null。如果 UI 能自然处理“无头像”,这种建模比随意塞一个空字符串更准确。

@Default(false) bool verified 表示字段缺失时使用 false。Freezed 与 JSON 生成配合时,会把这个默认值带入反序列化逻辑,因此适合接口允许省略、且产品语义存在明确默认值的字段。

用模型直接表达接口契约

下面是片段示例,假设项目已配置 freezed_annotation、freezed、json_annotation、json_serializable 与 build_runner,并已生成对应的 .freezed.dart 和 .g.dart 文件。

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

part 'user_profile.freezed.dart';
part 'user_profile.g.dart';

@freezed
abstract class UserProfile with _$UserProfile {
  const factory UserProfile({
    // 同时要求 JSON 中存在 id,并保持 Dart 侧非空。
    @JsonKey(required: true) required String id,
    required String name,
    // 缺字段时按业务约定回退为 false。
    @Default(false) bool verified,
    String? avatarUrl,
  }) = _UserProfile;

  factory UserProfile.fromJson(Map<String, Object?> json) =>
      _$UserProfileFromJson(json);
}

这里故意让 id 同时使用 Dart 的 required 和 JSON 的 @JsonKey(required: true):前者约束手写构造,后者明确要求反序列化输入中存在 id 键。verified 则选择宽松策略,缺失时自动取 false。

验证缺字段与默认值

在同一源文件中加入以下入口即可验证正常路径。输入没有 verified 和 avatarUrl,但两者都能得到确定结果。

dart
void main() {
  // 仅提供接口真正返回的必需字段。
  final profile = UserProfile.fromJson({
    'id': 'u-100',
    'name': 'Ada',
  });

  print(profile.id);
  print(profile.verified);
  print(profile.avatarUrl);
}

预期输出:

text
u-100
false
null

实际生成文件名和构建日志可能因项目结构不同而变化,但上述模型值应保持一致。

如果删除输入中的 id,严格配置会在反序列化阶段抛出缺少必填键的异常;这比先生成一个半有效对象、再等到页面访问 id 时失败更容易定位。

宽松与严格怎么选

接口契约稳定、缺字段代表服务端数据错误时,应让关键标识、状态码等字段尽早失败;如果字段本来就是可选能力,使用可空类型更合适;只有当业务确实定义了默认语义时才使用 @Default。

判断规则可以很简单:缺失是错误就严格失败,缺失是合法状态就用可空类型,缺失有明确业务含义才设默认值。这样模型本身就是接口契约的一部分,而不是一层被动的数据容器。

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

目录与阅读设置

记录一个想法

设置默认值与必填字段

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

登录哪都通