Marshmallow 是 Python 中一个非常流行且强大的库，主要用于对象的序列化（Serialization）和反序列化（Deserialization）。
它可以将复杂的 Python 对象（如类实例、字典、列表等）转换为 JSON 字符串或字典（序列化），也可以将 JSON 字符串或字典转换回 Python 对象（反序列化）。
🌟 为什么使用 Marshmallow？
- 结构化数据验证：在反序列化时自动验证数据格式、类型、必填字段等。
- 嵌套对象支持：轻松处理嵌套的字典或对象。
- 与 Web 框架集成良好：常用于 Flask、Django、FastAPI 等框架中处理 API 请求/响应数据。
- 灵活可扩展：支持自定义字段、转换器、钩子函数（hooks）等。
📦 安装
pip install marshmallow
📘 基本用法示例
定义 Schema
from marshmallow import Schema, fields, validate
class UserSchema(Schema):
id = fields.Int(dump_only=True) # 只用于输出（序列化）
name = fields.Str(required=True, validate=validate.Length(min=1, max=50))
email = fields.Email(required=True)
age = fields.Int(validate=validate.Range(min=0, max=120))
is_active = fields.Bool(default=True)
序列化（Python 对象 → 字典/JSON）
from marshmallow import pprint
user = {
"id": 1,
"name": "Alice",
"email": "alice@example.com",
"age": 30,
"is_active": True
}
schema = UserSchema()
result = schema.dump(user)
pprint(result)
# 输出: {'id': 1, 'name': 'Alice', 'email': 'alice@example.com', 'age': 30, 'is_active': True}
反序列化（字典/JSON → Python 对象）+ 验证
# 合法数据
data = {
"name": "Bob",
"email": "bob@example.com",
"age": 25
}
try:
result = schema.load(data)
print(result)
# 输出: {'name': 'Bob', 'email': 'bob@example.com', 'age': 25, 'is_active': True}
except Exception as e:
print(e)
# 非法数据（缺少必填字段）
invalid_data = {
"name": "Charlie" # 缺少 email
}
try:
result = schema.load(invalid_data)
except Exception as e:
print(e)
# 输出: {'email': ['Missing data for required field.']}
🔗 嵌套 Schema 示例
class AddressSchema(Schema):
street = fields.Str(required=True)
city = fields.Str(required=True)
class UserSchema(Schema):
id = fields.Int()
name = fields.Str()
address = fields.Nested(AddressSchema())
# 嵌套数据
user_data = {
"id": 1,
"name": "Alice",
"address": {
"street": "123 Main St",
"city": "New York"
}
}
schema = UserSchema()
result = schema.load(user_data)
print(result)
# 输出: {'id': 1, 'name': 'Alice', 'address': {'street': '123 Main St', 'city': 'New York'}}
🧩 常用字段类型
| 字段 | 说明 |
|---|---|
fields.Str() |
字符串 |
fields.Int() |
整数 |
fields.Float() |
浮点数 |
fields.Bool() |
布尔值 |
fields.Email() |
邮箱格式验证 |
fields.URL() |
URL 格式验证 |
fields.DateTime() |
日期时间（支持格式化） |
fields.List() |
列表 |
fields.Dict() |
字典 |
fields.Nested() |
嵌套 Schema |
fields.Method() |
自定义序列化/反序列化方法 |
fields.Function() |
自定义序列化函数 |
✅ 验证器（Validators）
Marshmallow 内置多种验证器，也可自定义：
from marshmallow import validate
# 内置验证器
name = fields.Str(validate=validate.Length(min=1, max=50))
age = fields.Int(validate=validate.Range(min=0, max=120))
email = fields.Email()
# 自定义验证器
def validate_not_bob(value):
if value.lower() == 'bob':
raise ValidationError("Name cannot be 'Bob'")
name = fields.Str(validate=validate_not_bob)
🔄 与 Web 框架集成（以 Flask 为例）
from flask import Flask, request, jsonify
from marshmallow import Schema, fields
app = Flask(__name__)
class UserSchema(Schema):
name = fields.Str(required=True)
email = fields.Email(required=True)
schema = UserSchema()
@app.route('/users', methods=['POST'])
def create_user():
try:
data = schema.load(request.json)
# 处理数据...
return jsonify({"message": "User created", "data": schema.dump(data)}), 201
except Exception as e:
return jsonify({"errors": e.messages}), 400
📚 官方文档
- 官网：https://marshmallow.readthedocs.io/
- GitHub：https://github.com/marshmallow-code/marshmallow
💡 小贴士
dump_only：字段仅在序列化时输出，不参与反序列化。load_only：字段仅在反序列化时输入，不参与序列化。required=True：该字段在反序列化时是必填的。default=value：如果字段缺失，使用默认值。
如果你有具体的使用场景（如 FastAPI、Django、数据模型转换等），可以告诉我，我可以提供更针对性的示例！
首发原创文章，作者：王坚，如若转载，请注明出处：https://idctop.com/marshmallow-python%e6%98%af%e4%bb%80%e4%b9%88%ef%bc%9fmarshmallow-python%e6%95%99%e7%a8%8b/
