9.2 异步数据库操作（SQLAlchemy 1.4+）

Python FastAPI入门教程：异步数据库操作快速上手

FastAPI 教程

本教程面向Python初学者，无Web开发经验，通过生活化类比和简单示例，手把手教你使用FastAPI和异步SQLAlchemy进行数据库操作，快速建立Web开发信心。

FastAPI入门教程：异步数据库操作（SQLAlchemy 1.4+）

引言：你的第一个Web应用之旅

想象一下，你想建一个在线小卖部，但不知道从哪里开始。别担心！FastAPI就像你的超级助手，帮你快速搭建一个漂亮的后台系统。这个教程是为有Python语法基础的朋友设计的，即使你从没碰过Web开发，也能跟着一步步做出自己的应用。我们的目标是：玩得开心，快速成功！

第一部分：FastAPI基础——从"Hello World"开始

1.1 FastAPI是什么？

FastAPI是一个现代的Web框架，用于用Python构建API（应用程序接口）。你可以把它看作一个高效的快递员：用户发送请求（比如想买瓶水），FastAPI接收请求、处理数据，然后快速返回响应（比如确认订单）。它的特点是速度快（像闪电）、简单易用（像拼积木）。

1.2 安装FastAPI

首先，打开你的终端或命令提示符，确保你已经安装了Python（建议3.7+）。然后运行：

pip install fastapi uvicorn

这就像给你的工具箱里加了一把新锤子：FastAPI是框架，uvicorn是服务器，用来运行你的应用。

1.3 创建第一个API端点

创建一个新文件 main.py，输入以下代码：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World! 你的第一个FastAPI应用成功啦！"}

解释一下：

app = FastAPI()：创建一个FastAPI应用实例。
@app.get("/")：定义一个GET请求的端点，访问根路径 /。
read_root 函数：当用户访问 / 时，返回一个JSON响应。

现在，在终端运行：

uvicorn main:app --reload

打开浏览器，访问 http://127.0.0.1:8000，你会看到 {"message": "Hello, World! ..."}。成功时刻：恭喜！你已经创建了第一个API，就像点亮了一盏灯一样简单！

第二部分：添加异步数据库操作——让应用"活"起来

数据库是用来存储数据的地方，比如用户信息或商品库存。在FastAPI中，我们可以用异步方式操作数据库，这样应用不会卡顿，就像多线程工作一样高效。这里我们使用SQLAlchemy 1.4+，因为它支持异步，并且和FastAPI配合得很好。

2.1 异步概念小类比

想象你去咖啡店点单。同步方式是你排队等一杯咖啡做好才能点下一杯；异步方式是你点单后，店员去制作，你可以同时做其他事情（比如看书），等咖啡好了再通知你。FastAPI的异步数据库操作就是这样，让服务器同时处理多个请求而不阻塞。

2.2 安装SQLAlchemy和异步驱动

运行以下命令安装所需库：

pip install sqlalchemy databases[postgresql]

这里我们用PostgreSQL作为示例数据库，你也可以用SQLite或其他。如果你用SQLite，可以简化安装：pip install sqlalchemy databases。

2.3 设置数据库连接

在 main.py 中，添加代码来连接数据库。假设我们创建一个简单的用户管理系统。

首先，导入必要的模块：

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

# 数据库URL，这里用SQLite示例（文件数据库，适合初学者）
DATABASE_URL = "sqlite:///./test.db"

# 创建数据库实例
database = Database(DATABASE_URL)

# 定义模型基类
Base = declarative_base()

2.4 定义数据模型

添加一个User模型，代表用户表：

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    email = Column(String, unique=True, index=True)

这就像设计一张表格：有id（主键）、name和email列。

2.5 创建数据库表

在应用启动时创建表。修改 main.py，添加异步事件：

from fastapi import FastAPI
from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动时连接数据库并创建表
    engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False} if "sqlite" in DATABASE_URL else {})
    Base.metadata.create_all(bind=engine)
    await database.connect()
    yield
    # 关闭时断开连接
    await database.disconnect()

app = FastAPI(lifespan=lifespan)

2.6 添加API端点来操作数据库

现在，让我们创建一个端点来添加用户。在 main.py 中继续添加：

from fastapi import HTTPException
from pydantic import BaseModel

# 定义请求数据模型
class UserCreate(BaseModel):
    name: str
    email: str

@app.post("/users/")
async def create_user(user: UserCreate):
    query = "INSERT INTO users (name, email) VALUES (:name, :email)"
    values = {"name": user.name, "email": user.email}
    await database.execute(query=query, values=values)
    return {"message": f"用户 {user.name} 添加成功！id 会自动生成。"}

@app.get("/users/")
async def read_users():
    query = "SELECT * FROM users"
    results = await database.fetch_all(query=query)
    return {"users": results}

解释：

UserCreate 用Pydantic定义数据验证，确保输入正确。
create_user 端点：使用POST请求添加用户到数据库。
read_users 端点：使用GET请求读取所有用户。

2.7 测试数据库操作

重启uvicorn服务器（如果还在运行，它会自动重载）。然后，用工具如curl或浏览器扩展测试：

添加用户：发送POST请求到 http://127.0.0.1:8000/users/，Body为JSON：{"name": "小明", "email": "xiaoming@example.com"}。
查看用户：访问 http://127.0.0.1:8000/users/。

成功时刻：看到返回的消息和用户列表？太棒了！你现在已经让应用和数据库"对话"了，就像给机器人装上了记忆芯片！

第三部分：扩展与练习

为了让学习更深入，这里有一些小挑战：

更新用户：添加一个PUT端点来修改用户信息。
删除用户：添加一个DELETE端点。
错误处理：如果邮箱已存在，返回错误提示。

提示：你可以参考FastAPI和SQLAlchemy文档，但先尝试自己写代码——犯错是学习的一部分！

结论：你已经入门了！

通过这个教程，你学会了：

用FastAPI创建基本API端点。
使用异步SQLAlchemy操作数据库。
通过简单示例建立信心。

FastAPI和异步数据库的结合，让你的应用高效又强大。记住，Web开发就像搭乐高：从简单块开始，慢慢组合成复杂结构。继续探索，尝试添加更多功能，比如用户认证或文件上传。

下一步建议：

查看FastAPI官方文档（https://fastapi.tiangolo.com/）获取更多示例。
尝试用真实数据库如PostgreSQL替换SQLite。
加入社区，分享你的项目！

祝你在Web开发之旅中玩得开心！如果有问题，随时回来看这个教程复习。

上一章 9.1 SQLAlchemy 核心集成

下一章 9.3 数据库模型定义与关系