MongoEngine：Python 对象文档映射器（ODM）for MongoDB

MongoDB 是最受欢迎的 NoSQL 数据库之一，但直接使用原始的 PyMongo 可能会显得冗长且容易出错。您会花太多时间编写用于文档验证、字段类型检查和关系管理的样板代码。MongoEngine 解决了这个问题，它为 MongoDB 带来了类似 Django 的声明式抽象层，在超过十年的 Python 开发中经受了时间的考验。

MongoEngine 是一个 Python 对象文档映射器（ODM），为与 MongoDB 交互提供了高级的声明式 API。它将文档定义为带有类型字段的 Python 类，支持验证、关系、索引，并通过富有表达力的 QuerySet API 进行查询。位于 github.com/MongoEngine/mongoengine 的项目自 2010 年以来一直处于活跃开发中，并持续在 MongoDB 4.4 到 8.0 版本之间保持维护。

该库专为那些既想要 MongoDB 文档模型的灵活性，又想要类型化 Python 对象的安全性和生产效率的开发者而设计。如果您使用过 Django 的 ORM，那么 MongoEngine 的模式会让您立刻感到熟悉——这正是设计的初衷。

什么是 MongoEngine？

MongoEngine 是一个 Python ODM，将 MongoDB 文档映射到 Python 对象。它提供字段验证、查询构建、引用处理和模式强制执行，同时在需要时保留 MongoDB 的模式弹性。文档以类形式声明式定义，查询返回的是类型化的 Python 对象，而非原始字典。

from mongoengine import Document, StringField, IntField, ListField

class User(Document):
    name = StringField(required=True, max_length=50)
    email = StringField(required=True, unique=True)
    age = IntField(min_value=0)
    tags = ListField(StringField())

# 使用方式
user = User(name="Alice", email="alice@example.com", age=30, tags=["python", "mongodb"])
user.save()

MongoEngine 有哪些依赖？

MongoEngine 的依赖足迹非常轻量。

不需要 ORM 风格的魔术库或 C 扩展。MongoEngine 是在 PyMongo 之上的纯 Python 实现。

MongoEngine 支持哪些 MongoDB 版本？

MongoEngine 的兼容性矩阵涵盖 MongoDB 4.4 到最新的 8.0 版本。

该项目在所有支持的版本上维持 CI 测试，以确保与每个 MongoDB 发布版本的兼容性。

MongoEngine 模型在实践中长什么样？

MongoEngine 的声明式 API 让文档建模变得直观。以下是一个包含关系的更复杂示例：

from mongoengine import *

class Post(Document):
    title = StringField(required=True)
    content = StringField()
    published_date = DateTimeField()
    author = ReferenceField('User')
    tags = ListField(StringField())
    meta = {'indexes': ['title', 'published_date']}

class Comment(Document):
    post = ReferenceField(Post, reverse_delete_rule=CASCADE)
    author = StringField()
    text = StringField()
    created_date = DateTimeField(default=datetime.now)

查询使用流畅的 QuerySet API，可以干净地链式调用：

posts = Post.objects(author=user, published_date__gte=some_date)
comments = Comment.objects(post=post).order_by('-created_date')

MongoEngine 可以与 Flask 一起使用吗？

可以。Flask-MongoEngine 将 MongoEngine 包装在 Flask 应用程序中，提供了配置模式和集成的会话处理。

from flask import Flask
from flask_mongoengine import MongoEngine

app = Flask(__name__)
app.config['MONGODB_SETTINGS'] = {
    'host': 'mongodb://localhost:27017/mydatabase'
}
db = MongoEngine(app)

配置完成后，您的 MongoEngine Document 类可以在 Flask 的应用程序上下文中运作，包括请求范围的连接和模板全局变量。

常见问题

什么是 MongoEngine？

MongoEngine 是一个 Python 对象文档映射器（ODM），用于 MongoDB，将数据库文档映射到类型化的 Python 对象。它提供类似 Django ORM 的声明式 API，包含字段验证、查询构建和关系管理。

MongoEngine 有哪些依赖？

MongoEngine 唯一的硬依赖是 PyMongo 3.4+。可选依赖包括用于信号支持的 blinker 和用于大文件存储的 gridfs。

MongoEngine 支持哪些 MongoDB 版本？

完整支持 MongoDB 4.4、5.0、6.0、7.0 和 8.0。CI 测试涵盖所有这些版本，以确保持续的兼容性。

MongoEngine 模型长什么样？

MongoEngine 模型是一个继承自 Document 的 Python 类，带有类型化的字段定义（StringField、IntField、DateTimeField、ReferenceField 等）。查询使用类似 Django 的过滤语法，搭配流畅的 QuerySet API。

MongoEngine 是否与 Flask 兼容？

是的。Flask-MongoEngine 提供无缝集成，在 Flask 的应用程序上下文中处理配置和连接生命周期。

延伸阅读

• MongoEngine GitHub 仓库
• MongoEngine 官方文档
• PyMongo 文档
• MongoDB 官方网站
• Flask-MongoEngine 文档

classDiagram
    class Document {
        +save()
        +delete()
        +update()
    }
    class User {
        +StringField name
        +StringField email
        +IntField age
        +ListField tags
    }
    class Post {
        +StringField title
        +StringField content
        +DateTimeField published_date
        +ReferenceField author
        +ListField tags
    }
    class Comment {
        +ReferenceField post
        +StringField author
        +StringField text
        +DateTimeField created_date
    }
    Document <|-- User
    Document <|-- Post
    Document <|-- Comment
    Post --> User : author
    Comment --> Post : post

flowchart LR
    A[Python 代码] --> B[MongoEngine ODM]
    B --> C[验证层]
    C --> D[查询构建器]
    D --> E[PyMongo 驱动程序]
    E --> F[MongoDB 服务器]
    F --> G[MongoDB 4.4]
    F --> H[MongoDB 5.0]
    F --> I[MongoDB 6.0]
    F --> J[MongoDB 7.0]
    F --> K[MongoDB 8.0]