FastAPI入门教程：ORM模式与数据模型转换

欢迎来到FastAPI世界！

嘿，你好！如果你已经熟悉Python的基本语法，但还没接触过Web开发，那这个教程就是为你准备的。今天，我们将一起探索FastAPI中的ORM（对象关系映射）模式和数据模型转换，就像学习如何使用一个新工具来整理你的数据一样。别担心，我们会用简单的生活化类比来理解概念，并通过动手实践让你快速看到成果。

第一部分：什么是ORM？

想象一下，你有一个Excel表格，里面存储了朋友的姓名和年龄。在Python中，我们可能用字典或列表来表示这些数据。ORM就像一个聪明的助手，它能帮你把数据库中的表（比如那个Excel表格）自动转换成Python中的对象（比如类）。这样，你就不需要写复杂的SQL语句，直接用Python代码操作数据就行了！

• 类比：把数据库表想象成一个衣柜，每件衣服（数据）放在不同的抽屉（表）里。ORM就是你的私人整理师，帮你把衣服（数据）从抽屉里拿出来，整齐地挂起来（变成Python对象），方便你使用。

第二部分：什么是数据模型转换？

在FastAPI中，我们经常使用Pydantic模型来处理API的请求和响应。数据模型转换就像是把一种格式的数据（比如从用户那里收到的JSON数据）转换成另一种格式（比如数据库中的记录），或者反过来。这确保了数据在流动时是干净、有效的。

• 类比：假设你要寄一封信，信封上需要写地址（Pydantic模型验证数据），然后把信塞进邮箱（数据库保存）。数据模型转换就是确保地址正确、信的内容完整的过程。

第三部分：为什么需要它们？

结合起来，ORM和Pydantic模型让Web开发变得更简单：ORM帮你轻松操作数据库，Pydantic帮你确保数据安全、格式正确。在FastAPI中，这俩是好搭档，能快速构建可靠的API。

第四部分：动手实践：设置环境

首先，确保你有Python环境。然后，安装必要的库：

pip install fastapi uvicorn sqlalchemy pydantic

这就像准备你的工具箱：fastapi 是框架，uvicorn 是服务器，sqlalchemy 是ORM工具，pydantic 是数据验证工具。

第五部分：创建ORM模型

让我们创建一个简单的朋友信息数据库。在Python文件中，我们定义ORM模型。

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

# 创建数据库引擎（假设用SQLite，无需额外安装）
DATABASE_URL = "sqlite:///./test.db"  # 数据库文件路径
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})

# 基类
Base = declarative_base()

# 定义ORM模型：对应数据库表
class FriendORM(Base):
    __tablename__ = "friends"  # 表名
    
    id = Column(Integer, primary_key=True, index=True)  # 主键
    name = Column(String)  # 姓名
    age = Column(Integer)  # 年龄

# 创建表
Base.metadata.create_all(bind=engine)

# 创建会话，用于操作数据库
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

成功时刻：运行这段代码后，它会自动创建一个数据库文件 test.db 和 friends 表。你可以用SQLite浏览器查看，或者继续代码中操作——现在，你的数据库已经准备好啦！

第六部分：创建Pydantic模型

接下来，我们定义Pydantic模型来处理API的数据。这些模型是用于验证和序列化的。

from pydantic import BaseModel

# 定义Pydantic模型：用于API请求和响应
class FriendCreate(BaseModel):
    name: str
    age: int

class FriendResponse(BaseModel):
    id: int
    name: str
    age: int

• 类比：FriendCreate 就像你要寄的信的内容模板（比如必须写姓名和年龄），FriendResponse 是回信的模板（包括自动生成的ID）。

第七部分：数据模型转换示例

现在，让我们创建一个简单的API端点，展示如何转换。我们将实现添加朋友的功能。

from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session

app = FastAPI()  # 创建FastAPI应用

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.post("/friends/", response_model=FriendResponse)  # 定义POST端点，指定响应模型
async def create_friend(friend: FriendCreate, db: Session = Depends(get_db)):
    # 将Pydantic模型转换为ORM模型
    db_friend = FriendORM(name=friend.name, age=friend.age)
    
    # 保存到数据库
    db.add(db_friend)
    db.commit()
    db.refresh(db_friend)
    
    # 将ORM模型转换为Pydantic模型作为响应
    return db_friend

成功时刻：启动服务器并测试！运行 uvicorn your_file_name:app --reload（将 your_file_name 替换为你的Python文件名），然后打开浏览器访问 http://127.0.0.1:8000/docs（FastAPI自动生成的API文档）。你可以在这个界面直接测试 POST /friends/ 端点，输入JSON数据如 {"name": "Alice", "age": 25}，点击“Try it out”，然后看到返回的响应中包含生成的ID——这证明了ORM和Pydantic模型转换成功，数据被正确保存和返回了！

第八部分：进阶示例：获取所有朋友

为了加深理解，我们再添加一个获取所有朋友的端点。

@app.get("/friends/", response_model=list[FriendResponse])  # 响应模型是列表
async def read_friends(db: Session = Depends(get_db)):
    friends = db.query(FriendORM).all()  # 从数据库查询所有记录
    return friends  # 自动转换ORM模型为Pydantic模型列表

运行后，在API文档中测试 GET /friends/，你会看到一个朋友列表——又一个成功时刻，数据从数据库到API流畅转换了！

总结

恭喜你！通过这个教程，你已经学会了：

• ORM：如何用SQLAlchemy定义数据库表对应的Python对象。
• 数据模型转换：如何使用Pydantic模型验证API数据，并在ORM和Pydantic之间转换。
• 动手实践：创建了完整的API端点，能接收数据、保存到数据库并返回响应。

这只是一个开始。FastAPI还有很多其他功能等着你去探索，比如异步支持、依赖注入等。如果你喜欢，可以继续学习更多教程。记住，关键是动手实践——尝试修改代码、添加新字段或新端点，你会很快变得更熟练。

祝你学习愉快！如果有问题，欢迎查阅FastAPI官方文档或社区支持。