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

导入失败怎样给出可定位错误

导入失败怎样给出可定位错误

配置导入最怕“失败了,但不知道哪一格错了”。本节把错误设计成可定位的数据:至少包含表名、行号、字段和原因,并让校验器统一收集后输出,目标是让策划或程序看到错误后直接回到原始配置修正,而不是反复猜测。

学习目标

  • 设计一条包含表名、行号、字段和原因的错误信息
  • 区分解析错误、字段校验错误和跨行校验错误
  • 实现可批量收集且便于定位的导入校验结果

错误信息要回答四个问题

一条有效的导入错误,至少要回答“哪张表、哪一行、哪个字段、为什么错”。只写 invalid config、parse failed 或抛出原始异常,都把定位成本转嫁给使用者。

例如,道具表第 18 行的 stackLimit 填成 0,错误应尽量接近下面这种形式:

text
Item.xlsx row=18 field=stackLimit: must be greater than 0, actual=0

这类信息可以直接映射回源表。表名用于定位文件,行号用于定位记录,字段名用于定位列,原因用于说明修复方向。

还要注意“行号”通常应该指用户看到的原始表格行号,而不是程序解析后的数组下标。若首行为表头,程序内部第 0 条数据可能对应 Excel 第 2 行,错误对象中应保存原始来源位置。

把错误位置做成结构化数据

不要在每个校验点手工拼字符串。更稳妥的方式是让解析阶段先保留来源位置,再由统一错误类型负责格式化。

下面示例使用 Python 模拟 CSV 配置导入。它会检查 itemId 是否为空、stackLimit 是否为正整数,并一次收集全部错误。

python
from dataclasses import dataclass
import csv
from io import StringIO

@dataclass
class ConfigError:
    table: str
    row: int
    field: str
    reason: str

    def __str__(self) -> str:
        return f"{self.table} row={self.row} field={self.field}: {self.reason}"

def validate_items(csv_text: str, table_name: str) -> list[ConfigError]:
    errors: list[ConfigError] = []
    reader = csv.DictReader(StringIO(csv_text))

    for row_number, row in enumerate(reader, start=2):
        item_id = (row.get("itemId") or "").strip()
        stack_limit_raw = (row.get("stackLimit") or "").strip()

        if not item_id:
            errors.append(
                ConfigError(table_name, row_number, "itemId", "must not be empty")
            )

        try:
            stack_limit = int(stack_limit_raw)
            if stack_limit <= 0:
                errors.append(
                    ConfigError(
                        table_name,
                        row_number,
                        "stackLimit",
                        f"must be greater than 0, actual={stack_limit}",
                    )
                )
        except ValueError:
            errors.append(
                ConfigError(
                    table_name,
                    row_number,
                    "stackLimit",
                    f"must be an integer, actual={stack_limit_raw!r}",
                )
            )

    return errors

source = '''itemId,name,stackLimit
potion_small,Small Potion,20
,Large Potion,10
bomb,Bomb,0
arrow,Arrow,abc
'''

for error in validate_items(source, "Item.csv"):
    print(error)

预期输出:

text
Item.csv row=3 field=itemId: must not be empty
Item.csv row=4 field=stackLimit: must be greater than 0, actual=0
Item.csv row=5 field=stackLimit: must be an integer, actual='abc'

这里没有“遇到第一处错误就退出”,因为配置导入通常属于离线工具链。一次把同一张表中的问题尽量收集全,修改者就能一轮修完,减少“修一处、再导入、再遇到下一处”的往返。

配置导入错误从源表定位到具体字段的流程

分清错误发生在哪一层

导入链路里常见的错误至少有三层,位置字段的含义并不完全相同。

解析错误发生在字符串转类型时,例如 stackLimit=abc 无法转成整数。此时可以明确给出表、行、字段和原始值。

字段校验错误发生在值已经成功解析后,例如 stackLimit=0 虽然是整数,却违反“必须大于 0”的业务规则。

跨行或跨表错误需要额外上下文,例如重复 itemId、掉落表引用了不存在的道具。此时仍应尽量保留当前记录的位置,并在原因中指出冲突对象。

例如重复键可以写成:

text
Item.csv row=27 field=itemId: duplicate value 'bomb', first defined at row=12

这种表达同时给出“当前错误位置”和“关联位置”,比只说 duplicate id 更容易修。

错误输出既要给人看,也要方便工具处理

如果导入器只在终端打印字符串,短期足够,但后续接入 CI、编辑器或后台时会很难复用。更稳妥的做法是内部保留结构化错误对象,最后再按不同场景转换为文本、JSON 或界面提示。

字段通常可以保持精简:

字段 作用
table 原始配置文件或逻辑表名
row 用户可见的源数据行号
field 出错字段;跨表错误也应尽量给出当前字段
reason 可直接指导修改的原因

reason 不要塞堆栈信息,也不要只复述异常类型。像 ValueError、NullReference 这类程序内部信息适合日志,不适合直接给配置使用者。对外错误应该说明“数据为什么不合法”,内部日志再保留异常和调用栈。

最终判断标准很简单:拿到一条错误后,使用者不需要重新跑调试器,也不需要搜索整张表,就能直接定位到原始数据并知道应该改什么。

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

目录与阅读设置

阅读设置

17

记录一个想法

导入失败怎样给出可定位错误

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

登录哪都通