游戏客户端架构 / 系统课时
导入时怎样做字段类型转换
导入时怎样做字段类型转换
配置表进入运行时之前,最容易出错的并不是“读到一行”,而是把文本单元格可靠地转换成程序真正需要的类型。本节用一个完整导入器处理数字、枚举、布尔、列表和嵌套对象,并明确转换失败时应该在哪里拦截。
学习目标
- 为常见配置字段建立显式、可复用的类型转换函数。
- 区分“格式转换成功”和“业务值合法”两个阶段。
- 让导入错误携带字段名和原始值,便于定位问题。
先把文本层和类型层分开
CSV、Excel 导出文件或表格服务返回的数据,很多时候最终都会以字符串形式进入导入程序。即使单元格看起来是 1001、true 或 rare,运行时也不能直接假设它已经是数字、布尔值或枚举。
更稳妥的链路是:先读取原始文本,再做空白归一化,然后按字段声明选择转换器,最后才得到强类型配置对象。转换阶段只回答“能不能转换成目标类型”,范围、唯一性、引用关系等业务规则留到校验阶段处理。

用显式转换器处理常见字段
下面示例把一行文本配置转换为 ItemConfig。关键点是不要依赖 JavaScript 的隐式真值规则,也不要用 Number('') 这类会把空字符串意外变成 0 的行为。
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));预期输出:
{
"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。
生产链路通常还会在字段转换外层补充行级上下文,并收集整批错误后一次性返回。这样策划或运营可以一次修完多处问题,而不是每修一处就重新导入一次。
只要把“原始文本 → 类型转换 → 业务校验”拆成清晰阶段,数字、枚举、布尔、列表和嵌套结构就不会混在一段不可维护的导入逻辑里,后续新增字段类型时也只需增加对应转换器。