Dart oss dson

学习 DSON 序列化库项目

Contents

• 项目概览
• 与 dart-core-libraries 的关联
• 项目架构分析
• 序列化实现详解
• Workflow: 通过 DSON 学习序列化技术
• Examples

项目概览

项目名称: dson 作者: dart-league GitHub: https://github.com/dart-league/dson Stars: 65 | 难度: 中等

一个纯 Dart 的对象-JSON 序列化库，支持循环引用、自定义转换器和代码生成。与 json_serializable 不同，dson 使用自己的注解和代码生成器，展示了 Dart 序列化机制的底层实现原理。

与 dart-core-libraries 的关联

该项目深入应用了 dart-core-libraries 技能：

dart-core-libraries 主题	项目中的应用
dart:convert	JSON 编解码核心
dart:mirrors / 反射	类型信息获取
String 操作	代码生成模板
Uri 解析	资源路径处理
Dart 注解	@Serializable 自定义注解
泛型	序列化器泛型抽象

项目架构分析

核心流程

@Serializable() 注解
    → code generator 扫描
    → 生成 .g.dart 文件
    → fromJson / toJson 方法
    → 支持循环引用解析

关键抽象

abstract class Serializable<T> {
  T fromJson(Map<String, dynamic> json);
  Map<String, dynamic> toJson();
}

class Serializer<T> {
  final Type type;
  final T Function(Map<String, dynamic>) fromJson;
  final Map<String, dynamic> Function(T) toJson;

  const Serializer({
    required this.type,
    required this.fromJson,
    required this.toJson,
  });
}

序列化实现详解

循环引用处理

DSON 的核心特性之一是支持循环引用的序列化：

class Node {
  String name;
  Node? parent;
  List<Node> children = [];
}

// DSL 自动处理父子循环引用
// {name: "root", parent: null, children: [
//   {name: "child", parent: "$ref:0", children: []}
// ]}

自定义转换器

class DateTimeConverter extends Converter<DateTime, int> {
  @override
  DateTime from(int milliseconds) =>
      DateTime.fromMillisecondsSinceEpoch(milliseconds);

  @override
  int to(DateTime date) => date.millisecondsSinceEpoch;
}

Workflow: 通过 DSON 学习序列化技术

Task Progress

• Step 1: 阅读项目接口定义。 从 Serializable 和 Serializer 抽象类理解核心设计。
• Step 2: 理解注解机制。 查看 @Serializable() 注解的定义，理解 Dart 元数据的存储方式。
• Step 3: 跟踪序列化流程。 从 fromJson() 调用开始，跟踪 JSON Map 如何转换为 Dart 对象。
• Step 4: 研究循环引用处理。 理解 DSON 如何用 $ref 标记解决循环引用。
• Step 5: 运行测试。 执行 dart test 观察循环引用、自定义转换器等测试用例。
• Step 6: 自定义转换器。 实现一个 DurationConverter，将 Duration 序列化为秒数。
• Step 7: 对比 json_serializable。 分析 DSON 与官方 json_serializable 的异同。
• Step 8: Feedback Loop。 添加转换器 → 写测试 → 跑分析 → 修正。

条件逻辑

• 如果对 Dart 注解机制不熟： 查阅 dart-type-system 技能中关于元数据的说明。
• 如果需要处理复杂嵌套对象： 参考 DSON 的递归序列化策略。
• 如果 JSON 解析性能是瓶颈： 考虑使用 dart:convert 的 JsonDecoder 与自定义 Converter 组合。
• 如果遇到类型转换错误： 检查 fromJson 中的 as 类型转换是否匹配 JSON 实际类型。

Examples

从项目中学到的序列化模式

class User extends Serializable {
  String name;
  int age;
  List<String> tags;

  User({required this.name, required this.age, this.tags = const []});

  @override
  User fromJson(Map<String, dynamic> json) => User(
    name: json['name'] as String,
    age: json['age'] as int,
    tags: (json['tags'] as List).cast<String>(),
  );

  @override
  Map<String, dynamic> toJson() => {
    'name': name,
    'age': age,
    'tags': tags,
  };
}

结合 dart-core-libraries 的延伸练习：通用 JSON 工具

import 'dart:convert';

class JsonHelper {
  static String prettyPrint(Map<String, dynamic> json) {
    return const JsonEncoder.withIndent('  ').convert(json);
  }

  static T? safeGet<T>(Map<String, dynamic> json, String key) {
    if (!json.containsKey(key)) return null;
    final value = json[key];
    return value is T ? value : null;
  }

  static Map<String, dynamic> deepCopy(Map<String, dynamic> source) {
    return jsonDecode(jsonEncode(source)) as Map<String, dynamic>;
  }
}