flask-pymongo 必须在应用上下文就绪后初始化，即先创建并配置 app，再实例化 pymongo；uri 需带 mongodb:// 前缀，连接池参数需按压测调优，避免连接数爆炸；查询前须确认 objectid 类型及集合存在性。
Flask-PyMongo 初始化必须在应用上下文就绪后
PyMongo 实例不能在 app = Flask(__name__) 之前创建，否则会报 RuntimeError: Working outside of application context 或 AttributeError: 'PyMongo' object has no attribute 'db'。这是因为 Flask 扩展依赖 app.config 读取 MONGO_URI，并需要注册 teardown 回调来管理连接生命周期。
正确做法是：先完成 app 创建与配置加载，再初始化 PyMongo；若用工厂模式，确保 create_app() 内部完成配置后再调用 PyMongo(app)。
- 模块顶层写
mongo = PyMongo(app)是错的——app此时尚未定义 -
mongo.db.collection.find()不能写在函数外（即模块级执行），否则启动时就触发，早于上下文建立 - URI 必须带
mongodb://前缀，副本集需含replicaSet=xxx，鉴权必须指定authSource=admin
teardown_appcontext 中只清理 session，不 dispose engine
Flask-PyMongo 的 PyMongo 对象内部封装了 motor 或原生 pymongo.MongoClient，其连接池由 MongoClient 自动管理。你不需要、也不应该在每次请求结束时调用 client.close() 或 engine.dispose() —— 这会强制销毁整个连接池，导致后续请求重建连接，性能暴跌。
真正该做的，是在 @app.teardown_appcontext 里确保当前请求绑定的数据库句柄被释放（比如 scoped session），但 PyMongo 本身不提供这种绑定机制，所以通常无需手动干预。如果你用了自定义封装或 flask-mongoengine，才需类似 db.session.remove() 的逻辑。
- 别写
mongo.cx.close()或mongo.db.client.close()在 teardown 里——这是反模式 - 连接复用靠的是
MongoClient内置连接池，默认maxPoolSize=100，够大多数业务用 - 如需精细控制，改配置项：
MONGO_MAX_POOL_SIZE=20、MONGO_MIN_POOL_SIZE=5，避免默认值撑爆 mongos
PyMongo 连接池参数必须按业务压测结果调优
连接数爆炸不是 MongoDB 服务扛不住，而是客户端驱动开太多连接又不回收。Java 驱动曾因默认 connectionsPerHost=100 × multiplier=5 导致单实例建 500 连接；Python 的 PyMongo 虽没 multiplier 概念，但 maxPoolSize 设太高一样会压垮 mongos，尤其在分片集群中。
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
实操建议：从 10–20 开始设 MONGO_MAX_POOL_SIZE，观察 mongostat 和 netstat -an | grep :27017 | wc -l，确认连接数稳定在预期范围内；再逐步加压，直到 QPS 上不去或延迟突增，此时的连接数就是你的安全上限。
- 别信“越大越好”——连接池过大反而增加内核调度和内存压力
- 高并发短查询场景可启用
maxIdleTimeMS=60000（需 PyMongo ≥ 4.0），让空闲连接自动释放 - 使用
mongodb+srv://连接 Atlas 时，srvMaxHosts和minPoolSize同样要设，否则 DNS 解析后可能意外拉起过多连接
查不到数据？先确认 ObjectId 类型和集合存在性
连接没泄露不代表查询有效。常见“插入成功但查不到”问题，90% 是类型或命名错误，而非连接问题。PyMongo 对 _id 字段极其敏感：传字符串进去永远查不到，必须转成 ObjectId 实例；集合名大小写、拼写、是否已创建，也直接影响 find 结果。
调试时优先跑这几行：
from bson import ObjectId
print(mongo.db.list_collection_names()) # 看集合名对不对
print(mongo.db.users.find_one({"_id": ObjectId("...")})) # 别传字符串
print(mongo.db.users.count_documents({})) # 确认文档真在库里
- 插入后立即查，记得等
result.acknowledged == True，否则可能是网络丢包误判 - 字段名别用 Python 关键字（如
class、type），点号访问会语法错误 - 生产环境务必开启
retryWrites=true&w=majority，否则主从切换期间可能丢写
连接泄漏往往藏在初始化顺序和连接池配置里，而不是代码里漏写了 close；而“连上了却查不到”，大概率是 ObjectId 类型或集合名踩坑。这两类问题互不干扰，排查时别混在一起猜。
