marshmallow,一个清晰的 Python 库

大家好，我是木木。

今天给大家分享一个清晰的 Python 库，marshmallow。

marshmallow

marshmallow 是一个对象序列化、反序列化和校验库。它常用于 API 入参校验、输出结构控制、配置解析和对象转换。和只写一堆手工 if 判断相比，Schema 能把字段类型、默认值、必填规则、嵌套结构和错误信息集中描述出来。它不绑定 Django、Flask 或 FastAPI，适合在各种 Python 服务里做数据边界层。用好它的关键是把 Schema 当成外部输入和内部对象之间的契约，而不是随手写的转换函数。

项目地址：https://github.com/marshmallow-code/marshmallow

官方文档：https://marshmallow.readthedocs.io/

三大特点

Schema 清晰

字段、默认值和校验规则集中在 Schema 中，边界更明确。

错误友好

校验失败时返回结构化错误信息，适合直接反馈给 API 调用方。

框架无关

不强绑定 Web 框架，服务、脚本和任务系统里都能使用。

最佳实践

安装方式：pip install marshmallow。

第一段代码解决的问题是：定义用户 Schema，把外部输入转换成规范 Python dict，再按同一 Schema 输出。

frommarshmallowimportSchema,fieldsfromimportlib.metadataimportversionclassUserSchema(Schema):name=fields.Str(required=True)email=fields.Email(required=True)age=fields.Int(load_default=18)schema=UserSchema()data=schema.load({"name":"Alice","email":"alice@example.com"})print("package:",version("marshmallow"))print("loaded:",data)print("dumped:",schema.dump(data))

第二段代码解决的问题是：捕获校验失败并拿到结构化错误信息，适合 API 返回 400 响应。

frommarshmallowimportSchema,fields,ValidationErrorclassUserSchema(Schema):name=fields.Str(required=True)email=fields.Email(required=True)schema=UserSchema()try:schema.load({"name":"Bob","email":"bad"})exceptValidationErroraserr:print("errors:",err.messages)print("valid data:",err.valid_data)

环境与版本信息

本文示例使用 Python 3.11.0，marshmallow 3.26.2。示例只使用核心 Schema 和 fields，不依赖任何 Web 框架。

高级功能

进阶一点看嵌套 Schema。真实 API 里经常有地址、订单明细、权限列表这样的嵌套结构。用 fields.Nested 可以把复杂结构拆成多个小 Schema，既便于测试，也便于复用。

frommarshmallowimportSchema,fieldsclassAddressSchema(Schema):city=fields.Str(required=True)zip_code=fields.Str(data_key="zip")classUserSchema(Schema):name=fields.Str(required=True)address=fields.Nested(AddressSchema)schema=UserSchema()loaded=schema.load({"name":"Alice","address":{"city":"Shanghai","zip":"200000"}})print("city:",loaded["address"]["city"])print("dumped:",schema.dump(loaded))

适用场景

适合 API 入参校验、响应字段控制、对象和 dict 转换、配置文件解析、消息队列 payload 校验，以及跨框架的数据边界层。

不适用场景

不适合需要 ORM 全套模型能力、强类型编译期检查，或团队已经统一使用 Pydantic 并且没有跨框架兼容需求的项目。

上线检查

1. 给外部输入都走 Schema，避免业务层混入零散字段判断。
2. 为错误信息写测试，确认调用方能理解字段失败原因。
3. 对嵌套结构拆小 Schema，不要把所有字段堆在一个巨大类里。

总结

marshmallow 的价值在于清晰地守住数据边界。字段规则写明白后，API 和任务代码都会少很多隐形假设。