数据管线基础使用

本章节将带你完成数据管线的第一次完整使用流程：

创建 Excel → QA 校验 → 自动生成代码 → 导出数据（JSON / 二进制）→ 运行时加载。

如果你从未使用过本框架数据管线，本章节是最推荐的入门方式。

在使用本章节前，请务必保证已进行过安装与初始化的流程。

1. 创建 Excel 配置表

在项目中，所有 Excel 文件需要放置于：项目根目录/FinkFramework_Data/DataTables

若该文件夹不存在，请手动创建。

创建一张新的表，例如：SimpleTestData.xlsx

Excel 的示例结构如下所示：

其中第三行注释行可留空。

DataTables 文件夹可包含任意子目录结构，例如：FinkFramework_Data/DataTables/Test/Example.xlsx

详细字段规则请查看下一章：
Excel配表规则

2. 打开数据工具窗口

在 Unity 菜单栏选择：FinkFramework → 数据工具面板。如下图：

你将看到数据管线的主界面，如下图所示：

3. 执行 QA 验证（可选）

点击：验证所有表格 按钮

工具将自动执行以下多项验证:

• 字段级非空与合法性检查
• 字段中变量名重复检查
• 数据行解析测试检查（逐格解析）
• 对每张表统计 汇总全局 QA 结果

如果 QA 未通过，则无法保证数据生成正确，建议在导出前执行一次。

若出现如下图所示——错误与警告均为0，则表示QA通过。

4. 自动处理全部数据

点击：一键处理全部数据 按钮

工具将自动执行以下操作：

4.1 清空旧生成的数据文件

包括：

• 外部 AutoExport 目录（JSON 输出）
• StreamingAssets 下旧的 JSON / 二进制数据
• PersistentDataPath 中旧的默认数据

相关路径由 DataPipelinePath 自动管理。

4.2 扫描表格并生成 C# 文件

自动生成两个文件：

• {ClassName}.cs —— 数据结构类
• {ClassName}Container.cs —— 数据容器类

生成位置取决于安装与初始化中的全局设置：

当使用内部 C# 输出时，会触发 Unity 自动重新编译，数据工具会在编译完成后继续导出流程。

4.3 导出 JSON 数据

无论选择何种数据源模式，JSON 都会被生成。

但导出位置根据当前数据源模式而不同：

JSON 导出路径由框架自动决定，无需配置。

4.4 生成二进制数据（可选）

若全局设置中 数据源为 Json 时，则不会生成二进制数据文件。

仅当全局数据源为 Binary 时，会为每张表生成一份二进制文件：

导出到：Assets/StreamingAssets/FinkFramework_Data/DataBinary

是否加密由全局设置控制：GlobalSettings.Current.EnableEncryption

二进制扩展名同样可在全局配置中自定义。

5. 在运行时访问数据

运行时无需知道文件路径、扩展名或数据源类型。所有解析与解密（若开启）都是自动完成的。

只需写（必须通过数据容器类的泛型访问）：

var simpleTestDataContainer = FilesUtil.LoadDefaultData<SimpleTestDataContainer>();

框架会根据当前模式自动选择数据源：

获取数据容器后，即可从变量获取任意数据源。表格从第四行起为数据行，对应items的索引号。
推荐使用IDE自带的断点调试功能来测试数据是否获取正确。
也可使用框架自带的LogUtil来代替Unity的Debug/print来简单测试数据。详情请见日志工具

LogUtil.Info(simpleTestDataContainer.items[0].name);
LogUtil.Info(simpleTestDataContainer.items[0].id.ToString());
LogUtil.Info(simpleTestDataContainer.items[0].position.ToString());

无需手动解密，无需手动反序列化，无需手动查找路径，全部是强类型访问。

若分别打印Wood、1001、(0.50, 1.00, 2.00) 则为成功。

关于更多运行时访问数据的内容，请查阅该文章：
运行时API