企业官网建设流程全解析

• 后端
• 序列化

导读

本文围绕 marshmallow 内部模块error_store，剖析其ErrorStore错误收集器与merge_errors深度合并函数的完整实现。读者将掌握：字段级错误如何被逐条写入统一错误字典、列表/字典/标量各类错误消息如何被深度合并、_schema这个保留键在其中扮演什么角色，以及这套私有机制如何支撑Schema.load()在收集全部错误后统一抛出ValidationError的完整链路。该模块定位为私有 API，日常使用 marshmallow 的开发者无需直接调用它，但理解它有助于读懂 marshmallow 的错误格式与自定义错误处理。

一、error_store 模块的定位与整体结构

在仓库中，该模块的 API 文档入口为 docs/marshmallow.error_store.rst，文档通过automodule指令自动生成，覆盖全部成员与私有成员。真正实现位于 src/marshmallow/error_store.py，包含两大部分：

• ErrorStore类：用于在反序列化/验证过程中存储错误消息集合；
• copy_containers与merge_errors两个模块级工具函数：负责错误容器的拷贝与深度合并。

模块 docstring 明确给出了重要警告——该模块被视为私有 API（private API），普通用户不应直接使用。所有对外暴露的入口（如Schema.load、Schema.validate）都通过ValidationError暴露错误，而不是直接暴露ErrorStore。这一点在 src/marshmallow/schema.py 的导入语句from marshmallow.error_store import ErrorStore中可以得到印证：ErrorStore只在 schema 内部被实例化使用。

二、ErrorStore：一次反序列化流程中的错误收集器

2.1 初始化与 errors 字典

ErrorStore的构造非常简单，只维护一个属性：

def __init__(self): self.errors = {}

errors是一个字典，用于存储序列化/反序列化过程中积累的所有错误。它的键值结构正是ValidationError中messages参数的标准格式（见 src/marshmallow/error_store.py）。

2.2 store_error：把单条错误写入集合

store_error是收集错误的核心方法，签名如下：

def store_error(self, messages, field_name=SCHEMA, index=None):

三个参数的含义：

其内部处理逻辑分为三条分支（注释中原文清晰描述了这一规则）：

• 字段错误（field error）：当field_name != SCHEMA时，将错误消息包一层{field_name: messages}存入；
• Schema 级字符串/列表错误：当field_name == SCHEMA且messages不是字典时，同样包装为{SCHEMA: messages}，最终会归到_schema键下；
• Schema 级字典错误：当field_name == SCHEMA且messages本身是字典时，说明错误已经携带了多个顶层键（可能是嵌套子 schema 抛出的结构化错误），此时直接与其他顶层键进行合并，不再额外包装。

此外，如果传入index，则会在外层再包一层{index: messages}，从而把错误挂到对应的列表下标上，例如{"items": {0: ["error"], 1: ["error"]}}。核心实现为：

messages = copy_containers(messages) if field_name != SCHEMA or not isinstance(messages, dict): messages = {field_name: messages} if index is not None: messages = {index: messages} self.errors = merge_errors(self.errors, messages)

2.3 store_error 的调用方

schema.py中多处调用store_error，共同构成错误收集链路：

1. 反序列化主流程_deserialize：当传入数据不是序列时调用error_store.store_error([self.error_messages["type"]], index=index)（src/marshmallow/schema.py）；当数据不是Mapping时同样记录类型错误（src/marshmallow/schema.py）；当unknown=RAISE时对每个未知字段记录"unknown"错误（src/marshmallow/schema.py）。
2. _call_and_store：捕获字段反序列化抛出的ValidationError，调用error_store.store_error(error.messages, field_name, index=index)（src/marshmallow/schema.py）。
3. _run_validator：schema 级验证器抛出的ValidationError也会被存入 store，其中field_name会经过data_key映射（src/marshmallow/schema.py）。
4. _invoke_field_validators与_invoke_schema_validators同样以error_store为参数，把字段验证器与 schema 验证器的错误统一写入同一实例（src/marshmallow/schema.py、src/marshmallow/schema.py）。

由此可以看出，一次load()过程中所有阶段的错误——包括类型错误、字段反序列化错误、字段验证器错误、schema 验证器错误、未知字段错误——都被汇聚到同一个ErrorStore.errors中。

三、merge_errors：深度合并的完整规则

merge_errors(errors1, errors2)将两份错误消息深度合并，返回合并结果。其合并语义严格按errors1（已在集合中的旧错误）与errors2（新错误）的类型组合分派，覆盖全部 9 种标量/列表/字典组合。完整规则如下：

空值规则

• errors1为空（falsy）→ 直接返回errors2；
• errors2为空 → 直接返回errors1。

errors1 是列表时

• errors2是列表 → 追加元素并返回（errors1.extend(errors2)）；
• errors2是字典 → 把errors1挂到errors2["_schema"]下（调用merge_errors(errors1, errors2.get(SCHEMA))），再返回errors2；
• 其他（标量）→ 追加到列表末尾。

errors1 是字典时

• errors2是字典 → 按键递归合并：键冲突时对该键的旧值和新值递归调用merge_errors，否则直接赋值；
• errors2不是字典（列表/标量）→ 将新错误归入_schema键（errors1[SCHEMA] = merge_errors(errors1.get(SCHEMA), errors2)）。

errors1 是标量时

• errors2是列表 → 返回[errors1, *errors2]（errors1成为新列表首元素）；
• errors2是字典 → 将errors1挂到_schema键下；
• 两者都是标量 → 返回[errors1, errors2]。

完整源码见 src/marshmallow/error_store.py。

3.1 关键设计点：标量升级为列表、字典冲突按键递归合并

从规则中可以提炼出两个核心设计意图：

第一，同键下多条标量错误会"升级"为列表。例如merge_errors("error1", "error2")得到["error1", "error2"]；即使错误消息本身是任意标量对象（测试中用 NamedTuple 自定义错误CustomError(123, "error1")验证），规则同样成立。这意味着最终错误字典中某个键对应的值既可能是字符串，也可能是字符串列表。

第二，字典合并是按键递归的深度合并。当新旧错误都是字典时，merge_errors对每个键递归合并，因此嵌套结构（如{"field1": {"field2": ...}}）会按同构结构逐层合并，而不是整体覆盖：

merge_errors( {"field1": "error1", "field2": "error2"}, {"field2": "error3", "field3": "error4"}, ) # 结果: {"field1": "error1", "field2": ["error2", "error3"], "field3": "error4"}

该深度合并行为在测试 tests/test_error_store.py 的test_deep_merging_dicts用例中有直接验证：{"field1": {"field2": "error1"}}与{"field1": {"field2": "error2"}}合并得到{"field1": {"field2": ["error1", "error2"]}}。

3.2 不修改调用方容器：copy_containers

store_error在合并前先调用copy_containers递归拷贝传入的列表/字典容器（src/marshmallow/error_store.py）。由于merge_errors会就地修改作为第一个参数的列表（extend）或字典（写入新键），如果不做拷贝，调用方持有的原始错误消息对象会被污染。测试中专门验证了这一行为：

message = ["foo"] store.store_error(message) store.store_error(message) assert message == ["foo"] # 原始列表未被修改 assert store.errors == {"_schema": ["foo", "foo"]} # store 内正确累积

对应用例为 tests/test_error_store.py 的test_list_not_changed与test_dict_not_changed（后者验证{"foo": ["bar"]}字典同样不被修改，且两次存储正确合并为{"foo": ["bar", "bar"]}）。

四、SCHEMA 常量与_schema保留键

merge_errors与store_error中反复出现的SCHEMA并非 error_store 内部自造，而是从 src/marshmallow/exceptions.py 导入的模块级常量：

# Key used for schema-level validation errors SCHEMA = "_schema"

它专门用于 schema 级验证错误。当某一方错误是标量/列表、而另一方是字典时，标量/列表一侧会被安放到_schema键下，从而保证错误字典结构始终一致。例如 tests/test_error_store.py 验证：

merge_errors("error1", {"field1": "error2"}) # == {"_schema": "error1", "field1": "error2"} merge_errors("error1", {"_schema": "error2", "field1": "error3"}) # == {"_schema": ["error1", "error2"], "field1": "error3"}

第二个示例展示了_schema键自身的合并：原本各持有标量的两侧，合并后升级为列表["error1", "error2"]。

五、ValidationError 与错误消息的对外形态

ErrorStore只是内部收集器，用户最终接触到的是ValidationError（定义于 src/marshmallow/exceptions.py）。其messages属性保存错误消息，格式正是merge_errors所操作的标准格式：字符串、字符串列表，或子项映射到错误消息的字典。

normalized_messages()方法（src/marshmallow/exceptions.py）用于统一错误形态：若错误本属于_schema且本身是字典则直接返回，否则包装为{field_name: messages}。在_do_load中，pre_load 处理函数或 post_load 处理函数抛出的ValidationError会通过errors = err.normalized_messages()被还原为标准字典（src/marshmallow/schema.py、src/marshmallow/schema.py），与ErrorStore收集到的error_store.errors处于同一形态。

ValidationError还附带data（原始输入数据）与valid_data（已成功反序列化的有效数据）两个属性，测试 tests/test_schema.py 验证了这一点：错误对象保留原始输入，valid_data只包含成功反序列化的字段（如datetime已被转换），被判定无效的字段不会出现在valid_data中。

六、完整错误收集链路：从 store 到异常抛出

将上述模块串联起来，一次Schema.load()的错误处理全流程如下（对应_do_load的实现，见 src/marshmallow/schema.py）：

1. 创建error_store = ErrorStore()；
2. 执行 pre_load 处理函数；若抛出ValidationError，直接用其normalized_messages()作为最终错误；
3. 否则调用_deserialize，反序列化过程中字段错误、类型错误、未知字段错误通过store_error不断累积进 store；
4. 运行字段级验证器_invoke_field_validators与 schema 级验证器_invoke_schema_validators，验证错误继续写入同一 store；
5. 取出errors = error_store.errors；
6. 若无错误，才允许运行 post_load 处理函数（其异常同样通过normalized_messages()捕获）；
7. 一旦存在错误，构造ValidationError(errors, data=data, valid_data=result)，调用handle_error(exc, data, many=many, partial=partial)后抛出。

可见，ErrorStore承担了"收集分散在各阶段、各字段的错误，并归一为单一结构"的职责，而merge_errors保证了多次写入同一键时不会互相覆盖，而是符合直觉地累加与嵌套合并。若需在项目中自定义错误处理行为，可以直接覆写Schema.handle_error方法（docs/extending/custom_error_handling.rst 给出了完整示例）：在handle_error中读取exc.messages（即最终合并完成的错误字典），决定是记录日志、改写消息结构，还是抛出自定义业务异常。此时errors的键名正是各字段名（含data_key映射后的名称）与保留键_schema。

七、小结：理解 error_store 的三个要点

• 不要直接使用该模块：error_store是私有 API，错误形态始终通过ValidationError.messages暴露；直接依赖其内部结构会与未来版本产生耦合。
• 合并规则即错误格式约定：merge_errors中"标量升级为列表、同键递归合并、_schema兜底"三条规则，定义了 marshmallow 错误字典的规范形态，也是阅读ValidationError.messages结构的钥匙。
• 错误收集是一次性完整的：ErrorStore生命周期覆盖一次load/validate调用，收集全部错误后统一抛出，因此异常中的messages始终是一份完整的错误清单，而非第一条错误。

如需进一步阅读，可对照源码 src/marshmallow/error_store.py、调用方 src/marshmallow/schema.py 以及边界用例 tests/test_error_store.py，自行验证各合并分支的输入输出。

• 后端
• 序列化