Flutter插件bare的介绍与使用

Flutter插件bare的介绍与使用

Binary Application Record Encoding (二进制应用程序记录编码)

BARE 是为 Dart 开发者提供的一个库。BARE 是一种用于结构化应用程序数据的简单二进制表示方法。https://baremessages.org/ 它是 protobuf、msgpack、JSON、BSON 等的替代方案。 此仓库提供了一个用于二进制应用程序记录编码的序列化/反序列化包。

关于BARE

BARE 是一种针对小消息量和实现简单化的消息协议。它的轻量级协议允许你构建明确的架构，并通过可选的代码生成，你可以在广泛的编程环境中获得兼容性和类型安全。BARE 还强调了消息的向后兼容性，今天编码的消息在明天也可以解码，而不会牺牲扩展性。 目前，已经有针对 Lisp、D、.NET、Elm、Erlang、Go、Java、JavaScript、OCaml、PHP、Python、Ruby、Rust 等语言的实现。

为什么选择BARE消息

在众多的消息协议中，有几种被广泛采用的标准供选择。在谷歌protobuf、JSON、BSON、MessagePack等之间的选择是一个权衡问题。JSON 对人和机器都是可读的，但消息比较臃肿。Protobuf 优化了这一点，但又过于脆弱且复杂。BSON 将MongoDB的实现细节泄露到了规范中…… 详细报告请参阅 BARE 创建者 Drew DeVault 的原始博客文章：Introducing the BARE messaging encoding

BARE 是你的选择，如果你希望优化以下方面：

• 小消息量
• 标准化
• 实现简单
• 普适性实现，几乎不需要扩展
• 简单性——没有不贡献核心任务的多余内容

bare.dart 特点

Dart 实现的 BARE 消息完全支持 BARE 的 IETF 互联网草案：draft-devault-bare-03

• 优化小消息量：二进制，非自描述，无对齐或填充
• 标准化且简单：规范只有大约1000个单词
• 普适性：扩展不需要扩展实现，也不需要与旧实现不兼容的消息
• 零依赖
• 解析 BARE 架构
• 生成 BARE 架构类型的编码/解码方法
• 支持深度嵌套的匿名结构和联合

要更深入地了解 BARE 的基础知识，请参阅官方文档。

BARE 代码生成器

代码生成器将所有 *.bare 文件转换为：

• *.dart
• *.bare.dart

它生成必要的类和扩展方法。

运行代码生成器：

$ dart run build_runner build

编码类的方法：

<class_name>.toBare

解码到类的方法：

<class_name>.fromBare(bytes)

查看示例文件夹以获取架构文件样本和生成的代码。

代码生成器配置选项

to_string - 为生成的类生成 toString 覆盖。默认 - True

targets:
  $default:
    builders:
      bare_codegen|bareGenerator:
        options:
          to_string: True

运行项目

更新依赖项：

$ cd bare && pub get
$ cd bare_codegen && pub get
$ cd example && pub get

进入 example 目录并运行构建过程和测试：

$ dart run build_runner build
$ dart test

示例 BARE 架构

type PublicKey data[128]
type Time str # ISO 8601

type Department enum {
  ACCOUNTING
  ADMINISTRATION
  CUSTOMER_SERVICE
  DEVELOPMENT

  # 保留给CEO
  JSMITH = 99
}

type Customer struct {
  name: str
  email: str
  address: Address
  orders: list<struct {
    orderId: i64
    quantity: i32
  }>
  metadata: map<str><data>
}

生成的类

（完整的文件请参见示例文件夹）

class Customer {
  String name;
  String email;
  Address address;
  List<Orders1> orders;
  Map<String, List<int>> metadata;
  Customer(
      {required this.name,
      required this.email,
      required this.address,
      required this.orders,
      required this.metadata});

  static Customer fromBare(data) => CustomerBare.fromBare(data);

  [@override](/user/override)
  String toString() =>
      'Customer { name: ${name}, email: ${email}, address: ${address}, orders: ${orders}, metadata: ${metadata} }';
}

extension CustomerBare on Customer {
  Uint8List toBare() {
    final x = Packer();
    pack(x);
    return x.takeBytes();
  }

  static Customer fromBare(data) {
    Unpacker unpacker = Unpacker.fromList(data);
    return unpack(unpacker);
  }

  Packer pack(Packer p) {
    p.packString(name);
    p.packString(email);
    address.pack(p);
    p.packLength(orders.length);
    orders.forEach((e) => e.pack(p));

    p.packLength(metadata.length);
    metadata.forEach((k, v) {
      p.packString(k);
      p.packBinary(v);
    });

    return p;
  }

  static Customer unpack(Unpacker p) {
    final name = p.unpackString();
    final email = p.unpackString();
    Address address;
    address = AddressBare.unpack(p);

    List<Orders1> orders;
    orders = <Orders1>[];
    final ordersLength = p.unpackLength();
    for (var i = 0; i < ordersLength; i++) {
      final e = Anon1Bare.unpack(p);
      orders.add(e);
    }

    Map<String, List<int>> metadata;
    List<MapEntry<String, List<int>>> entries = [];
    final metadataLength = p.unpackLength();
    for (var i = 0; i < metadataLength; i++) {
      final k = p.unpackString();
      final v = p.unpackBinary();
      entries.add(MapEntry(k, v));
    }
    final _map1 = <String, List<int>>{};
    _map1.addEntries(entries);
    metadata = _map1;

    return Customer(
        name: name,
        email: email,
        address: address,
        orders: orders,
        metadata: metadata);
  }
}