FastAPI + SQLAlchemy 实战：从零构建高效父-子关系API

大家好，今天我要分享一个实用的FastAPI开发案例，带你从零开始构建一个包含父子关系的数据模型API。无论你是FastAPI新手还是想深入了解SQLAlchemy ORM的使用，这篇文章都能给你带来收获。

为什么选择FastAPI？

FastAPI作为Python领域最快的Web框架之一，凭借其自动生成API文档、基于Python类型提示、高性能等特性，正在成为越来越多开发者的首选。结合SQLAlchemy这个强大的ORM工具，我们可以快速构建出规范、高效的RESTful API。

项目背景

我们将构建一个简单的”父母-孩子”关系管理系统。这个场景很常见，比如：

电商中的订单-订单项关系
博客中的文章-评论关系
组织架构中的部门-员工关系

通过这个案例，你将学会如何处理这种典型的一对多关系。

环境准备

首先安装必要的依赖：

1	pip install fastapi sqlalchemy uvicorn pydantic

代码实现详解

1. 数据库配置

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

# 使用SQLite数据库，方便快速开发
SQLALCHEMY_DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(
    SQLALCHEMY_DATABASE_URL, 
    connect_args={"check_same_thread": False}  # SQLite特定配置
)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

关键点：

check_same_thread=False 允许在不同线程中使用同一个SQLite连接
sessionmaker 创建数据库会话工厂
declarative_base() 创建模型基类

2. 数据库依赖注入

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

这个生成器函数是FastAPI依赖注入系统的核心，确保每个请求都有独立的数据库会话，请求结束后自动关闭连接。

3. SQLAlchemy模型设计

class ParentDB(Base):
    __tablename__ = "parents"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    # 建立一对多关系
    children = relationship("ChildDB", back_populates="parent")

class ChildDB(Base):
    __tablename__ = "children"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    parent_id = Column(Integer, ForeignKey("parents.id"))
    parent = relationship("ParentDB", back_populates="children")

设计亮点：

使用ForeignKey建立外键约束
relationship创建ORM级别的双向关系
back_populates明确指定对方的关系属性

4. Pydantic模型（Schema）

class Child(BaseModel):
    name: str

    class Config:
        orm_mode = True

class Parent(BaseModel):
    name: str
    children: list[Child] = []  # 默认空列表

    class Config:
        orm_mode = True

Pydantic模型的作用：

请求体验证
响应数据序列化
orm_mode=True 允许从ORM模型自动转换

5. API端点实现

创建父母

@app.post("/parents/", response_model=Parent)
def create_parent(parent: Parent, db: Session = Depends(get_db)):
    db_parent = ParentDB(name=parent.name)
    db.add(db_parent)
    db.commit()
    db.refresh(db_parent)
    return db_parent

为孩子添加父母

@app.post("/parents/{parent_id}/children/", response_model=Child)
def create_child(parent_id: int, child: Child, db: Session = Depends(get_db)):
    db_child = ChildDB(name=child.name, parent_id=parent_id)
    db.add(db_child)
    db.commit()
    db.refresh(db_child)
    return db_child

查询父母及其孩子

@app.get("/parents/{parent_id}/", response_model=Parent)
def read_parent(parent_id: int, db: Session = Depends(get_db)):
    db_parent = db.query(ParentDB).filter(ParentDB.id == parent_id).first()
    if db_parent is None:
        raise HTTPException(status_code=404, detail="Parent not found")
    return db_parent

注意：由于我们配置了relationship，当返回db_parent时，SQLAlchemy会自动加载关联的children数据。

更新父母信息

@app.put("/parents/{parent_id}/", response_model=Parent)
def update_parent(parent_id: int, parent: Parent, db: Session = Depends(get_db)):
    db_parent = db.query(ParentDB).filter(ParentDB.id == parent_id).first()
    if db_parent is None:
        raise HTTPException(status_code=404, detail="Parent not found")
    db_parent.name = parent.name
    db.commit()
    db.refresh(db_parent)
    return db_parent

删除父母

@app.delete("/parents/{parent_id}/")
def delete_parent(parent_id: int, db: Session = Depends(get_db)):
    db_parent = db.query(ParentDB).filter(ParentDB.id == parent_id).first()
    if db_parent is None:
        raise HTTPException(status_code=404, detail="Parent not found")
    db.delete(db_parent)
    db.commit()
    return {"message": "Parent deleted successfully"}

级联删除说明：默认情况下，删除Parent时，如果有关联的Child，数据库会报错。实际项目中可以根据需求配置cascade="all, delete"参数。

运行测试

创建文件main.py，复制以上代码，然后运行：

1	uvicorn main:app --reload

访问 http://localhost:8000/docs 查看自动生成的交互式API文档。

API测试流程

创建父母：POST /parents/ {“name”: “张三”}
添加孩子：POST /parents/1/children/ {“name”: “张小三”}
查询父母：GET /parents/1/（会同时返回孩子信息）
更新父母：PUT /parents/1/ {“name”: “张四”}
删除父母：DELETE /parents/1/

进阶优化建议

添加数据验证：在Pydantic模型中添加字段验证

from pydantic import Field

class Child(BaseModel):
    name: str = Field(..., min_length=1, max_length=50)

处理级联操作：在relationship中配置cascade

1	children = relationship("ChildDB", back_populates="parent", cascade="all, delete-orphan")

添加分页功能：为列表接口添加offset/limit参数
使用异步数据库驱动：配合databases或SQLAlchemy 1.4+的异步特性

总结

通过这个实战案例，我们学习了：

FastAPI的项目结构和依赖注入
SQLAlchemy ORM的基本使用
一对多关系的建模方法
RESTful API的设计规范
Pydantic模型的验证和序列化

这个基础模板可以轻松扩展到更复杂的业务场景。FastAPI + SQLAlchemy的组合，既能保证开发效率，又能提供良好的性能和代码可维护性。

希望这篇文章对你有帮助！如果你在实践过程中遇到任何问题，欢迎在评论区留言讨论。

文章作者: Guopingd

文章链接: http://nosaw.com/2026/02/23/202602/FastAPI%20+%20SQLAlchemy%20%E5%AE%9E%E6%88%98%EF%BC%9A%E4%BB%8E%E9%9B%B6%E6%9E%84%E5%BB%BA%E9%AB%98%E6%95%88%E7%88%B6-%E5%AD%90%E5%85%B3%E7%B3%BBAPI/

SQLAlchemy

相关推荐

2025-10-12

SQLAlchemy 数据库操作完整指南：从模型定义到CRUD实战

SQLAlchemy 数据库操作完整指南：从模型定义到CRUD实战SQLAlchemy 是 Python 中最著名的 ORM（对象关系映射）框架之一，它允许开发者使用 Python 类来定义数据库表，并通过简单的 Python 代码执行各种数据库操作。本文将带你全面了解 SQLAlchemy 的基本使用方法。 1. 环境准备与引擎创建首先需要安装 SQLAlchemy，然后创建数据库引擎： 1234from sqlalchemy import create_engine# 创建 SQLite 数据库引擎engine = create_engine('sqlite:///user.db') 这里我们使用 SQLite 作为示例数据库，实际项目中可以根据需要替换为 MySQL、PostgreSQL 等。 2. 定义数据模型使用声明式基类来定义数据模型： 12345678910111213from sqlalchemy.ext.declarative import declarative_basefrom sqlalchemy import Column, Int...

2026-02-23

FastAPI + SQLAlchemy 进阶：多对多关系实战

FastAPI + SQLAlchemy 进阶：多对多关系实战大家好，上次我们学习了如何使用FastAPI和SQLAlchemy构建一对多的父子关系API。今天，让我们更进一步，探讨更复杂的多对多关系场景——学生选课系统。为什么需要多对多关系？在实际业务中，很多关系都不是简单的一对多：学生和课程：一个学生可以选多门课，一门课也可以被多个学生选文章和标签：一篇文章可以有多个标签，一个标签可以对应多篇文章用户和角色：一个用户可以有多个角色，一个角色可以分配给多个用户这就是典型的多对多关系。今天我们就以学生选课系统为例，深入剖析多对多关系的实现。项目结构概览我们将构建一个完整的选课系统API，包含以下功能：学生管理（增删改查）课程管理（增删改查）学生选课/退课查询学生及其所选课程代码深度解析1. 环境准备（同上篇）1pip install fastapi sqlalchemy uvicorn pydantic 2. 数据库配置（新增echo功能）123456789101112from sqlalchemy import create_engin...

2026-03-01

FastAPI + SQLAlchemy 异步事务完全指南

🚀 FastAPI + SQLAlchemy 异步事务完全指南｜一篇搞定提交/回滚/异常处理 💡 收藏级教程：从原理到实践，手把手教你写出健壮的异步数据库事务代码 📌 开篇：为什么异步事务这么重要？在现代高并发应用中，数据一致性是生命线。而事务（Transaction）正是保障一致性的核心机制。当 FastAPI 遇上 SQLAlchemy 的异步模式，很多开发者会困惑： ❓ commit() 和 flush() 有什么区别？ ❓ 异常时如何正确回滚？ ❓ async with db.begin() 真的能自动管理事务吗？今天，我们就用一个完整可运行的示例，彻底搞懂 FastAPI 中的异步事务！🎯 🗂️ 项目结构一览123456project/├── main.py # 路由与事务逻辑（核心⭐）├── database.py # 数据库连接配置├── models.py # SQLAlchemy 模型定义├── schemas.py # Pydantic 数据校验└── requi...