游戏客户端架构 / 系统课时
CSV、JSON 和表格该怎么分工
CSV、JSON 和表格该怎么分工
CSV、JSON 和在线表格并不是互相替代的三种格式。真正稳定的做法是让它们承担不同阶段的职责:表格负责多人编辑,CSV 适合扁平批量数据交换,JSON 负责表达有层级的结构。分工清楚后,导入链路会更简单,也更容易校验。
学习目标
- 判断 CSV、JSON 和表格各自适合承载什么数据
- 设计从编辑态到导入态、运行态的格式转换关系
- 避免把复杂结构硬塞进 CSV 或让运行时直接依赖在线表格
三种载体解决的问题不同
表格最擅长人工编辑。排序、筛选、批量填充、多人协作和备注都很方便,因此适合作为策划维护数据的“编辑态”。但在线表格通常不适合让客户端或服务器直接读取,因为权限、网络、版本和格式变化都难以控制。
CSV 是扁平表数据的天然载体。一行一条记录、列结构稳定时,它体积小、差异清晰,也容易被各类语言解析。它不擅长嵌套对象和可变长度数组。
JSON 更适合树状结构、嵌套对象和数组,例如关卡波次、技能阶段或任务条件。代价是人工批量编辑体验较差,大量同构记录放进 JSON 后也不如表格直观。
| 载体 | 最适合的角色 | 优点 | 主要限制 |
|---|---|---|---|
| 表格 | 编辑态 | 易协作、易批量修改 | 不宜直接作为运行时依赖 |
| CSV | 扁平交换格式 | 简单、紧凑、差异清晰 | 难表达嵌套结构 |
| JSON | 结构化运行数据 | 层级和数组表达自然 | 大批量人工编辑不方便 |
扁平实体优先用 CSV
例如道具主表只有固定字段,一行就能完整描述一件道具:
itemId,name,quality,stackLimit
1001,Small Potion,COMMON,99
1002,Iron Sword,RARE,1这是配置数据示例,不是独立可执行程序。导入时应校验每行列数一致、itemId 唯一、quality 属于合法枚举,并把文本字段转换为程序需要的类型。若一条记录可以自然映射成固定列,CSV 往往比 JSON 更容易维护。
层级结构交给 JSON
当一条配置内部包含可变长度子项时,继续给 CSV 增加 phase1、phase2、phase3 之类的列,会让结构迅速僵化。此时 JSON 更合适。
{
"skillId": 2001,
"name": "Flame Burst",
"phases": [
{
"delay": 0,
"damage": 40
},
{
"delay": 0.6,
"damage": 80
}
]
}这段结构可以直接表达“一个技能拥有多个阶段”。验证时应确认 skillId 唯一、phases 至少包含一个元素,并对每个阶段的 delay 和 damage 做范围检查。若后续阶段数量增加,不需要修改字段结构。
表格最好停留在编辑层
常见稳定链路是:策划在表格中编辑,导出或同步为 CSV,再由构建工具校验并转换成游戏运行时需要的数据;对于天然嵌套的数据,可以在工具链中生成 JSON 或其他二进制格式。关键点是运行时读取“已经校验过的产物”,而不是直接读取人工编辑源。

选择格式时看结构,不看习惯
如果团队总是争论“统一用 CSV 还是统一用 JSON”,通常说明判断维度错了。应该先看数据形态和使用阶段:高频人工维护的数据优先表格;固定列、批量记录优先 CSV;对象嵌套、数组长度可变时优先 JSON。
真正需要统一的不是文件扩展名,而是导入协议:字段命名、类型、必填规则、主键约束、版本管理和错误报告都应一致。这样无论编辑源最终产出 CSV 还是 JSON,都能进入同一套校验和构建流程。