9.1 SQLAlchemy 核心集成

Python FastAPI入门教程：SQLAlchemy核心集成实战

FastAPI 教程

面向Python初学者的FastAPI入门教程，详细讲解如何集成SQLAlchemy核心进行数据库操作。教程简单易懂，包含生活化类比和动手实践示例，帮助无Web开发经验的用户快速上手并建立信心。

FastAPI入门教程：SQLAlchemy核心集成

欢迎来到FastAPI世界！如果你已经掌握了一些Python基础，但从未接触过Web开发，别担心，这个教程将引导你一步步创建你的第一个Web应用，并集成SQLAlchemy核心来处理数据库。想象一下，FastAPI就像一家快速服务餐厅，负责接收订单（HTTP请求）并迅速提供美味的菜肴（响应），而SQLAlchemy核心就是厨房里的高效厨师，帮你管理食材（数据库数据）。让我们一起动手吧！

1. 什么是FastAPI？为什么选择它？

FastAPI是一个现代、快速的Web框架，专为构建API（应用程序编程接口）而设计。它类似于一个超级高效的餐厅接待员，能快速理解顾客的需求（如GET或POST请求），并返回精准的结果。对于初学者来说，它的优势在于：

简单易学：代码清晰，不需要复杂的配置。
快速上手：只需几行代码就能运行一个API。
自动文档：它会自动生成交互式API文档，让你轻松测试。

想象一下，你刚学开车，FastAPI就像一辆自动挡汽车——操作简单，让你专注于目的地（你的应用逻辑），而不是复杂的换挡过程。

2. 安装和环境设置

首先，确保你已经安装了Python（推荐3.7以上版本）。然后，打开终端或命令行，运行以下命令来安装必要的库：

pip install fastapi uvicorn sqlalchemy

解释一下：

fastapi：核心框架，就像餐厅的菜单系统。
uvicorn：服务器，负责运行应用，类似于厨房的炉子。
sqlalchemy：数据库工具，我们主要使用其核心部分（Core）来操作数据库，想象成一套灵活的厨具。

成功安装后，恭喜你！你已经迈出了第一步，准备点火开灶。

3. 第一个FastAPI应用：Hello World

让我们从一个简单的例子开始，感受FastAPI的魅力。创建一个新文件，命名为 main.py，并写入以下代码：

from fastapi import FastAPI

# 创建FastAPI应用实例，就像开启一家新餐厅
app = FastAPI()

# 定义一个路由（或路径），例如主页，就像餐厅的欢迎入口
@app.get("/")
async def read_root():
    return {"message": "Hello World!"}

保存文件后，在终端运行：

uvicorn main:app --reload

main:app 告诉服务器从 main.py 文件中加载 app 实例。
--reload 开启自动重载，当你修改代码时，服务器会自动重启，就像餐厅及时更新菜单。

打开浏览器，访问 http://127.0.0.1:8000，你会看到 {"message": "Hello World!"} 的JSON响应。太棒了！你刚刚创建了第一个API端点，感受到了成功的喜悦。

4. 基础概念：路由和请求

在FastAPI中，路由定义了URL路径，而请求类型（如GET、POST）决定了操作。例如：

@app.get("/items")：处理获取物品列表的请求。
@app.post("/items")：处理添加新物品的请求。

这就像餐厅里的不同服务台：一个负责点菜（POST），另一个负责上菜（GET）。尝试扩展你的应用，添加另一个路由：

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id, "message": "Item retrieved!"}

访问 http://127.0.0.1:8000/items/123，你会看到根据ID返回的数据。通过这个简单示例，你已经掌握了路由基础，可以自信地设计更多API了。

5. 引入数据库：为什么需要SQLAlchemy核心？

现在，你的餐厅只提供静态菜单（硬编码数据），但真实餐厅需要管理库存（数据库）。SQLAlchemy核心是一个Python库，它让你用Python代码直接操作数据库，而不用写复杂的SQL语句。想象它像一个翻译官，把Python命令转换成数据库能理解的语言。

与SQLAlchemy ORM（对象关系映射）相比，核心更轻量级，适合初学者上手，因为它更接近SQL，但提供了Python接口。例如，你可以用它来连接数据库、执行查询和更新数据。

6. SQLAlchemy核心集成实战

让我们集成SQLAlchemy核心，来模拟一个简单的物品管理系统。我们将使用SQLite数据库，因为它轻便易用，就像一个小型厨房储物柜。

首先，创建一个新文件 database.py，设置数据库连接：

from sqlalchemy import create_engine, MetaData

# 创建一个SQLite数据库引擎，连接到一个文件数据库（如餐厅的库存记录本）
engine = create_engine("sqlite:///./test.db", echo=True)  # echo=True 会打印SQL语句，方便调试
metadata = MetaData()

create_engine：建立与数据库的连接。
MetaData：用于管理数据库表结构。

接下来，定义一张表，比如 items 表，记录物品信息。在 database.py 中添加：

from sqlalchemy import Table, Column, Integer, String

# 定义表结构：物品表，有ID和名称两列
items_table = Table(
    "items",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("name", String),
)

# 创建所有表（如果不存在）
metadata.create_all(engine)

现在，在 main.py 中导入并使用它。我们将创建一个新路由来添加和获取物品。首先，添加导入：

from sqlalchemy.orm import sessionmaker
from database import engine, items_table

# 创建会话，用于执行数据库操作，就像厨房的工作台
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

然后，添加一个POST路由来创建物品：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel  # Pydantic用于数据验证，就像餐厅的质检员

app = FastAPI()

# 定义数据模型，确保输入数据正确
class ItemCreate(BaseModel):
    name: str

@app.post("/items/")
async def create_item(item: ItemCreate):
    # 打开数据库会话
    db = SessionLocal()
    try:
        # 执行插入操作
        insert_stmt = items_table.insert().values(name=item.name)
        db.execute(insert_stmt)
        db.commit()  # 提交更改，就像确认订单
        return {"message": "Item created successfully!"}
    except Exception as e:
        db.rollback()  # 如果出错，回滚更改
        raise HTTPException(status_code=500, detail=str(e))
    finally:
        db.close()  # 关闭会话，清理工作台

最后，更新GET路由来获取所有物品：

@app.get("/items/")
async def read_items():
    db = SessionLocal()
    try:
        # 查询所有物品
        select_stmt = items_table.select()
        result = db.execute(select_stmt)
        items = result.fetchall()  # 获取所有行
        # 将结果转换为列表字典
        return [{"id": row[0], "name": row[1]} for row in items]
    finally:
        db.close()

保存文件，确保 database.py 和 main.py 在同一目录。重启服务器（如果没运行，再次运行 uvicorn main:app --reload）。

现在，使用工具如curl或浏览器扩展（如Postman）测试：

POST请求到 http://127.0.0.1:8000/items/，JSON体为 {"name": "Apple"}。
GET请求到 http://127.0.0.1:8000/items/，查看添加的物品列表。

哇！你刚刚成功集成了SQLAlchemy核心，能动态管理数据了。每次添加物品，就像在餐厅库存中添加新食材，而获取列表就像查看菜单。这个动手实践让你体验到了从零到一的成就感。

7. 扩展和测试

尝试添加更多功能：

更新物品：使用 @app.put("/items/{item_id}") 和 items_table.update()。
删除物品：使用 @app.delete("/items/{item_id}") 和 items_table.delete()。

记得使用Pydantic模型验证数据，这能避免错误输入，就像餐厅检查食材新鲜度。

运行应用时，访问 http://127.0.0.1:8000/docs，你会看到自动生成的交互式文档，可以轻松测试所有API端点——这是FastAPI的另一个惊喜时刻！

8. 总结和下一步

在这个教程中，你学会了：

安装FastAPI和基础设置：就像准备厨房设备。
创建简单API：从Hello World开始建立信心。
集成SQLAlchemy核心：连接数据库，执行CRUD操作，模拟真实应用场景。
使用生活化类比：将技术概念转化为熟悉的餐厅比喻，帮助理解。

你已经迈出了Web开发的第一步！继续探索FastAPI的高级功能，如依赖注入、中间件或集成更复杂的数据库。记住，学习就像烹饪——多练习，就能做出更美味的菜肴。祝你在编程之旅中享受乐趣！

如果遇到问题，参考官方文档或在线社区。现在，去创建你的下一个项目吧！

上一章 8.7 请求生命周期与中间件执行顺序

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