跨平台开发 / 系统课时

忽略只读与派生字段

忽略只读与派生字段

同一个 Freezed 模型里常同时存在服务端字段、客户端状态和 UI 派生值。如果它们都无差别参与 fromJson 与 toJson,就容易把只读字段回传给接口,或让本地标记污染网络数据。

学习目标

  • 使用 includeFromJson 与 includeToJson 控制字段的映射方向
  • 正确处理服务端只读字段、客户端补充字段和本地状态
  • 识别哪些派生值根本不该进入 JSON 模型

先按数据方向分类

JsonKey 可以分别控制一个字段是否参与反序列化和序列化。四种组合对应四种边界:

配置 fromJson toJson 典型用途
默认 参与 参与 普通接口字段
includeToJson: false 参与 忽略 服务端只读字段
includeFromJson: false 忽略 参与 客户端生成后需要上送的字段
两者都为 false 忽略 忽略 本地缓存或 UI 状态

仅关闭 includeFromJson 时,反序列化仍然必须有办法构造该字段,因此通常要让它可空或提供默认值。否则生成器无法凭空得到一个非空值。

在一个模型中划清边界

下面是片段示例,假设项目已经完成 Freezed 与 json_serializable 的依赖配置和代码生成。

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

part 'article.freezed.dart';
part 'article.g.dart';

@freezed
abstract class Article with _$Article {
  const Article._();

  const factory Article({
    required String id,
    required String title,
    // 服务端可返回发布时间,但客户端更新时不应回传。
    @JsonKey(includeToJson: false) DateTime? publishedAt,
    @JsonKey(includeFromJson: false, includeToJson: true)
    @Default('mobile')
    String source,
    // 纯本地缓存状态,不进入任何网络 JSON。
    @JsonKey(includeFromJson: false, includeToJson: false)
    @Default(false)
    bool cached,
  }) = _Article;

  factory Article.fromJson(Map<String, Object?> json) =>
      _$ArticleFromJson(json);

  String get displayTitle => title.trim().isEmpty ? '未命名文章' : title;
}

publishedAt 可以从服务端读取,但不会被 toJson 回传;source 不读取服务端同名字段,解析时采用客户端默认值,却会在序列化时发送;cached 是纯本地状态,两个方向都忽略。displayTitle 只是计算属性,没有必要成为构造字段,因此也不会进入生成的 JSON 映射。

验证序列化方向

在同一源文件中运行下面的入口,可以同时看到“忽略输入”和“忽略输出”的效果。

dart
void main() {
  final article = Article.fromJson({
    'id': 'a-1',
    'title': 'Flutter',
    'publishedAt': '2026-09-18T04:00:00.000Z',
    // 这两个输入分别会被本地默认值和忽略规则挡住。
    'source': 'server',
    'cached': true,
  });

  print(article.source);
  print(article.cached);
  print(article.toJson());
}

预期输出:

text
mobile
false
{id: a-1, title: Flutter, source: mobile}

Map 的显示顺序不应作为程序逻辑依赖;真正需要验证的是:publishedAt 与 cached 不在输出中,而 source 使用客户端值。

派生字段优先用 getter

如果一个值完全可以由已有字段计算,例如展示标题、格式化金额或“是否过期”,优先写成 getter,而不是把它放进构造函数再用忽略注解隐藏。这样可以避免复制状态,也不会出现原始字段更新后派生字段忘记同步的问题。

序列化边界应围绕“谁拥有这个值”来设计:服务端拥有的只读值只读入,客户端要上送的值才写出,本地状态不跨网络,能计算出的派生值不存储。模型越清楚地区分这些来源,接口层和 UI 层之间的意外耦合就越少。

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

目录与阅读设置

记录一个想法

忽略只读与派生字段

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

登录哪都通