游戏客户端架构 / 系统课时

导入时怎样做字段类型转换

导入时怎样做字段类型转换

配置表进入运行时之前,最容易出错的并不是“读到一行”,而是把文本单元格可靠地转换成程序真正需要的类型。本节用一个完整导入器处理数字、枚举、布尔、列表和嵌套对象,并明确转换失败时应该在哪里拦截。

学习目标

  • 为常见配置字段建立显式、可复用的类型转换函数。
  • 区分“格式转换成功”和“业务值合法”两个阶段。
  • 让导入错误携带字段名和原始值,便于定位问题。

先把文本层和类型层分开

CSV、Excel 导出文件或表格服务返回的数据,很多时候最终都会以字符串形式进入导入程序。即使单元格看起来是 1001、true 或 rare,运行时也不能直接假设它已经是数字、布尔值或枚举。

更稳妥的链路是:先读取原始文本,再做空白归一化,然后按字段声明选择转换器,最后才得到强类型配置对象。转换阶段只回答“能不能转换成目标类型”,范围、唯一性、引用关系等业务规则留到校验阶段处理。

字段文本经过不同解析器转换为强类型配置对象

用显式转换器处理常见字段

下面示例把一行文本配置转换为 ItemConfig。关键点是不要依赖 JavaScript 的隐式真值规则,也不要用 Number('') 这类会把空字符串意外变成 0 的行为。

ts
type Rarity = "common" | "rare" | "epic";

interface Effect {
  type: string;
  value: number;
}

interface ItemConfig {
  id: number;
  enabled: boolean;
  rarity: Rarity;
  tags: string[];
  effect: Effect;
}

function parseNumber(field: string, raw: string): number {
  const text = raw.trim();
  if (text === "") throw new Error(`${field}: value is empty`);

  const value = Number(text);
  if (!Number.isFinite(value)) {
    throw new Error(`${field}: "${raw}" is not a finite number`);
  }
  return value;
}

function parseBoolean(field: string, raw: string): boolean {
  const value = raw.trim().toLowerCase();
  if (value === "true" || value === "1") return true;
  if (value === "false" || value === "0") return false;
  throw new Error(`${field}: "${raw}" is not a boolean`);
}

function parseRarity(field: string, raw: string): Rarity {
  const value = raw.trim();
  const allowed = new Set<Rarity>(["common", "rare", "epic"]);
  if (!allowed.has(value as Rarity)) {
    throw new Error(`${field}: unsupported value "${raw}"`);
  }
  return value as Rarity;
}

function parseList(raw: string): string[] {
  const text = raw.trim();
  return text === ""
    ? []
    : text.split("|").map(v => v.trim()).filter(v => v.length > 0);
}

function parseEffect(field: string, raw: string): Effect {
  let value: unknown;
  try {
    value = JSON.parse(raw);
  } catch {
    throw new Error(`${field}: invalid JSON`);
  }

  if (
    typeof value !== "object" ||
    value === null ||
    typeof (value as { type?: unknown }).type !== "string" ||
    typeof (value as { value?: unknown }).value !== "number"
  ) {
    throw new Error(`${field}: object shape is invalid`);
  }
  return value as Effect;
}

const row = {
  id: "1001",
  enabled: "true",
  rarity: "rare",
  tags: "weapon|melee",
  effect: '{"type":"attack","value":12.5}'
};

const item: ItemConfig = {
  id: parseNumber("id", row.id),
  enabled: parseBoolean("enabled", row.enabled),
  rarity: parseRarity("rarity", row.rarity),
  tags: parseList(row.tags),
  effect: parseEffect("effect", row.effect)
};

console.log(JSON.stringify(item, null, 2));

预期输出:

json
{
  "id": 1001,
  "enabled": true,
  "rarity": "rare",
  "tags": [
    "weapon",
    "melee"
  ],
  "effect": {
    "type": "attack",
    "value": 12.5
  }
}

这个示例中,枚举值采用白名单,布尔值只接受约定好的字面量,嵌套结构使用 JSON 解析后继续检查对象形状。这样可以避免 "yes"、"TRUE " 或结构错误的对象悄悄进入运行时。

列表和嵌套结构要先约定编码方式

列表字段可以使用 | 这类分隔符,但前提是元素本身不会包含该字符。如果道具标签、路径或文案可能出现分隔符,优先把该字段改成 JSON 数组,而不是继续叠加转义规则。

嵌套结构也不建议用 attack:12.5;duration:3 这类自定义文本协议。JSON、结构化表格或拆表通常更容易校验,也更容易在后续版本中增加字段。

转换失败要带上定位信息

批量导入时,错误信息至少应包含行号、字段名和原始值。例如第 27 行的 enabled=truth 转换失败,日志应能直接指出该单元格,而不是只抛出 invalid boolean。

生产链路通常还会在字段转换外层补充行级上下文,并收集整批错误后一次性返回。这样策划或运营可以一次修完多处问题,而不是每修一处就重新导入一次。

只要把“原始文本 → 类型转换 → 业务校验”拆成清晰阶段,数字、枚举、布尔、列表和嵌套结构就不会混在一段不可维护的导入逻辑里,后续新增字段类型时也只需增加对应转换器。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

导入时怎样做字段类型转换

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通