运行时 API 使用

本章介绍 Fink Framework 数据管线中所有运行时可直接调用的数据 API，包括：

• 数据文件读取（默认数据 / 本地文件）
• 本地数据保存
• 数据加密与解密
• 自动映射数据路径（按类型自动定位文件）
• 类型解析（支持数组、List、Dictionary、嵌套泛型）
• AES 加密 / 解密工具

运行时 API 主要集中在以下两个类中：

• FilesUtil —— 负责组装路径、查找文件、读写 StreamingAssets / PersistentDataPath
• DataUtil —— 负责序列化、反序列化、AES 加密与解密

本章将逐一说明每个方法的作用、使用场景与示例。

其中用户只需重点关注 数据读取API与数据保存API 即可，其余通常不需要用户手动调用，均为框架内部使用。

1. 数据读取 API

1.1 读取默认数据（只读）

默认数据位于：

• StreamingAssets/FinkFramework_Data/DataJson
• StreamingAssets/FinkFramework_Data/DataBinary

特点：

• 只读，一般用于数值配置，无需存档的数据
• 随应用程序打包
• 若不传路径，会自动根据类型查找对应文件所在的路径（根据文件名匹配）

使用方法示例：

var cfg = FilesUtil.LoadDefaultData<T>(string relativePath = null);

其中relativePath可传空。
其中T为需要读取的强类型数据容器类。
若不传路径，会自动根据类型定位对应文件。例如：

• PlayerSaveDataContainer → 匹配 StreamingAssets/FinkFramework_Data/DataBinary/PlayerSaveData.自定义后缀名

1.2 读取本地数据（可读可写）

本地数据位于：

• PersistentDataPath/FinkFramework_Data/DataBinary
• PersistentDataPath/FinkFramework_Data/DataJson

特点：

• 可读可写，一般用于用户存档、用户设置等数据
• 若本地文件不存在，会自动从 StreamingAssets 复制默认文件
• 支持 AES 解密

使用方法示例：

var save = FilesUtil.LoadLocalData<PlayerSaveData>();

其中relativePath可传空。
其中T为需要读取的强类型数据容器类。
若不传路径，会自动根据类型定位对应文件。

2. 数据保存 API

用于保存玩家设置、玩家存档等。

2.1 保存本地数据

特点：

• 自动创建文件夹
• 自动加密
• 自动根据类名定位路径

使用方法示例：

FilesUtil.SaveLocalData<T>(T data, string relativePath = null);

其中relativePath可传空。
其中data为需要存储的数据实例。
若不传路径，会自动根据类型定位对应文件。

3. AES 加密与解密

若全局设置中 数据源选择了 二进制模式，则默认进行AES加密。
可在全局设置中 自行选择是否开启加密。
框架内部在 DataUtil.Save / Load 中自动完成加密/解密，因此用户一般无需手动调用。

4. 路径相关处理API

框架内部在加载与保存数据时，会自动处理对应的路径逻辑。
这些 API 通常由框架内部使用，用户一般无需手动调用。

4.1 NormalizePath

将任意形式的路径标准化，保证在不同平台上表现一致。

功能：

• 统一路径分隔符为 /
• 去除多余空格与多余的斜杠
• 不会误删绝对路径前缀（例如 http://、C:/）

示例：

string p = FilesUtil.NormalizePath("Data\\Player\\Save");

4.2 BuildFullPath

用于拼接文件的完整路径，并根据当前数据源模式（JSON / Binary）自动补上扩展名。

注意：

• 不会决定使用 StreamingAssets 或 PersistentDataPath — 由调用者传入 basePath 决定
• 若 isAddExtension = true 会自动补齐正确的扩展名: JSON 模式 → .json, Binary 模式 → GlobalSettings.Current.EncryptedExtension

string full = FilesUtil.BuildFullPath(
    Application.persistentDataPath,
    "FinkFramework_Data/DataLocal/PlayerSaveData",
    true
);

若当前模式为 JSON → 自动补 .json
若当前模式为 Binary → 自动补 .fink（或你自定义的扩展名）

4.3 EnsureDirectory

确保路径对应的文件夹已存在，否则自动创建。

FilesUtil.EnsureDirectory(path);

框架在保存本地数据、拷贝 StreamingAssets 默认文件时会自动调用。

5. 泛型类型映射

框架内部会自动动态解析类型，因此用户一般无需手动调用。

5.1 FindType

支持：

• int / float / bool / string 等基础类型
• Vector2 / Vector3 / Color / Matrix4x4 等Unity常用类型
• 数组类型（如ItemData[]）
• 常用泛型定义映射(如列表、字典、哈希表等)
• 反射查找同名类型
• 查找所有程序集中的类型

示例：

Type t = DataUtil.FindType("Dictionary<string, int>");

5.2 FindGenericType

支持查找多层嵌套类型等复杂结构：

Dictionary<string, List<ItemData>>
List<Dictionary<int, SkillData>>

示例：

var t = DataUtil.FindGenericType("Dictionary<string, List<SkillData>>");

6. 序列化与反序列化

框架内部会自动进行序列化和反序列化，因此用户一般无需手动调用。

框架底层使用 OdinSerializer，支持：

• Vector/Color 等 Unity 类型
• 自定义数据结构
• 数组与嵌套泛型
• 深度复制

6.1 序列化对象

DataUtil.Save(path, data);

6.2 反序列化对象

var obj = DataUtil.Load<PlayerData>(path);

通过 FilesUtil + DataUtil，你可以在游戏中轻松做到：

• 加载配置
• 保存玩家存档
• 加载默认模板数据
• 读取加密 JSON / 二进制
• 高度通用的类型解析（支持复杂 Excel 字段）

本章节为所有运行时层的数据交互提供了统一入口。