DataTables.API 1.0.6

Table of Contents

• 🚀 DataTables - 现代化高性能数据表系统
  • 📚 文档导航
  • 🚀 快速开始
    • .NET Core 项目
    • Unity项目
  • 🆕 新API指南
    • 核心API对比
    • 现代异步模式
    • 独立 DataTableContext
    • 智能配置系统
    • 可组合数据源配置示例
      • 本地包 / StreamingAssets
      • 远程 CDN
      • 热更新 / 回退链路
  • ⚡ 性能优化
    • 智能预热策略
    • 性能监控与统计
    • Hook机制 2.0
  • 🎮 Unity集成
    • 现代Unity最佳实践
    • Unity性能优化技巧
  • 🎯 高级功能
    • 自定义数据源
    • 工厂模式优化
    • 内存管理深度控制
  • 📋 数据表格式
    • 表格型(Table)格式
    • 索引声明与查询 API
    • 支持的数据类型
  • 🛠️ 代码生成器
    • CLI工具安装
    • 现代化生成命令
    • 解析选项与诊断
      • 标签过滤语法（TFE Lite）
    • MSBuild集成
  • 📈 迁移指南
    • 从旧版本升级
    • 渐进式升级策略
    • API映射表
  • 🏆 性能基准
  • 📜 License
  • 🌟 支持项目
  • Binary format upgrade and compatibility

🚀 DataTables - 现代化高性能数据表系统

异步优先数据表解决方案 - 适用于.NET Core服务端与Unity客户端

📚 文档导航

项目文档已按同类 .NET/Unity 开源项目常见实践分区维护：

• 文档中心：文档结构、阅读路径与维护规范。
• 表类型指南：table、matrix、column、kv、tree、graph 等表类型说明。
• 数据源管线：本地、远程、缓存、校验与回退链路。
• 二进制格式 v3：运行时 .bytes 文件格式与兼容策略。
• v3 迁移指南：升级到 v3 的生成物与数据迁移流程。

🚀 快速开始

.NET Core 项目

1. 安装NuGet包

dotnet add package DataTables.API

2. 零心智负担使用 🎉

using System;
using System.Threading.Tasks;
using DataTables;

public class Program
{
    public static async Task Main()
    {
        // 🌟 现代异步API - 自动初始化
        var scene = await DataTableManager.LoadAsync<DTScene>();
        var items = DataTableManager.GetCached<DTItem>(); // 缓存查询

        Console.WriteLine($"场景: {scene?.Name}, 物品数量: {items?.Count ?? 0}");

        // 🔥 可选的性能优化
        await DataTableManager.PreheatAsync(Priority.Critical | Priority.Normal);
        Console.WriteLine("数据预热完成！");
    }
}

3. 智能配置 (可选)

// 🎯 一行代码完成所有配置
DataTableManager.UseFileSystem("./DataTables");
DataTableManager.EnableMemoryManagement(50); // 50MB智能缓存
DataTableManager.EnableProfiling(stats =>
    Console.WriteLine($"加载{stats.TableCount}个表，耗时{stats.LoadTime}ms"));

Unity项目

1. 安装Unity Package

   • 从Releases下载DataTables.Unity.unitypackage

2. 现代化Unity使用

运行时源码同步约定：src/DataTables 是运行时源码的唯一修改源；src/DataTables.Unity/Assets/Scripts/DataTables/Runtime 是构建 src/DataTables/DataTables.csproj 后自动同步出的 Unity 镜像，按 Core、Caching、Sources、Protocol 分层。请不要直接修改 Unity 镜像中的 .cs 文件。提交前可运行 dotnet build -c Debug，再运行 ./scripts/verify-unity-runtime-sync.sh 和 git diff --exit-code -- src/DataTables.Unity/Assets/Scripts/DataTables，确保 Unity 包与主运行时一致。

using System;
using DataTables;
using UnityEngine;

public class GameManager : MonoBehaviour
{
    // Unity生命周期入口允许 async void；请在方法内捕获异常，避免异常丢失。
    async void Start()
    {
        try
        {
            // 🌟 异步优先 - 无阻塞启动
            var config = await DataTableManager.LoadAsync<DTGameConfig>();
            Debug.Log($"游戏版本: {config?.Version}");

            // 🔥 智能分层预热
            await DataTableManager.PreheatAsync(Priority.Critical);
            Debug.Log("关键数据预热完成，游戏可以启动！");

            // 后台预热其他数据
            _ = DataTableManager.PreheatAsync(Priority.Normal | Priority.Lazy);
        }
        catch (Exception ex)
        {
            Debug.LogException(ex);
        }
    }
}

🆕 新API指南

核心API对比

现代异步模式

// 🌟 推荐的现代异步模式

// 单表异步加载
var scene = await DataTableManager.LoadAsync<DTScene>();

// 并发加载多表
var tasks = new[]
{
    DataTableManager.LoadAsync<DTScene>(),
    DataTableManager.LoadAsync<DTItem>(),
    DataTableManager.LoadAsync<DTCharacter>()
};
var results = await Task.WhenAll(tasks);

// 缓存优先查询 (热路径)
var cachedScene = DataTableManager.GetCached<DTScene>();
if (cachedScene != null)
{
    var sceneData = DTScene.GetDataRowById(1001);
    Console.WriteLine($"场景名称: {sceneData?.Name}");
}

独立 DataTableContext

DataTableManager 是默认上下文的静态兼容门面。服务端多租户、测试隔离或同时加载多套配置时，直接实例化独立上下文：

using var context = new DataTableContext(new FileSystemDataSource("./DataTables/TenantA"));
context.EnableMemoryManagement(50);

// 生成的清单支持注册到指定上下文
DataTableManagerExtension.Register(context);
await context.PreheatAsync(Priority.Critical | Priority.Normal);

var sceneTable = await context.LoadAsync<DTScene>();
var scene = sceneTable?.GetDataRowById(1001);

每个上下文独立持有数据源、单飞加载任务、LRU 缓存、生命周期版本、统计和 Hook；清理或切换一个上下文不会影响其他实例。

智能配置系统

// 🎯 统一配置接口

// 文件系统数据源 (默认)
DataTableManager.UseFileSystem("./DataTables");

// 网络数据源
DataTableManager.UseNetwork("https://cdn.game.com/data/");

// 自定义数据源
DataTableManager.UseCustomSource(new MyCustomDataSource());

// 内存管理 (LRU缓存)
DataTableManager.EnableMemoryManagement(100); // 100MB限制

// 性能监控
DataTableManager.EnableProfiling(stats =>
{
    Console.WriteLine($"加载了 {stats.TableCount} 个表");
    Console.WriteLine($"总耗时: {stats.LoadTime}ms");
    Console.WriteLine($"内存使用: {stats.MemoryUsed / 1024 / 1024:F1}MB");
});

可组合数据源配置示例

本地包 / StreamingAssets

// 兼容原有 API：本地 .bytes 文件仍可直接使用
DataTableManager.UseFileSystem("./DataTables");

// Unity 项目可预留 StreamingAssets 入口
DataTableManager.UseDataSource(
    new CachedDataSource(
        new StreamingAssetsDataSource(Application.streamingAssetsPath + "/DataTables")));

远程 CDN

// 兼容原有网络 API
DataTableManager.UseNetwork("https://cdn.game.com/data");

// 可按需叠加版本、压缩、加密与内存缓存装饰器
IDataSource cdnSource = new CachedDataSource(
    new CompressedDataSource(
        new VersionedDataSource(
            new NetworkDataSource("https://cdn.game.com/data"),
            "v42")));

DataTableManager.UseDataSource(cdnSource);

热更新 / 回退链路

// 优先读取热更新 CDN，失败或不存在时回退到随包数据
var hotUpdate = new VersionedDataSource(
    new NetworkDataSource("https://cdn.game.com/hotfix"),
    "2026.07.06");

var builtin = new StreamingAssetsDataSource(Application.streamingAssetsPath + "/DataTables");

DataTableManager.UseCompositeSource(hotUpdate, builtin);

// Addressables 可继承 AddressablesDataSourceBase 后接入项目内的 Addressables.LoadAssetAsync<TextAsset>()。

⚡ 性能优化

智能预热策略

// 🔥 现代预热API - 基于优先级的智能调度

// 客户端：分层预热
await DataTableManager.PreheatAsync(Priority.Critical);           // 立即加载关键数据
_ = DataTableManager.PreheatAsync(Priority.Normal | Priority.Lazy); // 后台预热其他数据

// 服务器：全量预热
var preheatStats = await DataTableManager.PreloadAllAsync();
Console.WriteLine($"预热完成: {preheatStats.SuccessCount} 成功, {preheatStats.FailureCount} 失败");

// 自定义预热 (并发安全)
var tasks = new[]
{
    DataTableManager.LoadAsync<DTConfig>(),
    DataTableManager.LoadAsync<DTLevel>(),
    DataTableManager.LoadAsync<DTCharacter>()
};
await Task.WhenAll(tasks);

PreheatAsync 会读取生成代码中的 DataTableManagerExtension.TableRegistrations，按 Priority 筛选后并发调用 LoadAsync<T>/CreateDataTableAsync<T>；返回的 LoadStats 包含本次预热的耗时、成功数、失败数与内存变化。GetStats() 返回进程内累计历史加载统计，而不是固定耗时。

性能监控与统计

// 📊 全面的性能监控

// 历史加载统计（LoadTime/MemoryUsed 为累计加载耗时与累计内存变化）
var stats = DataTableManager.GetStats();
Console.WriteLine($"已加载表数量: {stats.TableCount}");
Console.WriteLine($"累计加载耗时: {stats.LoadTime}ms");
Console.WriteLine($"成功/失败: {stats.SuccessCount}/{stats.FailureCount}");
Console.WriteLine($"累计内存变化: {stats.MemoryUsed / 1024 / 1024:F1}MB");

// 缓存统计
var cacheStats = DataTableManager.GetCacheStats();
if (cacheStats.HasValue)
{
    var cache = cacheStats.Value;
    Console.WriteLine($"缓存项数: {cache.TotalItems}");
    Console.WriteLine($"缓存命中率: {cache.HitRate:P}");
    Console.WriteLine($"内存使用率: {cache.MemoryUsageRate:P}");
}

// 加载状态检查
bool isLoaded = DataTableManager.IsLoaded<DTScene>();
Console.WriteLine($"场景表是否已加载: {isLoaded}");

Hook机制 2.0

// 🎣 简化的类型安全Hook系统

// 类型安全Hook
DataTableManager.OnLoaded<DTScene>(table =>
{
    Console.WriteLine($"✅ 场景表加载完成: {table.Count} 行数据");

    // 自定义后处理
    ValidateSceneData(table);
    BuildSceneIndex(table);
});

// 全局Hook
DataTableManager.OnAnyLoaded(table =>
{
    var typeName = table.GetType().Name;
    var loadTime = DateTime.Now;
    Console.WriteLine($"📊 [{loadTime:HH:mm:ss}] {typeName} 已加载");
});

// 清理Hook
DataTableManager.ClearHooks();

🎮 Unity集成

现代Unity最佳实践

using System;
using System.Threading.Tasks;
using DataTables;
using UnityEngine;

public class ModernDataTableDemo : MonoBehaviour
{
    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
    static void InitializeDataTables()
    {
        _ = InitializeDataTablesAsync();
    }

    static async Task InitializeDataTablesAsync()
    {
        try
        {
            // 🚀 启动时快速初始化
            DataTableManager.UseFileSystem(Application.streamingAssetsPath + "/DataTables");
            DataTableManager.EnableMemoryManagement(30); // Unity环境30MB限制

            // 立即加载核心表
            await DataTableManager.LoadAsync<DTGameConfig>();

            // 后台预热其他表
            _ = DataTableManager.PreheatAsync(Priority.Normal | Priority.Lazy);
        }
        catch (Exception ex)
        {
            Debug.LogException(ex);
        }
    }

    // Unity生命周期入口允许 async void；请在方法内捕获异常，避免异常丢失。
    async void Start()
    {
        try
        {
            // 🎯 场景相关数据预热
            await DataTableManager.PreheatAsync(Priority.Critical);
            Debug.Log("关键数据已就绪，游戏可以开始！");

            // 使用数据
            var config = DataTableManager.GetCached<DTGameConfig>();
            if (config != null)
            {
                var gameConfig = DTGameConfig.GetDataRowById(1);
                Debug.Log($"游戏版本: {gameConfig?.Version}");
            }
        }
        catch (Exception ex)
        {
            Debug.LogException(ex);
        }
    }

    void OnApplicationPause(bool pauseStatus)
    {
        if (pauseStatus)
        {
            // 暂停时清理缓存释放内存
            DataTableManager.ClearCache();
        }
    }
}

Unity性能优化技巧

using System.Threading.Tasks;

// 📱 移动平台优化

public class MobileOptimizationDemo : MonoBehaviour
{
    void Start()
    {
        // 根据设备性能调整缓存大小
        var systemMemory = SystemInfo.systemMemorySize;
        var cacheSize = systemMemory > 4096 ? 50 : 20; // 4GB+设备使用50MB，否则20MB
        DataTableManager.EnableMemoryManagement(cacheSize);

        // 监听内存警告
        Application.lowMemory += OnLowMemory;
    }

    private void OnLowMemory()
    {
        Debug.Log("收到内存警告，清理数据表缓存");
        DataTableManager.ClearCache();
    }

    // 场景切换时的优化策略：非Unity生命周期方法返回Task，便于调用方await并捕获异常。
    public async Task LoadSceneAsync(int sceneId)
    {
        var sceneConfig = DTScene.GetDataRowById(sceneId);

        // 预加载场景相关数据
        var preloadTasks = new[]
        {
            DataTableManager.LoadAsync<DTNpc>(),
            DataTableManager.LoadAsync<DTQuest>(),
            DataTableManager.LoadAsync<DTItem>()
        };

        await Task.WhenAll(preloadTasks);

        // 开始切换场景
        UnityEngine.SceneManagement.SceneManager.LoadScene(sceneConfig.SceneName);
    }
}

🎯 高级功能

自定义数据源

// 🔧 扩展自定义数据源

public class EncryptedDataSource : IDataSource
{
    private readonly string _baseDirectory;
    private readonly byte[] _encryptionKey;

    public EncryptedDataSource(string baseDirectory, byte[] encryptionKey)
    {
        _baseDirectory = baseDirectory;
        _encryptionKey = encryptionKey;
    }

    public async ValueTask<Stream> OpenReadAsync(string tableName, CancellationToken cancellationToken)
    {
        var filePath = Path.Combine(_baseDirectory, $"{tableName}.encrypted");
        var encryptedData = await File.ReadAllBytesAsync(filePath, cancellationToken);

        // 自定义解密逻辑
        return new MemoryStream(DecryptData(encryptedData, _encryptionKey), writable: false);
    }

    public ValueTask<bool> ExistsAsync(string tableName, CancellationToken cancellationToken)
        => ValueTask.FromResult(File.Exists(Path.Combine(_baseDirectory, $"{tableName}.encrypted")));

    public ValueTask<DataSourceManifest> GetManifestAsync(CancellationToken cancellationToken)
        => ValueTask.FromResult(DataSourceManifest.Empty);

    public ValueTask<bool> IsAvailableAsync(CancellationToken cancellationToken)
        => ValueTask.FromResult(Directory.Exists(_baseDirectory));

    private byte[] DecryptData(byte[] encryptedData, byte[] key)
    {
        // 实现你的解密算法
        return encryptedData; // 这里应该是解密后的数据
    }
}

// 使用自定义数据源
var encryptionKey = LoadEncryptionKey();
var encryptedSource = new EncryptedDataSource("./EncryptedData", encryptionKey);
DataTableManager.UseCustomSource(encryptedSource);

工厂模式优化

// 🏭 工厂模式 - 消除反射调用，提升90%性能

// 实现数据表工厂
public class DTSceneFactory : IDataTableFactory<DTScene, DRScene>
{
    public DTScene CreateTable(string name, int capacity)
        => new DTScene(name, capacity);

    public DRScene CreateRow()
        => new DRScene();
}

// 注册工厂 (通常由代码生成器自动完成)
DataTableManager.RegisterFactory<DTScene, DRScene, DTSceneFactory>();

// 注册后，表的创建将使用工厂模式，避免反射调用
var scene = await DataTableManager.LoadAsync<DTScene>(); // 90%性能提升！

内存管理深度控制

// 🧠 精确的内存管理控制

// 启用LRU缓存管理
DataTableManager.EnableMemoryManagement(50); // 50MB限制

// 监控内存使用
var cacheStats = DataTableManager.GetCacheStats();
if (cacheStats?.MemoryUsageRate > 0.8f) // 使用率超过80%
{
    Console.WriteLine("内存使用率较高，LRU将自动淘汰旧数据");
}

// 手动清理缓存
DataTableManager.ClearCache();

// 禁用内存管理 (如果需要)
DataTableManager.DisableMemoryManagement();

📋 数据表格式

表格型(Table)格式

Excel文件格式定义：

索引声明与查询 API

在 A1 表头中使用 Index= 声明唯一索引，使用 Group= 声明分组索引；组合索引用 & 固定字段顺序。生成器会在校验阶段检查字段是否存在、字段类型是否可作为字典 key、唯一索引是否重复，以及组合索引字段顺序是否稳定。

DTGen=Table, Title=场景表, Class=Scene, Index=Id, Index=Type&Level, Group=Type

生成代码会统一提供以下查询方法：

// 唯一索引：Index=Id
DRScene? row = DTScene.GetById(1001);
bool ok = DTScene.TryGetById(1001, out DRScene? found);
bool exists = DTScene.ContainsId(1001);

// 组合唯一索引：Index=Type&Level，调用参数顺序与声明顺序一致
DRScene? typed = DTScene.GetByTypeAndLevel(SceneType.Battle, 3);

// 分组索引：Group=Type
IReadOnlyList<DRScene>? scenes = DTScene.GetManyByType(SceneType.Battle);
bool hasGroup = DTScene.ContainsType(SceneType.Battle);

// 兼容旧 API：仍保留 GetDataRowByXxx/GetRowByXxx 与 GetDataRowsGroupByXxx/GetRowsGroupByXxx 别名。

索引字典在加载过程中使用可变字典构建，加载完成后通过只读字典接口暴露给查询 API，避免运行期查询路径产生额外锁或拷贝。

支持的数据类型

🛠️ 代码生成器

CLI工具安装

# 全局安装
dotnet tool install --global DataTables.Generator

# 本地安装
dotnet tool install --tool-path ./tools DataTables.Generator

现代化生成命令

# 基础生成
dotnet dtgen -i ./Tables -patterns "*.xlsx" -co ./Generated -do ./Data -n MyProject -p DR

# 高级生成
dotnet dtgen \
  -i "./Tables" \              # 输入目录
  -patterns "*.xlsx" \         # 输入文件模式
  -co "./Generated" \          # 代码输出目录
  -do "./Data" \               # 数据输出目录
  -n "MyProject" \             # 命名空间
  -p "DR" \                    # 数据行类前缀
  -t "RELEASE" \               # 列标签过滤
  -f                            # 强制覆写

解析选项与诊断

# 启用严格名称校验与公式一致性校验，并生成诊断报告
dotnet dtgen \
  -i "./Tables" -patterns "*.xlsx" -co "./Generated" -do "./Data" -n "MyProject" -p "DR" \
  --strictNameValidation true \
  --validateFormulaConsistency true \
  --formulaPolicy ValidateOnly \
  --columnCommentMarkerText "#列注释标志" \
  --rowCommentMarkerText "#行注释标志" \
  --skipCellMarker "#" \
  --arrayNestedSeparators "" \
  -t "CLIENT && !SERVER" \
  --diagnosticsJsonOutput diagnostics.json

# 关闭公式评估，快速导出
dotnet dtgen -i ./Tables -patterns "*.xlsx" -co ./Generated -do ./Data --formulaPolicy Off

# 自定义嵌套数组的分隔字符（解决 "id#count|id#count" 与单条目 "801000#2" 行为不一致问题）
# 字符位置 = 数组嵌套深度（从 1 开始）；为空时维持旧行为（优先 '|' 否则 '#'）
dotnet dtgen -i ./Tables -patterns "*.xlsx" -co ./Generated -do ./Data \
  --arrayNestedSeparators "|#-"   # 第 1 层 '|'，第 2 层 '#'，第 3 层 '-'

标签过滤语法（TFE Lite）

• 语法元素（大小写不敏感）：
  • 标识符：[A-Za-z0-9_]+
  • 布尔运算：AND、OR、NOT（别名：&&、||、!）
  • 括号：(、)
• 优先级：NOT > AND > OR
• 空表达式：视为 true（不过滤）
• Excel 标签标注：在列标题末尾用 @ 标注标签，多个标签可用空格、逗号、分号、竖线、中文逗号等分隔。
  • 示例：Hp@CLIENT、Atk@CLIENT,SERVER、Speed@client|pve
• 过滤表达式示例：
  • CLIENT AND NOT SERVER
  • (CLIENT OR EDITOR) AND NOT LEGACY
  • PVE || PVP
  • !INTERNAL

诊断报告（JSON）字段：

• InfoCount / WarningCount / ErrorCount
• Items: [ { Severity, File, Sheet, Cell, Message } ]

MSBuild集成

<ItemGroup>
    <PackageReference Include="DataTables.MSBuild.Tasks" Version="x.x.x" PrivateAssets="all" />
</ItemGroup>

<Target Name="DataTablesGen" BeforeTargets="BeforeBuild">
    <DataTablesGenerator
        UsingNamespace="$(ProjectName)"
        InputDirectories="$(ProjectDir)Tables"
        SearchPatterns="*.xlsx"
        CodeOutputDirectory="$(ProjectDir)Generated"
        DataOutputDirectory="$(ProjectDir)DataTables"
        PrefixClassName="DR"
        FilterColumnTags="RELEASE"
        ForceOverwrite="false" />
</Target>

📈 迁移指南

从旧版本升级

如果你目前使用传统的DataTableManager API：

// ❌ 旧版本方式 (仍然支持)
DataTableManager.SetDataTableHelper(new DefaultDataTableHelper("./Data"));
DataTableManagerExtension.Preload(() => Console.WriteLine("加载完成"));
DataTableManager.CreateDataTable<DTScene>(() => {
    var scene = DataTableManager.GetDataTable<DTScene>();
    var data = scene.GetDataRowById(2000);
});

// ✅ 升级到现代异步方式
DataTableManager.UseFileSystem("./Data");  // 一次性配置
var scene = await DataTableManager.LoadAsync<DTScene>(); // 异步加载
var data = DTScene.GetDataRowById(2000); // 直接访问

渐进式升级策略

1. 阶段1 - 兼容运行 (保持现有代码不变)

// 现有代码继续工作，无需修改
DataTableManager.SetDataTableHelper(helper);
var table = DataTableManager.GetDataTable<DTScene>();

2. 阶段2 - 新功能使用新API

// 新功能采用现代API
await DataTableManager.LoadAsync<DTNewTable>();
DataTableManager.EnableMemoryManagement(50);

3. 阶段3 - 逐步重构

// 逐步替换旧API调用
// DataTableManager.CreateDataTable<T>(callback)
// → await DataTableManager.LoadAsync<T>()

API映射表

🏆 性能基准

基于激进优化的性能表现：

📜 License

This library is under the MIT License.

🌟 支持项目

如果这个项目对你有帮助，请考虑：

• ⭐ 给项目点星
• 🐛 报告bug和建议
• 💡 贡献代码和文档
• 📢 向其他开发者推荐

感谢使用 DataTables！享受现代化高性能的开发体验！ 🚀

Binary format upgrade and compatibility

Starting with binary format version 3, generated .bytes files use a structured header before the row payload:

1. Signature (DTABLE)
2. FormatVersion
3. SchemaHash
4. GeneratorVersion
5. TableFullName
6. RowCount
7. Flags

The schema hash is calculated during generation from the effective exported schema: table type, table full name, and each non-ignored field's name, type, and order. Runtime loading validates the .bytes schema hash against the hash embedded in the generated table class, so a mismatch clearly indicates that the generated C# code and binary data were not produced from the same table schema.

Upgrade policy:

• Format version 3 is a breaking binary format used by the next major release; older format versions are not read by this runtime.
• Runtimes require the exact binary format version they were built for. When upgrading, regenerate both the C# table code and .bytes assets together and publish them with the matching major runtime.
• Flags is reserved for payload features such as compression, encryption, or an embedded default-value table. Unknown non-zero flags are rejected by the runtime until explicit support is added.