【Unix】FlatBuffers 在 C++ 项目中的使用教程

在 C++ 项目中使用 FlatBuffers 主要涉及以下几个步骤：

1. 安装 FlatBuffers

首先，你需要在你的系统上安装 FlatBuffers 编译器和库。你可以从 FlatBuffers 的 GitHub 仓库下载源码并编译：

git clone https://github.com/google/flatbuffers.git
cd flatbuffers
cmake -G "Unix Makefiles"
make

完成后，你将获得一个 flatc 编译器，这是用于将 FlatBuffers schema 文件（.fbs 文件）转换为各种支持的语言的源代码的工具。

2. 定义 Schema

创建一个 FlatBuffers schema 文件（扩展名为 .fbs）。这个文件定义了你想要序列化的数据结构。例如：

// example.fbs
namespace MyGame.Sample;

table Monster {
  id:int;
  name:string;
  inventory:[ubyte];  // Vector of unsigned bytes
}

root_type Monster;

3. 生成 C++ 源代码

使用 flatc 编译器从你的 schema 文件生成 C++ 绑定代码：

flatc -c example.fbs

这会生成一些 C++ 文件，这些文件提供了操作定义的 FlatBuffers 数据结构的 API。

4. 在项目中使用 FlatBuffers

将生成的代码和 FlatBuffers 的包含文件添加到你的 C++ 项目中。你需要包括 FlatBuffers 的库路径和头文件路径在你的编译设置中。

5. 读写 FlatBuffers 数据

写入数据

在 C++ 中构建和序列化 FlatBuffers 数据：

#include "example_generated.h"  // 自动生成的头文件

flatbuffers::FlatBufferBuilder builder;

auto name = builder.CreateString("Orc");
auto inventory = builder.CreateVector(std::vector<uint8_t>({1, 2, 3, 4}));

auto orc = MyGame::Sample::CreateMonster(builder, 123, name, inventory);
builder.Finish(orc);

// 获取生成的数据和大小
uint8_t *buf = builder.GetBufferPointer();
int size = builder.GetSize();  // 使用这些数据

代码解读：

包含生成的头文件

#include "example_generated.h"  // 自动生成的头文件

这行代码包含了由 FlatBuffers 编译器 (flatc) 根据你的 .fbs schema 文件自动生成的 C++ 头文件。这个头文件中定义了与 schema 中定义的数据结构对应的 C++ 类和方法。

初始化 FlatBufferBuilder

flatbuffers::FlatBufferBuilder builder;

这行代码创建了一个 FlatBufferBuilder 对象，名为 builder。FlatBufferBuilder 是用于构建 FlatBuffer 二进制缓冲区的主要工具。这个对象会管理内存分配，并最终产生一个二进制缓冲区，其中包含序列化的数据。

创建字符串

auto name = builder.CreateString("Orc");

这行代码使用 builder 对象创建了一个 FlatBuffers 字符串。这里，字符串 “Orc” 被添加到构建中的 FlatBuffers 中，并返回一个指向这个 FlatBuffers 字符串的引用。

创建向量

auto inventory = builder.CreateVector(std::vector<uint8_t>({1, 2, 3, 4}));

这行代码创建了一个类型为 uint8_t 的向量，并将其内容初始化为 {1, 2, 3, 4}。然后，它使用 builder 将这个向量添加到 FlatBuffer 中，并返回一个指向 FlatBuffers 中向量的引用。

构建 Monster 对象

auto orc = MyGame::Sample::CreateMonster(builder, 123, name, inventory);

这行代码调用一个由 FlatBuffers 自动生成的函数 CreateMonster，这个函数根据给定的参数构造 Monster 对象。这里传递的参数包括 builder、一个整数 ID (123)、前面创建的 name 字符串引用和 inventory 向量引用。

完成构建过程

builder.Finish(orc);

这行代码标记 FlatBuffers 构建的完成，这里的 orc 是 Monster 对象在 FlatBuffer 中的引用。调用 Finish 方法后，FlatBuffer 中的数据布局被最终确定，并准备好序列化输出。

获取缓冲区指针和大小

uint8_t *buf = builder.GetBufferPointer();
int size = builder.GetSize();  // 使用这些数据

这两行代码获取生成的 FlatBuffers 二进制数据的指针和大小。buf 是指向 FlatBuffers 缓冲区起始位置的指针，size 是缓冲区的字节大小。这些信息通常用于将序列化的数据发送到文件、网络或其他存储和通信媒介。

这段代码代码整体的作用就是使用 FlatBuffers 在 C++ 中定义、填充并序列化一个复杂的数据结构。这种序列化的数据可以高效地进行存储或网络传输，并且可以在不需要解析整个结构的情况下直接访问特定字段，这是 FlatBuffers 设计的一大优势。

读取数据

解析 FlatBuffers 数据：

#include "example_generated.h"  // 自动生成的头文件

void ReadMonster(const uint8_t *buf) {
    auto monster = MyGame::Sample::GetMonster(buf);
    std::cout << "Monster ID: " << monster->id() << std::endl;
    std::cout << "Monster Name: " << monster->name()->str() << std::endl;

    auto inv = monster->inventory();
    if (inv) {
        std::cout << "Inventory: ";
        for (auto it = inv->begin(); it != inv->end(); ++it) {
            std::cout << int(*it) << ' ';
        }
        std::cout << std::endl;
    }
}

// 调用
ReadMonster(buf);