FlatBuffers简介

FlatBuffers简介
FlatBuffers Schema解析
FlatBuffers序列化过程
FlatBuffers反序列化过程

这篇文章是对FlatBuffers官方文档Main Page的简单翻译，有不当之处欢迎指出。

OverView

FlatBuffers是Google出品的一个高效的跨平台序列化库，最初是为了游戏开发和其他性能要求比较严格的应用而创建的。

主要特点

• 不需要parsing/unpacking即可直接访问数据。这是FlatBuffers和其他序列化框架，比如Protocol Buffers或者Thrift，的主要区别。后两者必须先进行一次转化才能访问数据。FlatBuffers在一个扁平的binaryBuffer中表示层级结构的数据，支持版本演进。
• 高效的内存使用和运行速度。唯一需要的内存空间就是存储对象的buffer。除了为了支持版本演进和可选Field需要额外一些开销之外，访问速度几乎等同于不进行序列化的直接访问。
• 灵活性。可选field支持向前和向后的兼容性。
• 轻量的代码封装。
• 强类型。
• 方便使用，跨平台，不需要依赖（这个主要是针对C，Java还是需要依赖，不过只有四个类）

使用方法

1. 编写schema

直接使用官方Tutorial中的例子，这里的Monster表示游戏中的一个角色，其属性有颜色、位置、装备等。schema中Field可以使用的元素包括：标量（整形或者浮点类型）/string/任何类型的数组/另一个对象的引用/union（一组可能的对象，包含多种类型，每次只能有其中一种类型的值）。Field都是可选的且有默认值，因此不是每个实例都有所有的Field。后面会有详细文章对schema单独说明。

// Example IDL file for our monster's schema.
namespace MyGame.Sample;
enum Color:byte { Red = 0, Green, Blue = 2 }
union Equipment { Weapon } // Optionally add more tables.
struct Vec3 {
  x:float;
  y:float;
  z:float;
}
table Monster {
  pos:Vec3; // Struct.
  mana:short = 150;
  hp:short = 100;
  name:string;
  friendly:bool = false (deprecated);
  inventory:[ubyte];  // Vector of scalars.
  color:Color = Blue; // Enum.
  weapons:[Weapon];   // Vector of tables.
  equipped:Equipment; // Union.
  path:[Vec3];        // Vector of structs.
}
table Weapon {
  name:string;
  damage:short;
}
root_type Monster;

2. 编译生成文件

上面的schema保存为Monster.fbs，使用flac进行编译：
flac.exe --java Monster.fbs
生成5个文件

image.png

3. 使用FlatBufferBuilder构造flat binary buffer

import MyGame.Sample.Color;
import MyGame.Sample.Equipment;
import MyGame.Sample.Monster;
import MyGame.Sample.Vec3;
import MyGame.Sample.Weapon;

import com.google.flatbuffers.FlatBufferBuilder;

import java.nio.ByteBuffer;

class SampleBinary {
  // Example how to use FlatBuffers to create and read binary buffers.
  public static void main(String[] args) {
    FlatBufferBuilder builder = new FlatBufferBuilder(0);

    // Create some weapons for our Monster ('Sword' and 'Axe').
    int weaponOneName = builder.createString("Sword");
    short weaponOneDamage = 3;
    int weaponTwoName = builder.createString("Axe");
    short weaponTwoDamage = 5;

    // Use the `createWeapon()` helper function to create the weapons, since we set every field.
    int[] weaps = new int[2];
    weaps[0] = Weapon.createWeapon(builder, weaponOneName, weaponOneDamage);
    weaps[1] = Weapon.createWeapon(builder, weaponTwoName, weaponTwoDamage);

    // Serialize the FlatBuffer data.
    int name = builder.createString("Orc");
    byte[] treasure = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
    int inv = Monster.createInventoryVector(builder, treasure);
    int weapons = Monster.createWeaponsVector(builder, weaps);
    int pos = Vec3.createVec3(builder, 1.0f, 2.0f, 3.0f);

    Monster.startMonster(builder);
    Monster.addPos(builder, pos);
    Monster.addName(builder, name);
    Monster.addColor(builder, Color.Red);
    Monster.addHp(builder, (short)300);
    Monster.addInventory(builder, inv);
    Monster.addWeapons(builder, weapons);
    Monster.addEquippedType(builder, Equipment.Weapon);
    Monster.addEquipped(builder, weaps[1]);
    int orc = Monster.endMonster(builder);

    builder.finish(orc); // You could also call `Monster.finishMonsterBuffer(builder, orc);`.

    // We now have a FlatBuffer that can be stored on disk or sent over a network.

    // ...Code to store to disk or send over a network goes here...

    // Instead, we are going to access it right away, as if we just received it.

    ByteBuffer buf = builder.dataBuffer();

    // Get access to the root:
    Monster monster = Monster.getRootAsMonster(buf);

    // Note: We did not set the `mana` field explicitly, so we get back the default value.
    assert monster.mana() == (short)150;
    assert monster.hp() == (short)300;
    assert monster.name().equals("Orc");
    assert monster.color() == Color.Red;
    assert monster.pos().x() == 1.0f;
    assert monster.pos().y() == 2.0f;
    assert monster.pos().z() == 3.0f;

    // Get and test the `inventory` FlatBuffer `vector`.
    for (int i = 0; i < monster.inventoryLength(); i++) {
      assert monster.inventory(i) == (byte)i;
    }

    // Get and test the `weapons` FlatBuffer `vector` of `table`s.
    String[] expectedWeaponNames = {"Sword", "Axe"};
    int[] expectedWeaponDamages = {3, 5};
    for (int i = 0; i < monster.weaponsLength(); i++) {
      assert monster.weapons(i).name().equals(expectedWeaponNames[i]);
      assert monster.weapons(i).damage() == expectedWeaponDamages[i];
    }

    // Get and test the `equipped` FlatBuffer `union`.
    assert monster.equippedType() == Equipment.Weapon;
    Weapon equipped = (Weapon)monster.equipped(new Weapon());
    assert equipped.name().equals("Axe");
    assert equipped.damage() == 5;

    System.out.println("The FlatBuffer was successfully created and verified!");
  }
}

4. 保存或者发送到其他地方

5. 从二进制文件中读取对象

参考第3步。