本教程详细介绍了在 marshmallow 中如何将模型实例的简单字符串id字段（例如 `parent_id`）序列化为嵌套的 json 对象格式 `{"id": "value"}`。通过结合使用 `fields.nested` 和一个带有 `@pre_dump` 钩子的辅助 schema，可以优雅且高效地实现这一常见的数据转换需求，确保输出数据结构符合预期。
引言
在构建 RESTful API 或进行数据交换时，我们经常需要将内部模型中的扁平化数据结构转换为更丰富、更具语义的外部表示。一个常见的场景是，模型实例可能包含一个简单的字符串形式的关联ID（例如 parent 字段存储着父对象的ID），但在序列化为 JSON 时，我们希望将其包装成一个嵌套的对象，如 {"id": "..."}，以提供更清晰的数据结构。
本教程的目标是演示如何在 Marshmallow 框架中实现这一转换，将模型实例中形如 parent = "123-345" 的字段，在序列化后变为 parent = {"id": "123-345"}。
使用 Marshmallow 实现嵌套ID字段
Marshmallow 提供了灵活的字段类型和钩子（hooks）机制来处理复杂的序列化和反序列化需求。对于将简单字符串ID包装为嵌套对象的问题，我们可以利用 fields.Nested 结合一个辅助 Schema，并巧妙地运用 @pre_dump 钩子来完成。
核心思路
其核心在于：
- 定义一个辅助 Schema (IdSchema)，它负责描述 {"id": "..."} 这种嵌套结构。
- 在辅助 Schema 中使用 @pre_dump 钩子，拦截传入的原始字符串ID，并将其包装成 {"id": "..."} 字典格式，以便辅助 Schema 能够正确处理。
- 在主 Schema (UserSchema) 中，使用 fields.Nested(IdSchema) 将需要转换的字段委托给辅助 Schema 进行序列化。
步骤详解
1. 定义辅助 Schema (IdSchema)
首先，我们创建一个名为 IdSchema 的辅助 Schema。这个 Schema 的主要作用是处理包含单个 id 字段的字典结构。
from marshmallow import Schema, fields, pre_dump
class IdSchema(Schema):
"""
辅助Schema，用于处理 {"id": "value"} 形式的数据。
"""
id = fields.String(required=True)
@pre_dump
def wrap_id_for_dump(self, data, **kwargs):
"""
在序列化之前执行，将原始字符串ID包装成 {"id": "..."} 字典。
当 fields.Nested 传递一个字符串（而非字典）给 IdSchema 时，
此钩子会将其转换为 IdSchema 期望的字典格式。
"""
if isinstance(data, str):
return {"id": data}
return data # 如果数据已经是字典，则直接返回- id = fields.String(required=True): 这定义了 IdSchema 预期会有一个名为 id 的字符串字段。
- @pre_dump 钩子: 这是实现转换的关键。当 UserSchema 尝试序列化 parent 字段时，如果 parent 的值是一个字符串（例如 "123-345"），fields.Nested(IdSchema) 会将这个字符串作为 data 传递给 IdSchema 的 dump 方法。@pre_dump 钩子会在 IdSchema 实际处理 data 之前被调用。在这里，我们检查 data 是否为字符串，如果是，就将其包装成 {"id": data} 的字典形式，然后返回。这样，后续的 IdSchema 就能像处理一个普通的字典一样，从中提取 id 字段进行序列化。
2. 定义主 Schema (UserSchema)
接下来，我们定义 UserSchema，它将使用 IdSchema 来处理 parent 字段。
class UserSchema(Schema):
"""
主Schema，用于序列化 User 模型实例。
"""
name = fields.String(required=True)
parent = fields.Nested(IdSchema, allow_none=True) # 使用 IdSchema 处理 parent 字段- name = fields.String(required=True): 这是一个普通的字符串字段。
- parent = fields.Nested(IdSchema, allow_none=True): 这是关键所在。fields.Nested(IdSchema) 告诉 Marshmallow，User 实例的 parent 属性应该通过 IdSchema 进行序列化。当 UserSchema 遇到 parent 字段时，它会获取 user_instance.parent 的值（即 "123-345"），并将其传递给 IdSchema 进行处理。如前所述，IdSchema 中的 @pre_dump 钩子会确保这个字符串被正确地包装成字典。
完整示例代码
下面是一个完整的示例，展示了如何定义模型、Schema 并进行序列化：
from marshmallow import Schema, fields, pre_dump
import json
# 1. 定义模型
class User:
def __init__(self, name, parent_id=None):
self.name = name
self.parent = parent_id # parent 属性存储的是一个字符串ID
def __repr__(self):
return f""
# 2. 定义辅助 Schema
class IdSchema(Schema):
id = fields.String(required=True)
@pre_dump
def wrap_id_for_dump(self, data, **kwargs):
"""
在序列化之前执行，将原始字符串ID包装成 {"id": "..."} 字典。
"""
if isinstance(data, str):
return {"id": data}
return data
# 3. 定义主 Schema
class UserSchema(Schema):
name = fields.String(required=True)
parent = fields.Nested(IdSchema, allow_none=True)
# 4. 创建模型实例并进行序列化
if __name__ == "__main__":
# 示例1：包含父ID的用户
user_with_parent = User(name="Alice", parent_id="user-123-abc")
user_schema = UserSchema()
serialized_data = user_schema.dump(user_with_parent)
print("序列化结果 (包含父ID):")
print(json.dumps(serialized_data, indent=2, ensure_ascii=False))
# 预期输出:
# {
# "name": "Alice",
# "parent": {
# "id": "user-123-abc"
# }
# }
print("\n" + "="*30 + "\n")
# 示例2：不包含父ID的用户
user_without_parent = User(name="Bob")
serialized_data_no_parent = user_schema.dump(user_without_parent)
print("序列化结果 (不包含父ID):")
print(json.dumps(serialized_data_no_parent, indent=2, ensure_ascii=False))
# 预期输出:
# {
# "name": "Bob",
# "parent": null
# } 运行上述代码，您将看到 parent 字段被成功地从一个字符串转换为了 {"id": "..."} 的嵌套对象结构。
注意事项与进阶
序列化（Dumping）的优势： 此方法在将模型实例中的简单字符串属性转换为嵌套的 JSON 对象进行 输出 时非常有效且简洁。它使得内部模型保持扁平化，而外部 API 接口则能提供更丰富的结构。
-
反序列化（Loading）的考虑： 本教程主要关注序列化（dumping）。如果您需要将接收到的 {"id": "value"} 格式的 JSON 数据反序列化回模型实例的扁平字符串ID（即 parent="value"），则 IdSchema 还需要一个 @post_load 钩子来提取 id 值：
class IdSchema(Schema): id = fields.String(required=True) @pre_dump def wrap_id_for_dump(self, data, **kwargs): if isinstance(data, str): return {"id": data} return data @post_load def unwrap_id_for_load(self, data, **kwargs): """ 在反序列化之后执行，从 {"id": "..."} 字典中提取原始字符串ID。 """ return data.get("id") # 返回 "id" 字段的值通过添加 unwrap_id_for_load 方法，当 UserSchema 反序列化 {"parent": {"id": "user-123-abc"}} 时，IdSchema 会将 {"id": "user-123-abc"} 转换为 "user-123-abc"，然后赋给 User 模型的 parent 属性。
-
其他实现方式： 对于更复杂的转换逻辑，您也可以考虑使用 fields.Method 或自定义 fields.Field。
- fields.Method: 允许您定义一个方法来处理字段的序列化逻辑，提供更大的灵活性。
- 自定义 fields.Field: 当转换逻辑非常通用且需要在多个 Schema 中复用时，创建自定义字段是最佳选择。 然而，对于将简单字符串包装为 {"id": "..."} 这种特定场景，fields.Nested 配合 @pre_dump 提供了一个清晰且易于理解的解决方案。
总结
本教程展示了在 Marshmallow 中如何优雅地将模型实例的字符串ID字段序列化为嵌套的 {"id": "value"} 对象结构。通过定义一个带有 @pre_dump 钩子的辅助 Schema，并将其与 fields.Nested 结合使用，我们能够有效地控制输出数据的格式，使其符合特定的 API 或数据交换规范。这种方法不仅功能强大，而且保持了代码的清晰性和可维护性。
