Revolution 导表工具 · 架构解析

源设计起源 · 为什么要做这个模块

• 没有它，Excel 和业务代码之间就是手工搬运 + 运行时反射：工具把"读 Excel → 生成强类型结构体 + 容器 + 数据文件"固定成一条流水线，业务侧只用 await RevDataTableManager.LoadAsync<某表>() 取表，不必在运行时反射逐个字段去塞。
• 数据做成 struct、字段用 public，是为了性能与零开销：值类型让上万行配置不产生托管堆分配；生成代码直接给 public 字段赋值，做到零反射、零装箱。
• 数据文件用纯文本 TXT，不是 json / 二进制：为的是可读、可 diff、可手工核对 —— 出问题时能直接看、直接比对。
• 错误要在导出时炸，而不是运行时：主键为空 / 重复、类型写错、字段名不是合法标识符，都在导出前全量校验，报错带 Excel 行号（如"第 5 行 [Cost]：abc 不是合法的 int"），能直接指给策划；坏表跳过，其它表照常导出。
• 两个导出按钮，是为了别动不动就全量重编译：只改数值时用"仅生成数据"：只写数据 txt、一个代码文件都不碰，回到 Unity 不会触发脚本重编译。

更完整的"早期版本 vs 新版 / 为什么重写"论证，见同目录《导表工具对比与设计说明》。

本篇只讲为什么；怎么用见同目录《使用说明》。

0三句话速览（完整用法见《使用说明》）

① 写 Excel：第 1 行字段名 / 第 2 行类型 / 第 3 行描述 / 第 4 行起数据（第一个字段是主键）
② 启动工具 → 选 Excel → 读取 → 选三个输出目录 → 开始导出
③ 把 Code\ 拷到 Assets/Revolution/Generation\，把 Data\ 拷到 「资源根目录」\Data\（如 Assets/GameRes/Data）
④ 业务代码：
     await RevDataTableManager.LoadAsync<HeroTable>();
     HeroTable.Instance.FindByKey(1001, out var h);

1准备

1.1 运行环境

• .NET 8 桌面运行时（Windows）。工程目标框架是 net8.0-windows。
• 工具是 WPF 独立程序，不需要开 Unity，也不需要装 Excel（自带 xlsx 解析）。

1.2 启动方式

# 方式一：命令行（开发期常用）
cd RevolutionFramework\Revolution.ExcelTool
dotnet run

# 方式二：直接跑 exe（打包给策划/TA 用）
Revolution.ExcelTool\bin\Debug\net8.0-windows\Revolution.ExcelTool.exe

1.3 界面长什么样

首次启动会自动猜你的 Unity 工程路径（在工具目录附近找 RevolutionFrameWork_Unity），猜到了就预填好三个输出目录；猜不到也不影响使用，手动选一下即可。

2Excel 该怎么写

2.1 四行结构（这是唯一的契约）

• 第一个字段（第一列）就是主键，不需要额外标记。
• 一个工作表 = 一张表，表名就是工作表名（Hero → 生成 Hero 结构体 + HeroTable 容器）。

2.2 一个完整示例（可以直接抄）

工作表名：Hero

工作表名：Buff（演示 string 主键）

2.3 列的处理规则

2.4 行的处理规则

3字段类型与取值规则

3.1 四种类型

大小写不敏感、前后空格会被去掉（Int、 int 都认）。

3.2 容错与默认值

bool 认这些写法（不区分大小写）：

4主键规则

字符串主键的典型用法（业务代号做主键）：

BUFF_ATK_UP / DEBUFF_STUN / ITEM_SWORD_01

运行时就是：

BuffTable.Instance.FindByKey("BUFF_ATK_UP", out Buff buff);

5命名规则

5.1 字段名 → C# 字段名

5.2 表名（工作表名）→ 类名

工作表名 "Hero"      → 结构体 Hero      + 容器 HeroTable     + 数据文件 Hero.txt
工作表名 "Buff"      → 结构体 Buff      + 容器 BuffTable     + 数据文件 Buff.txt
工作表名 "HeroSkin"  → 结构体 HeroSkin  + 容器 HeroSkinTable + 数据文件 HeroSkin.txt

6界面操作流程（六步）

• 选数据源
  「选择文件」→ 可多选 .xlsx（Excel 的临时文件 ~$xxx.xlsx 会自动跳过）；
  「选择目录」→ 扫描该目录下顶层的所有 .xlsx（不递归）。
  选中后会自动读取一次。
  源会被记住：下次启动会自动加载上次的源（窗口先出来，表随后加载）； 点「选择文件 / 选择目录」时，对话框也直接落在上次那个目录。 源要是已被删 / 改名，只在日志里提示一句（不会刷红色错误），点「选择文件」重选即可。
• 点「读取」
  日志里会列出每张表：### 表 Hero：主键=ID(int)，9 字段 / 5 行 / 有效=True；有问题的表会打出 [提示] / [错误]。
• 看左侧「表列表」　每项显示"字段数 · 行数"；有错误的表会标红（点开看预览区里的具体错误）。
• 看右侧「表结构预览」　显示字段摘要（★ID:int，Name:string…）+ 数据前 50 行，可以直接核对。
• 选三个输出目录（选过就会被记住，下次启动自动填回）

  输出	建议位置	说明
  数据结构类目录	Assets\Revolution\Generation\DataStructures	生成 RevDataStructures.cs
  容器类目录	Assets\Revolution\Generation\RevDataTables	生成 RevDataTables.cs
  TXT 数据文件目录	<资源根目录>\Data（如 Assets\GameRes\Data）	每张表一个 <表名>.txt

  工具与 Unity 完全解耦：不预填、也不读 Unity 那边的配置，只记住你自己上次用过的源与目录 —— 存在本机 %APPDATA%\Revolution\ExcelTool\settings.txt。想让它忘掉，删掉那个文件即可。
  目录不存在也没关系，导出时会自动创建。
• 点「全量生成（代码+数据）」或「仅生成数据」 → 看⑥日志区

  数据结构类 → ...\RevDataStructures.cs
  容器类     → ...\RevDataTables.cs
  数据文件   → ...\Data（4 个表，18 条数据）
  导出成功：4 张表，共 18 条数据。

  两个按钮怎么选：改了表结构（加字段 / 改类型 / 增删表）→ 「全量生成（代码+数据）」（代码 + 数据一起重新生成）； 只改了 Excel 里的数值 → 「仅生成数据」：只写数据 txt，一个代码文件都不碰 —— 回到 Unity 也不会触发脚本重编译（省掉十几秒起步的一次全量编译）。

7输出物详解

7.1 RevDataStructures.cs（数据结构类）

namespace Revolution
{
    /// <summary>Hero —— 配置表的一条数据（对应 Excel 一行；struct：值类型，零 GC）</summary>
    [Serializable]
    public struct Hero
    {
        /// <summary>英雄ID（★ 主键）</summary>
        public int Id;

        /// <summary>英雄名</summary>
        public string Name;
        // ...
    }
}

• struct 而不是 class：上万行配置不会在托管堆上分配，几乎不产生 GC。
• 字段是 public 字段（不是属性）—— 生成代码直接赋值，零反射零装箱。
• 描述来自 Excel 第 3 行，直接变成 XML 注释，写代码时鼠标悬停就能看到。

7.2 RevDataTables.cs（容器类）

namespace Revolution
{
    /// <summary>Hero 表的容器（主键：ID，9 个字段，5 条数据）</summary>
    public sealed class HeroTable : RevDataTable<int, Hero>
    {
        /// <summary>便捷访问；未加载时为 null（先 RevDataTableManager.LoadAsync<HeroTable>()）</summary>
        public static HeroTable Instance => RevDataTableManager.Get<HeroTable>();

        public HeroTable() : base("Hero") { }

        protected override int GetKey(in Hero data) => data.Id;

        protected override bool ParseRow(string[] cells, out Hero data)
        {
            data = default;
            if (cells.Length < 9) return false;      // 列数不够 → 数据文件与结构不匹配

            data.Id = RevDataFieldParser.ToInt(cells[0]);      // 英雄ID
            data.Name = RevDataFieldParser.ToStr(cells[1]);    // 英雄名
            // ...
            return true;
        }
    }
}

每张表只生成两个方法（GetKey / ParseRow），查询能力全部继承自运行时基类 RevDataTable<TKey, TData>：

一张表生成代码只有二十来行，而且改工具重新生成时不会动到数据结构文件（两个文件分开的用意）。

7.3 TXT 数据文件

以 Buff.txt 为例：

#Buff
#ID	Name	Type	Duration	Stackable	Desc
#状态ID	状态名	类型	持续(秒)	可否叠加	状态描述
BUFF_ATK_UP	攻击提升	1	5	false	攻击力提升 20%
DEBUFF_STUN	眩晕	3	1.5	false	无法移动与释放技能

格式规范：

转义规则（字符串里出现这些字符时会被写成两个字符，运行时还原）：

空白单元格：保留为空，运行时取该类型的默认值：

3004	女王崇拜	1002	35		true	连续三次冲击...   ← Damage 列空着 → 运行时读到 0f

为什么用 txt 而不是 json / 二进制：可读、可 diff、可手工核对（详见对比文档第三章）。

8接入 Unity

8.1 两个输出目录怎么选

Revolution.Demo\ExcelTool\Code\   →   Assets\Revolution\Generation\   ← 生成代码（asmdef 已引用 Revolution.Runtime）
Revolution.Demo\ExcelTool\Data\   →   Assets\GameRes\Data\             ← 数据文件（逻辑路径正好是 Data\<表名>）

• Assets\Revolution\Generation\ 下的 Revolution.Generation.asmdef 已引用 Revolution.Runtime，所以生成出来的容器类能直接继承 RevDataTable<,>。
• Assets\GameRes\ 只是示例：资源根目录由你在打包工具窗口里配置（代码里没有默认值），放在根目录下的文件逻辑路径 = 相对路径去掉扩展名，所以 <资源根目录>/Data/Hero.txt 的逻辑路径就是 Data/Hero —— 正好等于生成代码里 base("Hero") 推出的默认路径。

导出后回 Unity，会自动刷新并编译（日志里也会提示）。

8.2 运行时加载（三行）

// ① 加载（走资源系统：编辑器直读工程、真机走 AB）
await RevDataTableManager.LoadAsync<HeroTable>();

// ② 查询
if (HeroTable.Instance.FindByKey(1001, out Hero hero))
    Debug.Log($"{hero.Name} 攻击力 {hero.Attack} 是否远程 {hero.IsRanged}");

// ③ 用完卸载（归还资源引用）
RevDataTableManager.Unload<HeroTable>();

字符串主键 / 字符串表名同样支持：

BuffTable.Instance.FindByKey("BUFF_ATK_UP", out Buff buff);   // 字符串主键
RevDataTableManager.Get("Buff");                                  // 按表名取表
RevDataTableManager.TryGet<BuffTable>("Buff", out BuffTable tbl);  // 按表名取具体容器

8.3 走 AB 模式：数据表直接就能进包

数据文件是 .txt，而打包工具的排除后缀 excludeExtensions 默认只剩 .cs / .meta —— 所以数据表会正常进 ResMap，不需要任何额外设置。

⚠️ 但反过来要注意：如果你手动把 .txt 加进排除列表，数据表就会被静默踢出包：

不会进 ResMap → RevABResPolicy 查不到 → PathNotMapped

详见《资源加载系统架构解析》第四章「打包注意事项」。

9报错对照表

导出的报错都带行号（和 Excel 左上角行号一致），直接指给策划看：

10局限与边界（用之前先知道）

1. 只支持 .xlsx（Excel 2007+）。老的 .xls 是 OLE 复合文档，不是 zip，读不了 —— 用 Excel 另存为 xlsx 即可。
2. 不处理图表、批注、条件格式、合并单元格；公式取其缓存值（Excel 保存时会写入计算结果，够导表用）。
3. 只支持 4 种类型（int / float / string / bool），不支持数组、嵌套结构、枚举。
4. 只支持单主键，且必须是第一个字段。
5. 每次导出会整体重写两个代码文件（表很多时会变大，并触发 Unity 重编译）。
6. 没有 schema 版本号：靠"导表同时覆盖代码与数据"保证一致，别只拷其中一个。
7. 坏表会被跳过（而非中止），所以导出后一定看一眼日志有没有 [提示]，别以为"没报红色就全导了"。

11附：文件索引