扫描二维码
关注或者微信搜一搜：编程智域前端至全栈交流与成长

探索数千个预构建的 AI 应用，开启你的下一个伟大创意：https://tools.cmdragon.cn/

第一章：MongoDB 与 FastAPI 基础集成

1.1 环境准备与依赖安装

运行环境要求

Python 3.8+
MongoDB 4.4+
FastAPI 0.95+
Motor 3.1+

安装所需依赖：

pip install fastapi==0.95.0 
pip install motor==3.1.2
pip install pydantic==1.10.7
pip install python-multipart==0.0.6
pip install uvicorn==0.21.1

1.2 异步数据库连接

Motor驱动配置

from fastapi import FastAPI
from motor.motor_asyncio import AsyncIOMotorClient
from pydantic import BaseModel, Field
import os

app = FastAPI()


# MongoDB配置模型
class MongoDBConfig:
    MONGO_URI = os.getenv("MONGO_URI", "mongodb://localhost:27017")
    DB_NAME = "fastapi_demo"
    COLLECTION = "users"


# 异步数据库客户端
@app.on_event("startup")
async def startup_db_client():
    app.mongodb_client = AsyncIOMotorClient(MongoDBConfig.MONGO_URI)
    app.mongodb = app.mongodb_client[MongoDBConfig.DB_NAME]


@app.on_event("shutdown")
async def shutdown_db_client():
    app.mongodb_client.close()

1.3 数据模型与CRUD操作

Pydantic数据验证

from bson import ObjectId
from typing import Optional


class PyObjectId(ObjectId):
    @classmethod
    def __get_validators__(cls):
        yield cls.validate

    @classmethod
    def validate(cls, v):
        if not ObjectId.is_valid(v):
            raise ValueError("Invalid ObjectId")
        return ObjectId(v)


class UserCreate(BaseModel):
    name: str = Field(..., min_length=3)
    age: int = Field(..., gt=0)
    tags: list[str] = []


class UserResponse(UserCreate):
    id: PyObjectId = Field(default_factory=PyObjectId, alias="_id")

    class Config:
        json_encoders = {ObjectId: str}

异步CRUD实现

插入文档

@app.post("/users/")
async def create_user(user: User):
    result = await db.users.insert_one(user.dict())
    return {"id": str(result.inserted_id)}

查询文档

@app.get("/users/{user_id}")
async def read_user(user_id: str):
    if not ObjectId.is_valid(user_id):
        raise HTTPException(400, "Invalid ID format")

    user = await db.users.find_one({"_id": ObjectId(user_id)})
    if not user:
        raise HTTPException(404, "User not found")

    # 转换 MongoDB 的 ObjectId 为字符串
    user["id"] = str(user.pop("_id"))
    return user

更新文档

@app.patch("/users/{user_id}")
async def update_user(user_id: str, update_data: dict):
    # 过滤无效字段
    valid_fields = User.__annotations__.keys()
    filtered_data = {k: v for k, v in update_data.items() if k in valid_fields}

    result = await db.users.update_one(
        {"_id": ObjectId(user_id)},
        {"$set": filtered_data}
    )
    return {"modified_count": result.modified_count}

1.4 聚合管道实践

用户分析接口

from fastapi import APIRouter

router = APIRouter()


@router.get("/users/stats/age-distribution")
async def get_age_distribution():
    pipeline = [
        {"$group": {
            "_id": "$age",
            "count": {"$sum": 1}
        }},
        {"$sort": {"_id": 1}}
    ]

    results = []
    async for doc in app.mongodb.users.aggregate(pipeline):
        results.append({
            "age": doc["_id"],
            "count": doc["count"]
        })
    return results

1.5 索引优化策略

索引创建示例

async def create_indexes():
    # 单字段索引
    await app.mongodb.users.create_index("name", unique=True)

    # 复合索引
    await app.mongodb.users.create_index([("age", 1), ("tags", 1)])

    # 文本索引
    await app.mongodb.users.create_index([("name", "text")])

课后Quiz

为什么在FastAPI中推荐使用Motor驱动而不是同步的PyMongo？
答案：FastAPI基于异步架构，Motor作为异步驱动可以避免阻塞事件循环，提升系统吞吐量。PyMongo的同步操作会阻塞整个事件循环，导致性能下降。
配置 Motor 驱动时，为什么要传入 io_loop=app.state.loop 参数？
- A. 为了提升查询速度
- B. 确保使用相同的事件循环
- C. 强制使用同步模式
- 答案：B，保证异步驱动使用与 FastAPI 相同的事件循环
处理 MongoDB 的日期字段时，Pydantic 模型为什么推荐使用 datetime.utcnow()？
- A. 减少存储空间
- B. 避免时区混乱
- C. 提高序列化速度
- 答案：B，统一使用 UTC 时间可避免时区转换问题

当收到”422 Unprocessable Entity”错误时，应该如何快速定位问题？
答案：检查请求数据是否符合Pydantic模型定义，使用Swagger文档验证请求格式。错误响应体包含详细的字段验证信息。
如何验证用户年龄字段必须是正整数？
1
age: int = Field(..., gt=0)
该定义表示age必须大于0（gt=greater than）

常见报错解决方案

错误1：ServerSelectionTimeoutError

现象：连接MongoDB超时
原因：MongoDB服务未启动或配置错误
解决：
1. 检查MongoDB服务状态：sudo systemctl status mongod
2. 验证连接字符串格式：mongodb://username:password@host:port

错误2：ValidationError

现象：返回422状态码
原因：请求数据不符合Pydantic模型

解决：

查看错误响应中的detail字段

使用try-except捕获ValidationError：

from fastapi.exceptions import RequestValidationError

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request, exc):
    return JSONResponse(status_code=400, content={"detail": exc.errors()})

错误3：查询性能低下

现象：API响应缓慢
解决：
1. 使用explain()分析查询计划
2. 创建合适索引
3. 优化聚合管道阶段顺序

余下文章内容请点击跳转至个人博客页面或者扫码关注或者微信搜一搜：编程智域前端至全栈交流与成长，阅读完整的文章：

异步之舞：FastAPI与MongoDB的深度协奏