跨平台开发 / 系统课时
设置默认值与必填字段
设置默认值与必填字段
接口字段“缺失”“为 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 文件。
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,但两者都能得到确定结果。
void main() {
// 仅提供接口真正返回的必需字段。
final profile = UserProfile.fromJson({
'id': 'u-100',
'name': 'Ada',
});
print(profile.id);
print(profile.verified);
print(profile.avatarUrl);
}预期输出:
u-100
false
null实际生成文件名和构建日志可能因项目结构不同而变化,但上述模型值应保持一致。
如果删除输入中的 id,严格配置会在反序列化阶段抛出缺少必填键的异常;这比先生成一个半有效对象、再等到页面访问 id 时失败更容易定位。
宽松与严格怎么选
接口契约稳定、缺字段代表服务端数据错误时,应让关键标识、状态码等字段尽早失败;如果字段本来就是可选能力,使用可空类型更合适;只有当业务确实定义了默认语义时才使用 @Default。
判断规则可以很简单:缺失是错误就严格失败,缺失是合法状态就用可空类型,缺失有明确业务含义才设默认值。这样模型本身就是接口契约的一部分,而不是一层被动的数据容器。