thrift-related/PythonWorkSpace/IntegratedTool

Thrift 完整流程工具使用说明

功能概述

这是一个集成所有步骤的完整工具，从 Excel 配置到 Unity 部署一键完成。

执行流程

步骤1：生成 Thrift 文件

• 根据 cfg_txt.json 配置读取 Excel 文件
• 自动解析 Excel 表头和类型
• 生成对应的 .thrift 文件

步骤2：编译到 C#

• 使用 thrift.exe 编译器
• 生成 Unity 可用的 C# 代码
• 参数：-strict -v -r --gen netstd:unity,serial,async_postfix

步骤3：生成 Bytes 文件

• 临时生成 gen-py Python 代码
• 使用 Thrift Binary Protocol 序列化
• 生成 .bytes 二进制文件

步骤4：清理 Extensions

• 删除多余的 .Extensions.cs 文件
• 只保留 AllConfigs.Extensions.cs

步骤5：复制 C# 到 Unity

• 复制所有 .cs 文件到 Unity C# 目录
• 覆盖原有文件

步骤6：复制 Bytes 到 Unity

• 复制所有 .bytes 文件到 Unity Bytes 目录
• 使用复制而非移动，方便检查

步骤7：清理临时文件

• 删除 gen-py 目录

配置说明

所有路径配置会保存在 pipeline_config.json，下次打开自动加载。

必需配置

1. cfg_txt.json - 配置文件，包含 Excel 和 Sheet 映射
2. Thrift 编译器 - thrift.exe 路径
3. Thrift 文件路径 - 生成的 .thrift 文件存放位置
4. C# 输出路径 - 编译生成的 C# 代码临时存放
5. Bytes 输出路径 - 生成的 .bytes 文件临时存放
6. Config 路径 - Excel 文件 (.xlsx) 所在目录
7. Unity C# 路径 - Unity 项目中的 C# 代码目标目录
8. Unity Bytes 路径 - Unity 项目中的 Bytes 文件目标目录

cfg_txt.json 格式

{
  "file_list": [
    {
      "in_file": "Music.xlsx",
      "out_file": "Music.txt",
      "sheet_name": "Music"
    }
  ]
}

执行报告

每次执行完成后会生成详细报告：

• 文件名：report_YYYYMMDD_HHMMSS.txt
• 包含每个步骤的状态、时间、详细数据
• 方便排查问题

使用方法

开发模式

python integrated_pipeline.py

打包为 EXE

打包集成工具.bat

打包后的 EXE 位于：../../IntegratedToolEXE/ThriftPipeline.exe

注意事项

1. 首次运行 - 需要正确配置所有路径
2. Excel 格式 - 第1行字段名，第2行类型，第3行开始数据
3. 类型映射 - int→i32, long→i64, float/double→double, string→string
4. AllConfigs - 因为包含其他配置的引用，只保留其 Extensions 文件
5. gen-py 清理 - 每次运行都会重新生成，完成后自动清理
6. 文件覆盖 - Unity 目录中的文件会被新文件覆盖

故障排查

问题：找不到 thrift 模块

• 确保安装了 thrift Python 包：pip install thrift

问题：编译失败

• 检查 thrift.exe 路径是否正确
• 查看日志中的错误信息

问题：Bytes 生成失败

• 检查 Excel 文件格式是否正确
• 确保字段名与 Thrift 定义匹配

问题：报告中显示某步骤失败

• 查看详细日志找到具体错误
• 根据错误信息修复对应问题

技术细节

Binary Protocol 序列化

• 使用 Thrift 的 TBinaryProtocol
• 紧凑的二进制格式，比 JSON 小很多
• Unity 使用相同协议反序列化

为什么需要 gen-py

• Thrift 序列化需要对应语言的类定义
• Python 需要 gen-py，C# 需要 .cs 文件
• 这是 Thrift 框架的设计，无法绕过

文件命名规则

• Thrift 文件：{StructName}.thrift
• C# 文件：{StructName}.cs 和 {StructName}.Extensions.cs
• Bytes 文件：{StructName}.bytes

版本历史

• v1.0 - 初始版本，集成完整流程