跨平台开发 / 系统课时
忽略只读与派生字段
忽略只读与派生字段
同一个 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 层之间的意外耦合就越少。
按自己的节奏,确认真正理解。