数据序列化组件

数据序列化组件用于在对象和数据格式（如 JSON）之间进行转换。

提示：选择合适的序列化方案可以提高代码的类型安全性和可维护性。
📱 渲染效果预览
{ "name": "John", "age": 25, "email": "john@example.com" }

json_serializable

json_serializable 提供类型安全的 JSON 序列化。

import 'package:json_annotation/json_annotation.dart';

part 'user.g.dart';

@JsonSerializable()
class User {
  final String name;
  final int age;
  final String email;

  User({required this.name, required this.age, required this.email});

  factory User.fromJson(Map json) => _$UserFromJson(json);
  Map toJson() => _$UserToJson(this);
}

// 使用
final userJson = '{"name":"John","age":25,"email":"john@example.com"}';
final user = User.fromJson(jsonDecode(userJson));

final json = jsonEncode(user.toJson());
📱 渲染效果预览
Dart Object
User(name: "John", age: 25)
⇄
JSON
{"name":"John","age":25}

dart:convert

dart:convert 是 Dart 内置的编码/解码库。

import 'dart:convert';

// 编码为 JSON
final data = {
  'name': 'John',
  'age': 25,
  'email': 'john@example.com',
};
final jsonString = jsonEncode(data);

// 解码 JSON
final decoded = jsonDecode(jsonString);
print(decoded['name']); // John

// 处理列表
final users = [
  {'name': 'John', 'age': 25},
  {'name': 'Jane', 'age': 30},
];
final jsonString = jsonEncode(users);

final decoded = jsonDecode(jsonString) as List;
for (var user in decoded) {
  print('${user['name']}: ${user['age']}');
}
📱 渲染效果预览
✓ 推荐
Freezed
  • ✓ 不可变类
  • ✓ 模式匹配
  • ✓ 序列化支持
  • ✓ 复制with方法
传统类
  • ✗ 可变
  • ✗ 无模式匹配
  • ✗ 手动序列化
  • ✗ 需手动实现

Freezed

Freezed 是一个用于生成不可变类的代码生成库。

import 'package:freezed_annotation/freezed_annotation.dart';

part 'user.freezed.dart';
part 'user.g.dart';

@freezed
class User with _$User {
  const factory User({
    required String name,
    required int age,
    String? email,
  }) = _User;

  factory User.fromJson(Map json) => _$UserFromJson(json);
}

// 使用
final user = User(name: 'John', age: 25);
final json = user.toJson();
final userFromJson = User.fromJson(json);
📱 渲染效果预览
User
Immutable Object
⇄
Serialized
Binary / JSON

built_value

built_value 提供不可变数据类和序列化支持。

import 'package:built_value/built_value.dart';
import 'package:built_value/serializer.dart';

part 'user.g.dart';

abstract class User implements Built {
  String get name;
  int get age;
  String? get email;

  User._();
  factory User([updates(UserBuilder b)]) = _$User;

  static Serializer get serializer => _$userSerializer;
}

// 注册序列化器
final serializers = (Serializers().toBuilder()
  ..add(User.serializer));

// 序列化
final user = User((b) => b
  ..name = 'John'
  ..age = 25);

final json = serializers.serialize(user);
final userFromJson = serializers.deserialize(json) as User;
序列化方案选择：
  • json_serializable: Flutter 官方推荐，类型安全
  • dart:convert: 简单快速，适合小型项目
  • Freezed: 提供不可变类和模式匹配
  • built_value: 高性能，适合大型项目
注意事项：
  • 运行代码生成命令（flutter pub run build_runner build）
  • 将生成的文件添加到 .gitignore
  • 确保在 pubspec.yaml 中添加必要的依赖
← 网络请求组件 高级动画组件 →