[技术方案] 跨格式数据迁移：Excel抽卡记录的JSON标准化实践

[技术方案] 跨格式数据迁移：Excel抽卡记录的JSON标准化实践

【免费下载链接】HoYo.Gacha✨ An unofficial tool for managing and analyzing your miHoYo gacha records. (Genshin Impact | Honkai: Star Rail) 一个非官方的工具，用于管理和分析你的 miHoYo 抽卡记录。（原神 | 崩坏：星穹铁道）项目地址: https://gitcode.com/gh_mirrors/ho/HoYo.Gacha

副标题：三步实现游戏数据互通：从表格到标准JSON的全流程

数据格式转换是实现跨平台数据互通的关键环节，而标准化流程则是确保数据质量和兼容性的核心保障。本文将从数据转换工程师视角，系统阐述如何将Excel格式的抽卡记录转换为符合UIGF标准的JSON格式，为游戏数据的高效管理与分析提供技术方案。

一、问题诊断：抽卡数据格式的兼容性挑战

1.1 数据异构性问题

Excel格式的抽卡记录通常以自由表格形式存储，字段定义缺乏规范，常见问题包括：

• 时间格式不统一（如"2023/10/01"与"10-01-2023"混用）
• 字段命名混乱（"星级"与"稀有度"等同义不同名现象）
• 数据类型不一致（数字与文本型数值并存）

1.2 目标格式分析

UIGF（Uniformed Interchangeable GachaLog Format，统一可交换抽卡记录格式）作为行业标准，定义了严格的数据结构。根据项目本地化文件显示，当前支持UIGF v4.0/v4.1及 legacy v2.0-v3.0版本，其核心要求包括：

• 必选字段完整性（如gacha_type、time、item_id等）
• 数据类型标准化（时间戳需为ISO 8601格式）
• 嵌套结构规范性（如info和list的层级关系）

二、方案设计：分层转换架构

2.1 架构设计

采用"解析-转换-验证"三层架构：

1. 解析层：将Excel表格数据提取为结构化对象
2. 转换层：实现中间格式（GWE）与UIGF标准的映射
3. 验证层：通过JSON Schema确保输出格式合规

2.2 数据校验矩阵

三、分步实施：从Excel到UIGF的转换流程

3.1 数据提取与规范化

操作步骤：

1. 使用pandas读取Excel文件，指定表头行索引
2. 执行数据清洗：
   • 移除空行与重复记录
   • 标准化日期格式为ISO 8601
   • 统一字段命名（如将"抽卡时间"重命名为"time"）

预期结果：生成包含标准化字段的DataFrame对象

验证方法：

# 示例代码片段 import pandas as pd df = pd.read_excel("gacha_records.xlsx", header=0) assert "time" in df.columns, "缺少必要字段: time" assert pd.api.types.is_datetime64_any_dtype(df["time"]), "时间字段格式错误"

3.2 中间格式转换（Excel→GWE）

操作步骤：

1. 定义GWE格式映射规则
2. 实现字段转换逻辑：
   • 将文本类型映射为枚举值
   • 计算衍生字段（如uid、lang）
   • 构建嵌套结构

预期结果：生成符合GWE规范的JSON对象

验证方法：通过JSON Schema验证工具检查结构完整性

3.3 标准格式转换（GWE→UIGF）

操作步骤：

1. 加载GWE格式数据
2. 执行版本适配转换：
   • 按项目i18n配置支持UIGF v2.2及以上版本
   • 实现gacha_type字段的编码映射
   • 添加必要元数据（如uigf_version）

预期结果：生成符合UIGF v4.0标准的JSON文件

验证方法：

// UIGF格式验证示例 function validateUIGF(jsonData) { const requiredFields = ['info', 'list', 'uigf_version']; return requiredFields.every(field => field in jsonData); }

四、数据质量控制：异常处理与优化

4.1 异常值处理策略

1. 时间格式异常：
   • 使用dateutil库进行模糊解析
   • 无法解析的记录标记为"待审核"
2. 缺失值处理：
   • 关键字段缺失：拒绝转换并提示
   • 非关键字段缺失：填充默认值或标记为null
3. 类型转换错误：
   • 数值型字段转换失败时记录错误日志
   • 提供手动修正界面

4.2 数据质量指标

五、风险规避：常见错误排查

5.1 转换失败排查树状图

转换失败 ├─ 源数据错误 │ ├─ Excel格式损坏 → 尝试修复或使用备份文件 │ ├─ 表头缺失 → 手动指定表头行 │ └─ 数据量过大 → 分批次处理 ├─ 格式映射错误 │ ├─ GachaType映射失败 → 检查映射表版本 │ └─ 版本不兼容 → 升级转换工具至最新版 └─ 验证错误 ├─ JSON Schema验证失败 → 检查必填字段 └─ 数据类型错误 → 执行类型强制转换

5.2 版本兼容性处理

根据项目本地化配置，当前支持的UIGF版本包括：

• 现代版：v4.0, v4.1
• legacy版：v2.0-v3.0 转换时需根据输入文件自动识别版本，并应用对应转换规则。

六、技术原理：标准化转换的实现机制

6.1 JSON Schema验证示例

UIGF v4.0核心Schema片段：

{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "required": ["info", "list", "uigf_version"], "properties": { "uigf_version": { "type": "string", "pattern": "^4\\.[0-1]$" }, "info": { "type": "object", "required": ["uid", "lang"] }, "list": { "type": "array", "items": { "type": "object", "required": ["gacha_type", "time", "item_id"] } } } }

6.2 转换引擎工作流程

1. 解析阶段：使用表格解析库提取原始数据
2. 转换阶段：应用预定义映射规则进行字段转换
3. 验证阶段：通过Schema验证和业务规则校验
4. 输出阶段：生成格式化JSON文件并附加校验报告

总结

本文提出的Excel抽卡记录转JSON技术方案，通过"问题诊断→方案设计→分步实施→风险规避"四阶段框架，实现了从非结构化表格到标准化格式的可靠转换。该方案已在HoYo.Gacha项目中得到应用，支持UIGF多版本兼容，为游戏数据的跨平台互通提供了技术保障。通过严格的数据质量控制和异常处理机制，确保了转换过程的稳定性和结果的可靠性。

项目源码可通过以下地址获取：https://gitcode.com/gh_mirrors/ho/HoYo.Gacha

【免费下载链接】HoYo.Gacha✨ An unofficial tool for managing and analyzing your miHoYo gacha records. (Genshin Impact | Honkai: Star Rail) 一个非官方的工具，用于管理和分析你的 miHoYo 抽卡记录。（原神 | 崩坏：星穹铁道）项目地址: https://gitcode.com/gh_mirrors/ho/HoYo.Gacha