FlatBuffers学习笔记一——初识FlatBuffers

一、文件下载

1.下载flatc.exe工具和FlatBuffers源码，链接请点我； 
2.用Visual Studio打开源码/net/FlatBuffers/FlatBuffers.csproj项目，编译输出类库文件FlatBuffers.dll； 
3.查看官方说明文档请点我； 
4.官方C#示例代码可见源码/tests/FlatBuffers.Test工程

 

二、工具介绍

1.flatc.exe

   此文件是根据fbs文件生成解析数据的代码文件，如果是C#的话，那么就生成cs代码文件;

2.fbs文件

   此文件用于定义数据文件的文件格式，类似mysql数据库中的表结构，不包括表数据;

3.FlatBuffers.dll

   flac.exe生成的代码文件通过该文件来解析数据;

 

三、开始使用

1.编写fbs文件

   例如文件名: MyGame.fbs

// 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.
}

table Weapon {
  name:string;
  damage:short;
}

root_type Monster;

2.生成代码文件

   这里我们只生成C#代码文件, 可以在CMD工具栏中通过命令行生成，也可以使用下面的代码生成：

D:\Projects\FlatBuffers\Test\flatc.exe -n --gen-onefile MyGame.fbs
@pause

   将上面的两行代码保存到compile.bat文件中，然后双击compile.bat文件看看有什么结果。

3.flatc参数的含义

   我们可以通过flatc.exe /?命令来查看参数的含义，如下：

D:\Projects\FlatBuffers\Test>flatc.exe /?
flatc.exe: error: no options: specify at least one generator.
Usage: flatc.exe [OPTION]... FILE... [-- FILE...]
  --binary     -b    Generate wire format binaries for any data definitions.
  --json       -t    Generate text output for any data definitions.
  --cpp        -c    Generate C++ headers for tables/structs.
  --go         -g    Generate Go files for tables/structs.
  --java       -j    Generate Java classes for tables/structs.
  --js         -s    Generate JavaScript code for tables/structs.
  --dart       -d    Generate Dart classes for tables/structs.
  --ts         -T    Generate TypeScript code for tables/structs.
  --csharp     -n    Generate C# classes for tables/structs.
  --python     -p    Generate Python files for tables/structs.
  --lobster          Generate Lobster files for tables/structs.
  --lua        -l    Generate Lua files for tables/structs.
  --rust       -r    Generate Rust files for tables/structs.
  --php              Generate PHP files for tables/structs.
  --jsonschema       Generate Json schema.
  -o PATH            Prefix PATH to all generated files.
  -I PATH            Search for includes in the specified path.
  -M                 Print make rules for generated files.
  --version          Print the version number of flatc and exit.
  --strict-json      Strict JSON: field names must be / will be quoted,
                     no trailing commas in tables/vectors.
  --allow-non-utf8   Pass non-UTF-8 input through parser and emit nonstandard
                     \x escapes in JSON. (Default is to raise parse error on
                     non-UTF-8 input.)
  --natural-utf8     Output strings with UTF-8 as human-readable strings.
                     By default, UTF-8 characters are printed as \uXXXX escapes.
  --defaults-json    Output fields whose value is the default when
                     writing JSON
  --unknown-json     Allow fields in JSON that are not defined in the
                     schema. These fields will be discared when generating
                     binaries.
  --no-prefix        Don't prefix enum values with the enum type in C++.
  --scoped-enums     Use C++11 style scoped and strongly typed enums.
                     also implies --no-prefix.
  --gen-includes     (deprecated), this is the default behavior.
                     If the original behavior is required (no include
                     statements) use --no-includes.
  --no-includes      Don't generate include statements for included
                     schemas the generated file depends on (C++).
  --gen-mutable      Generate accessors that can mutate buffers in-place.
  --gen-onefile      Generate single output file for C# and Go.
  --gen-name-strings Generate type name functions for C++.
  --gen-object-api   Generate an additional object-based API.
  --gen-compare      Generate operator== for object-based API types.
  --cpp-ptr-type T   Set object API pointer type (default std::unique_ptr)
  --cpp-str-type T   Set object API string type (default std::string)
                     T::c_str() and T::length() must be supported
  --gen-nullable     Add Clang _Nullable for C++ pointer. or @Nullable for Java
  --object-prefix    Customise class prefix for C++ object-based API.
  --object-suffix    Customise class suffix for C++ object-based API.
                     Default value is "T"
  --no-js-exports    Removes Node.js style export lines in JS.
  --goog-js-export   Uses goog.exports* for closure compiler exporting in JS.
  --es6-js-export    Uses ECMAScript 6 export style lines in JS.
  --go-namespace     Generate the overrided namespace in Golang.
  --go-import        Generate the overrided import for flatbuffers in Golang.
                     (default is "github.com/google/flatbuffers/go")
  --raw-binary       Allow binaries without file_indentifier to be read.
                     This may crash flatc given a mismatched schema.
  --size-prefixed    Input binaries are size prefixed buffers.
  --proto            Input is a .proto, translate to .fbs.
  --oneof-union      Translate .proto oneofs to flatbuffer unions.
  --grpc             Generate GRPC interfaces for the specified languages
  --schema           Serialize schemas instead of JSON (use with -b)
  --bfbs-comments    Add doc comments to the binary schema files.
  --bfbs-builtins    Add builtin attributes to the binary schema files.
  --conform FILE     Specify a schema the following schemas should be
                     an evolution of. Gives errors if not.
  --conform-includes Include path for the schema given with --conform
    PATH
  --include-prefix   Prefix this path to any generated include statements.
    PATH
  --keep-prefix      Keep original prefix of schema include statement.
  --no-fb-import     Don't include flatbuffers import statement for TypeScript.
  --no-ts-reexport   Don't re-export imported dependencies for TypeScript.
  --reflect-types    Add minimal type reflection to code generation.
  --reflect-names    Add minimal type/name reflection.
  --root-type T      Select or override the default root_type
  --force-defaults   Emit default values in binary output from JSON
  --force-empty      When serializing from object API representation,                      force strings and vectors to empty rather than null.
FILEs may be schemas (must end in .fbs), or JSON files (conforming to preceding
schema). FILEs after the -- must be binary flatbuffer format files.
Output files are named using the base file name of the input,
and written to the current directory or the path given by -o.
example: flatc.exe -c -b schema1.fbs schema2.fbs data.json

通过参数说明我们知道:

-n   表示生成C#代码

--gen-onefile 表示将文件中的多个结构体生成到一个代码文件中，如果不加这个参数，那么有几个结构体就会生成几个代码文件.

 

至此我们就把flatc.exe的用法搞明白了，最终我们是希望生成并解析FlatBuffers格式的二进制文件，那么第二讲我会讲解如何使用生成的代码文件来生成二进制流文件，然后就会用到FlatBuffers.dll了。