适用场景与故障现象

一个内部批处理工具接收小型 UTF-8 键值配置,每行格式为 KEY=VALUE。最初只有 MODE=batch,上线后增加带填充符的编码文本、查询表达式或 URL 参数,解析器突然报 ValueError: too many values to unpack。有人改成取拆分结果的第二项,程序不报错了,值却被截断。

本文约定的是自定义简单格式,不是 dotenv、INI 或 shell 语法:键为 1—64 位大写 ASCII 标识,值从第一个等号后开始原样保存;空值允许,键周围的空格允许;空白行与首个非空白字符为 # 的整行注释忽略。值中的 #、引号、反斜杠都只是普通字符,不做插值和转义。示例适用于 Python 3.10+ 标准库。

先复现两种错误

line = "FILTER=status=ready"
try:
    key, value = line.split("=")
except ValueError:
    print("无限制拆分导致解包失败")
assert line.split("=")[1] == "status"
assert line.partition("=") == ("FILTER", "=", "status=ready")

第二个断言证明取下标虽然绕过异常,却丢失 =ready。不要用生产配置原文排障;日志只记录配置来源、行号、失败原因和解析器版本,不输出值,尤其不能把连接串或令牌拼进异常。

原因与排查顺序

split("=") 会处理所有等号;partition("=") 只处理第一次出现的位置,并固定返回键前段、分隔符、值后段。分隔符不存在时中间项为空,可以明确区分 EMPTY= 与 BROKEN。这与 Python 字符串官方文档 的接口约定一致。

排查时先在脱敏测试配置中加入 FILTER=status=ready,确认异常是否由拆分触发;再检查是否存在 split("=")[1] 这种静默截断,以及对整行执行 strip() 导致尾部空格丢失的处理。最后检查重复键:直接赋值给字典会把前面的配置覆盖,容易掩盖发布文件合并错误。

split("=", 1) 也能限制拆分,但必须另外处理无分隔符情况。本例选择 partition,让缺少分隔符成为明确的业务校验。

完整修复与回归测试

保存下列代码为 test_config_pairs.py,执行 python -m unittest -v test_config_pairs。代码不读取环境变量、不访问网络,也不执行配置内容。

import re
import unittest


KEY_PATTERN = re.compile(r"[A-Z][A-Z0-9_]{0,63}")
MAX_TEXT_LENGTH = 65536
MAX_LINE_COUNT = 1000
MAX_VALUE_LENGTH = 4096


def parse_config(text: object) -> dict[str, str]:
    """按简单键值合同解析整份文本,全部通过后才返回配置。"""
    if not isinstance(text, str):
        raise ValueError("配置必须为文本")
    if len(text) > MAX_TEXT_LENGTH:
        raise ValueError("配置文本超过长度上限")
    # 只认可 LF 和 CRLF,避免把其他 Unicode 分隔符当作新配置行。
    lines = text.split("\n")
    if len(lines) > MAX_LINE_COUNT:
        raise ValueError("配置行数超过上限")
    result: dict[str, str] = {}
    for line_number, raw_line in enumerate(lines, start=1):
        line = raw_line.removesuffix("\r")
        if "\r" in line or "\x00" in line:
            raise ValueError(f"第 {line_number} 行包含非法控制字符")
        if not line.strip() or line.lstrip().startswith("#"):
            continue
        key, separator, value = line.partition("=")
        key = key.strip()
        if not separator:
            raise ValueError(f"第 {line_number} 行缺少等号")
        if KEY_PATTERN.fullmatch(key) is None:
            raise ValueError(f"第 {line_number} 行键名无效")
        if len(value) > MAX_VALUE_LENGTH:
            raise ValueError(f"第 {line_number} 行值超过长度上限")
        if key in result:
            raise ValueError(f"第 {line_number} 行键名重复")
        result[key] = value
    return result


class ParseConfigTests(unittest.TestCase):
    """验证分隔符、值保真与格式拒绝边界。"""

    def test_preserves_equals(self) -> None:
        self.assertEqual(
            parse_config("FILTER=status=ready\nPAYLOAD=YWJjZA=="),
            {"FILTER": "status=ready", "PAYLOAD": "YWJjZA=="},
        )

    def test_empty_and_missing_separator(self) -> None:
        self.assertEqual(parse_config("EMPTY="), {"EMPTY": ""})
        with self.assertRaisesRegex(ValueError, "缺少等号"):
            parse_config("BROKEN")

    def test_preserves_value_spaces_and_hash(self) -> None:
        self.assertEqual(
            parse_config(' LABEL =  示例 #说明  '),
            {"LABEL": "  示例 #说明  "},
        )

    def test_comments_and_crlf(self) -> None:
        self.assertEqual(parse_config(" # 注释\r\n\r\nMODE=batch\r\n"),
                         {"MODE": "batch"})
        self.assertEqual(parse_config(""), {})

    def test_duplicate_is_rejected(self) -> None:
        with self.assertRaisesRegex(ValueError, "第 2 行键名重复"):
            parse_config("MODE=batch\n MODE =stream")

    def test_invalid_inputs(self) -> None:
        for text in (None, 1, b"MODE=batch", "=x", "lower=x", "9KEY=x",
                     "A-B=x", "键=x", "A" * 65 + "=x", "A=x\x00",
                     "A=x\ry"):
            with self.subTest(text_type=type(text).__name__):
                with self.assertRaises(ValueError):
                    parse_config(text)

    def test_size_boundaries(self) -> None:
        self.assertEqual(parse_config("A=" + "x" * 4096)["A"], "x" * 4096)
        for text in ("A=" + "x" * 4097, "#" * 65537, "\n" * 1000):
            with self.assertRaises(ValueError):
                parse_config(text)
        self.assertEqual(parse_config("\n" * 999), {})


if __name__ == "__main__":
    unittest.main()

长度上限按 Python 字符数计算,不能替代读取入口的字节上限。接入文件时应在解码前限制字节数、使用明确的 UTF-8 严格解码,并将解码失败与格式失败分别报告。行数按 LF 拆分结果计算,末尾换行会产生一个空行;这是本例明确采用的计数合同。

这里不对值做 strip(),因为前后空格可能是内容。也不执行 shell 展开,VALUE=$HOME 会得到字面值 $HOME。需要引号、续行、变量引用时,应改用具有明确规范的格式与对应解析器,不应继续堆叠字符串替换。

发布时如何替换旧解析器

先用固定样本比较旧、新解析结果;真实配置仅比较键集合、值是否相等与长度,不打印差异原文。修复拆分后仍需按业务校验键白名单、必填项和各字段类型。例如重试次数必须转换为有上下限的整数,目标地址还需要独立的协议与权限校验。

解析整份配置并完成业务校验后,才把结果交给运行中的任务。不要在循环中一边解析一边写全局配置,否则后面一行失败时,前面的变更已经生效。本文返回局部字典,但不实现线程间配置发布;热更新同步与回滚需要由调用方完成。

上线前故意把 partition 改回无限制 split,包含多个等号的回归测试应报错。若改回 split("=")[1],测试应因值不一致而失败。再去掉重复键拒绝,重复键测试也应失败。这些检查确保测试覆盖真正的缺陷,而不只是“函数能返回字典”。

验证范围与维护要点

正文七项 unittest 验证多等号、空值、空格保真、注释、CRLF、重复键、非法输入和大小限制。它们不证明真实配置源、文件权限、业务字段约束或多线程热更新正确。接入时还需验证读取与发布边界。

这一故障的修复点是明确分隔规则:只把第一个等号当分界,保留后续内容,并把缺失分隔符、非法键和重复键变成有行号的校验错误。值是否可用,则继续由字段级业务合同判断。