Python初学者FastAPI入门教程：Alembic配置与使用

简介

欢迎来到FastAPI入门教程！如果你是Python初学者，有基础语法知识但没有Web开发经验，那你就来对地方了。今天，我们将一起学习如何用FastAPI创建一个简单的Web应用，并引入Alembic来管理数据库迁移。不用担心复杂理论，我会用生活化类比帮你轻松理解，并通过大量简单示例让你快速体验成功时刻。想象一下：FastAPI就像是一个超级快递员，能快速将你的API代码交付给用户；数据库像一个仓库，存储你的数据；而Alembic则像是仓库管理员，负责更新仓库的布局，确保数据整齐有序。准备好了吗？让我们开始吧！

前置条件

• 确保你安装了Python 3.7或更高版本。如果没有，去Python官网下载并安装。
• 熟悉基础Python语法，比如变量、函数和导入模块。

第一步：安装FastAPI和相关工具

首先，我们需要安装必要的工具。打开终端或命令提示符，运行以下命令来安装FastAPI、SQLAlchemy、Alembic和一个ASGI服务器（如Uvicorn）：

pip install fastapi uvicorn sqlalchemy alembic

这就像是为你的项目准备工具包——快递员（FastAPI）、服务器（Uvicorn）、仓库（SQLAlchemy）和管理员（Alembic）都齐了。成功安装后，你会看到类似“Successfully installed”的消息，这是你的第一个成功时刻！

第二步：创建第一个FastAPI应用

现在，让我们创建一个简单的FastAPI应用，体验一下“Hello World”的乐趣。在项目中创建一个新文件 main.py，并输入以下代码：

from fastapi import FastAPI

app = FastAPI()  # 初始化FastAPI应用，就像启动快递员

@app.get("/")  # 定义一个GET路由，当访问根路径时触发
def read_root():
    return {"Hello": "World"}  # 返回一个JSON响应

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

uvicorn main:app --reload

打开浏览器，访问 http://127.0.0.1:8000，你会看到 {"Hello": "World"} 显示在页面上。恭喜你！你已经成功运行了第一个FastAPI应用——快递员正在工作，快速送达了你的消息！

第三步：引入数据库和Alembic

在Web开发中，我们经常需要存储数据，比如用户信息或博客文章。这就是数据库的用武之地——想象它是一个仓库，存放你的物品（数据）。但仓库布局可能需要更新，比如添加新货架。Alembic就是你的仓库管理员，负责这些更新。

首先，我们需要设置数据库模型。创建一个新文件 models.py，定义简单的用户模型：

from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()  # 基础类，用于定义模型

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、姓名和邮箱三个货架。

第四步：配置Alembic

现在，我们来配置Alembic，让它管理数据库迁移。在终端中，运行以下命令初始化Alembic：

alembic init alembic

这会创建一个 alembic 文件夹和 alembic.ini 配置文件。打开 alembic.ini 文件，找到 sqlalchemy.url 行，修改为你的数据库URL。对于初学者，我们可以使用SQLite数据库，它像一个本地文件仓库：

sqlalchemy.url = sqlite:///./test.db

然后，在 alembic/env.py 文件中，导入你的模型并设置 target_metadata。修改文件，添加以下代码：

from models import Base
target_metadata = Base.metadata  # 告诉Alembic跟踪这些模型

保存文件后，运行 alembic current 检查配置，如果看到“No current revision”之类信息，说明配置成功——管理员已经就位！

第五步：使用Alembic进行迁移

迁移就像仓库管理员根据规划更新仓库。首先，我们需要创建迁移脚本。在终端运行：

alembic revision --autogenerate -m "Create users table"

这会生成一个迁移文件在 alembic/versions/ 文件夹中。打开它，你会看到SQL语句，比如创建 users 表。现在，应用这个迁移来更新数据库：

alembic upgrade head

运行后，数据库会被创建或更新，你可以在项目目录中看到 test.db 文件。成功！管理员已经执行了更新，仓库现在有了新货架。

第六步：集成到FastAPI，创建一个简单API

现在，让我们把数据库和FastAPI结合起来，创建一个可以添加和查看用户的API。修改 main.py 文件：

from fastapi import FastAPI, HTTPException
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from models import Base, User

# 创建数据库引擎和会话，就像打开仓库门
DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# 确保数据库表存在
Base.metadata.create_all(bind=engine)

app = FastAPI()

@app.post("/users/")  # 定义一个POST路由来添加用户
def create_user(name: str, email: str):
    db = SessionLocal()
    new_user = User(name=name, email=email)
    db.add(new_user)  # 将新用户添加到仓库
    db.commit()  # 确认更新
    db.refresh(new_user)
    return new_user  # 返回创建的用户

@app.get("/users/{user_id}")  # 定义一个GET路由来查看用户
def read_user(user_id: int):
    db = SessionLocal()
    user = db.query(User).filter(User.id == user_id).first()
    if user is None:
        raise HTTPException(status_code=404, detail="User not found")
    return user

保存文件后，重新运行 uvicorn main:app --reload。现在，你可以使用工具如curl或浏览器扩展测试API。例如，发送一个POST请求到 http://127.0.0.1:8000/users/?name=John&email=john@example.com，然后GET请求到 http://127.0.0.1:8000/users/1 来查看用户。成功时刻！你已经创建了一个能存储和检索数据的Web API。

第七步：更多迁移示例

为了巩固知识，让我们添加一个迁移来更新模型。假设我们想给用户添加年龄字段。首先，更新 models.py：

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)
    age = Column(Integer, nullable=True)  # 新增年龄字段

然后，生成和应用迁移：

alembic revision --autogenerate -m "Add age field to users"
alembic upgrade head

现在，数据库已经更新，你可以修改API来使用新字段。这展示了Alembic的强大——轻松管理仓库变化！

总结

恭喜你完成了这个FastAPI和Alembic入门教程！你学会了：

• 安装和运行FastAPI应用，体验了“Hello World”成功。
• 配置Alembic来管理数据库迁移，用生活化类比理解概念。
• 创建了简单API，集成数据库操作。 通过动手实践，你已经建立了Web开发的信心。记住，FastAPI让API开发快速，Alembic让数据库变更安全。接下来，你可以尝试添加更多功能，比如身份验证或复杂查询。继续探索，享受编程的乐趣！

如果有问题，参考FastAPI官方文档和Alembic文档。祝你学习愉快！