Flutter二进制序列化插件binary_serializable_generator的使用

binary_serializable_generator

binary_serializable_generator 是一个用于生成 binary_serializable 插件中 BinaryType 的代码生成工具。

安装

首先，安装 binary_serializable 作为常规依赖项，并将 binary_serializable_generator 和 build_runner 作为开发依赖项：

$ dart pub add binary_serializable
$ dart pub add -d binary_serializable_generator build_runner

使用

导入 package:binary_serializable/binary_serializable.dart 并为类添加 [@BinarySerializable](/user/BinarySerializable)() 注解以生成对应的 BinaryType。字段上可以使用 BinaryType 的子类型来实现序列化。

示例代码

import 'package:binary_serializable/binary_serializable.dart';

part 'example.g.dart'; // 替换为实际文件名.g.dart，build_runner 将在此文件中生成代码

[@BinarySerializable](/user/BinarySerializable)()
class Example {
  @uint64
  final int id;

  [@utf8String](/user/utf8String)
  final String name;

  @LengthPrefixedListType(uint8, utf8String)
  final List<String> tags;

  Example(this.id, this.name, this.tags);
}

运行以下命令以生成代码：

$ dart run build_runner build

生成的代码将出现在 file_name.g.dart 中：

class ExampleType extends BinaryType<Example> {
  const ExampleType();

  [@override](/user/override)
  Uint8List encode(Example input) {
    final builder = BytesBuilder(copy: false);
    builder.add(uint64.encode(input.id)); // 序列化 id
    builder.add(utf8String.encode(input.name)); // 序列化 name
    builder.add(const LengthPrefixedListType(
      uint8,
      utf8String,
    ).encode(input.tags)); // 序列化 tags
    return builder.takeBytes();
  }

  [@override](/user/override)
  BinaryConversion<Example> startConversion(void Function(Example) onValue) =>
      _ExampleConversion(
        this,
        onValue,
      );
}

class _ExampleConversion extends CompositeBinaryConversion<Example> {
  _ExampleConversion(
    this.type,
    super.onValue,
  );

  final ExampleType type;

  [@override](/user/override)
  BinaryConversion startConversion() {
    return uint64.startConversion((id) { // 开始解析 id
      currentConversion = utf8String.startConversion((name) { // 解析 name
        currentConversion = const LengthPrefixedListType(
          uint8,
          utf8String,
        ).startConversion((tags) { // 解析 tags
          final instance = Example(
            id,
            name,
            tags,
          );
          onValue(instance); // 调用回调函数
        });
      });
    });
  }
}

高级用法

自定义构造函数

如果类有多个构造函数，可以通过在构造函数上添加 [@BinarySerializable](/user/BinarySerializable)() 注解来指定要使用的构造函数。需要注意以下限制：

1. 构造函数的每个参数都必须有一个字段，该字段带有与参数同名的 BinaryType 注解。
2. 类中所有带 BinaryType 注解的字段都会按顺序被序列化，无论它们是否出现在构造函数中。

示例代码

[@BinarySerializable](/user/BinarySerializable)(constructor: 'fromMap')
class Example {
  @uint64
  final int id;

  [@utf8String](/user/utf8String)
  final String name;

  @LengthPrefixedListType(uint8, utf8String)
  final List<String> tags;

  Example(this.id, this.name, this.tags);

  factory Example.fromMap(Map<String, dynamic> map) {
    return Example(
      map['id'] as int,
      map['name'] as String,
      (map['tags'] as List<dynamic>).cast<String>(),
    );
  }
}

运行 dart run build_runner build 后，会生成相应的代码。

带泛型的类

如果类包含泛型，则可以在生成的 BinaryType 中指定这些泛型的类型。

示例代码

[@BinarySerializable](/user/BinarySerializable)()
class GenericType<T, U> {
  @Generic('T')
  final T genericField;

  @LengthPrefixedListType(uint8, Generic('U'))
  final List<U> genericList;

  GenericType(this.genericField, this.genericList);
}

class GenericTypeType<T, U> extends BinaryType<GenericType<T, U>> {
  const GenericTypeType(
    this.genericTypeU,
    this.genericTypeT,
  );

  final BinaryType<U> genericTypeU;

  final BinaryType<T> genericTypeT;

  [@override](/user/override)
  Uint8List encode(GenericType<T, U> input) {
    final builder = BytesBuilder(copy: false);
    builder.add(genericTypeT.encode(input.genericField)); // 序列化 genericField
    builder.add(LengthPrefixedListType(
      uint8,
      genericTypeU,
    ).encode(input.genericList)); // 序列化 genericList
    return builder.takeBytes();
  }

  [@override](/user/override)
  BinaryConversion<GenericType<T, U>> startConversion(
          void Function(GenericType<T, U>) onValue) =>
      _GenericTypeConversion(
        this,
        onValue,
      );
}

class _GenericTypeConversion<T, U>
    extends CompositeBinaryConversion<GenericType<T, U>> {
  _GenericTypeConversion(
    this.type,
    super.onValue,
  );

  final GenericTypeType<T, U> type;

  [@override](/user/override)
  BinaryConversion startConversion() {
    return type.genericTypeT.startConversion((genericField) {
      currentConversion = LengthPrefixedListType(
        uint8,
        type.genericTypeU,
      ).startConversion((genericList) {
        final instance = GenericType<T, U>(
          genericField,
          genericList,
        );
        onValue(instance);
      });
    });
  }
}

抽象类

对于抽象类，可以使用 MultiBinaryType 来生成对应的 BinaryType。

示例代码

[@BinarySerializable](/user/BinarySerializable)()
abstract class Message {
  [@uint8](/user/uint8)
  int get id;
}

[@BinarySerializable](/user/BinarySerializable)()
class StringMessage extends Message {
  [@override](/user/override)
  int get id => 2;

  [@utf8String](/user/utf8String)
  final String data;

  StringMessage(this.data);
}

[@BinarySerializable](/user/BinarySerializable)()
class IntegerMessage extends Message {
  [@override](/user/override)
  int get id => 1;

  [@int64](/user/int64)
  final int data;

  IntegerMessage(this.data);
}

class MessageType extends MultiBinaryType<Message, int> {
  const MessageType([super.subtypes = MessageType.defaultSubtypes]);

  static const Map<int, BinaryType<Message>> defaultSubtypes = {
    2: StringMessageType(),
    1: IntegerMessageType(),
  };

  [@override](/user/override)
  int extractPrelude(Message instance) => instance.id;

  [@override](/user/override)
  BinaryConversion<int> startPreludeConversion(void Function(int) onValue) =>
      _MessagePreludeConversion(
        this,
        onValue,
      );
}

class _MessagePreludeConversion extends CompositeBinaryConversion<int> {
  _MessagePreludeConversion(
    this.type,
    super.onValue,
  );

  final MessageType type;

  [@override](/user/override)
  BinaryConversion startConversion() {
    return uint8.startConversion((id) {
      onValue(id);
    });
  }
}