FastAPI 入门教程：Python 初学者的轻松之旅

简介：为什么学习 FastAPI？

想象一下，您想在咖啡店里点一杯咖啡。咖啡店的菜单（API 端点）告诉您有哪些饮料（数据）可用，而您填写的订单表单（模型）确保您点的是正确的咖啡类型和大小。FastAPI 就像一个超级高效的咖啡店系统，让您轻松创建和管理这些菜单和表单！

FastAPI 是一个现代、快速的 Web 框架，用 Python 编写，用于构建 API。即使您没有 Web 开发经验，也能快速入门。本教程将带您一步步动手实践，避免过多理论，让您在每个阶段都体验到“成功时刻”！

第一步：安装 FastAPI

在开始之前，您需要安装 FastAPI 和一个 ASGI 服务器（如 Uvicorn），来运行您的应用。打开终端或命令行，输入以下命令：

pip install fastapi uvicorn

安装完成后，您就可以开始编写代码了！

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

让我们从一个最简单的例子开始，就像第一次学习加法一样——既简单又有成就感！

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

from fastapi import FastAPI

app = FastAPI()  # 创建一个 FastAPI 应用实例，就像是开设一家新咖啡店

@app.get("/")  # 定义一个 GET 端点，就像在咖啡店菜单上添加一个“欢迎光临”选项
def read_root():
    return {"message": "欢迎使用 FastAPI！您的第一个 API 已成功运行！"}

现在，在终端运行这个应用：

uvicorn main:app --reload

访问 http://127.0.0.1:8000 在浏览器中，您会看到 JSON 响应 {"message": "欢迎使用 FastAPI！您的第一个 API 已成功运行！"}。恭喜！您已经创建了第一个 API——这就是您的“成功时刻”！

第三步：理解模型定义与字段类型

在 FastAPI 中，我们使用 Pydantic 来定义模型。模型就像是咖啡店的订单表单，确保客户点的是有效的咖啡（例如，不能点“巧克力味的披萨”）。字段类型指定了表单中每个部分应该是什么类型的数据（例如，名字是文本，年龄是数字）。

生活化类比

• 模型（Model）：想象成您填写的外卖订单单子。单子有固定的格式，比如必须填写姓名、电话号码、订单项。如果您填写了无效的信息（比如把电话号码写成了字母），系统会提示您错误。

• 字段类型（Field Types）：订单单子上的每个字段都有特定类型。例如，姓名字段是字符串（str），电话号码是整数或字符串（int 或 str），订单数量是整数（int）。这确保了数据的一致性。

动手实践：定义一个简单模型

在 main.py 中，添加以下代码来定义一个用户模型：

from pydantic import BaseModel  # 导入 BaseModel 来创建模型

class User(BaseModel):  # 定义一个用户模型，就像设计订单单子
    name: str  # 名字字段，必须是字符串——就像订单上的姓名必须是文本
    age: int   # 年龄字段，必须是整数——就像订单数量必须是数字
    email: str  # 邮箱字段，必须是字符串，但稍后我们可以添加更复杂的验证

现在，让我们使用这个模型来创建一个 POST 端点，接收用户数据：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    age: int
    email: str

@app.post("/users/")
def create_user(user: User):  # FastAPI 会自动验证输入数据是否符合 User 模型
    # 这里我们只是返回接收到的数据，让您看到验证成功
    return {"message": "用户创建成功！", "user": user}

运行应用（如果已经在运行，保存文件后会自动重载），然后使用一个工具如 curl 或浏览器扩展（如 Postman）来测试。例如，用 curl 发送一个 POST 请求：

curl -X POST "http://127.0.0.1:8000/users/" -H "Content-Type: application/json" -d '{"name": "小明", "age": 25, "email": "xiaoming@example.com"}'

您应该会收到响应：{"message": "用户创建成功！", "user": {"name": "小明", "age": 25, "email": "xiaoming@example.com"}}。如果输入错误，比如 age 写为字符串，FastAPI 会自动返回错误——这就是模型的强大之处！

更多字段类型示例

Pydantic 支持多种字段类型，让您的模型更强大。让我们扩展 User 模型：

from pydantic import BaseModel, EmailStr  # 导入 EmailStr 用于邮箱验证
from typing import Optional  # 导入 Optional 用于可选字段

class EnhancedUser(BaseModel):
    name: str  # 必须的字符串字段
    age: int   # 必须的整数字段
    email: EmailStr  # 邮箱字段，Pydantic 会自动验证邮箱格式
    phone: Optional[str] = None  # 可选字段，如果未提供则为 None，就像订单上的备注是可选的
    is_active: bool = True  # 布尔字段，默认值为 True，就像默认订单状态是有效的

现在，创建一个新的端点来测试这个模型：

@app.post("/enhanced-users/")
def create_enhanced_user(user: EnhancedUser):
    return {"message": "增强用户创建成功！", "user": user}

测试时，尝试发送不同数据，看看验证如何工作。例如，发送无效邮箱会返回错误——这又让您体验了一个“成功时刻”，因为系统帮您捕获了问题！

第四步：更多“成功时刻”示例

为了巩固信心，让我们快速添加几个简单示例：

示例1：获取所有用户（模拟数据）

users_db = []  # 一个简单的内存列表来存储用户数据

@app.get("/users/")
def read_users():
    return {"users": users_db}

@app.post("/users/")
def create_user(user: User):
    users_db.append(user)  # 将新用户添加到列表
    return {"message": "用户已添加！", "user": user}

现在，您可以先通过 POST 添加用户，然后通过 GET 查看所有用户——就像是咖啡店记录订单！

示例2：更新用户信息

from fastapi import HTTPException

@app.put("/users/{user_id}")  # {user_id} 是路径参数，就像指定订单号
def update_user(user_id: int, updated_user: User):
    if user_id >= len(users_db):
        raise HTTPException(status_code=404, detail="用户未找到")
    users_db[user_id] = updated_user
    return {"message": f"用户 ID {user_id} 更新成功！", "user": updated_user}

测试时，使用 PUT 请求更新特定用户。这展示了 FastAPI 如何处理路径参数和模型验证。

总结和下一步

恭喜您完成了 FastAPI 的入门之旅！您已经学会了：

• 安装 FastAPI 并运行一个简单应用。
• 使用 Pydantic 定义模型和字段类型，确保数据有效性。
• 创建多个 API 端点，体验了 GET、POST、PUT 操作。

通过生活化类比和动手实践，您应该对 FastAPI 有了基本信心。记住，就像学做咖啡一样，多加练习会让您更熟练！

下一步建议：

• 探索 FastAPI 官方文档（有交互式示例）。
• 尝试添加删除功能（DELETE 端点）。
• 学习如何集成数据库，如 SQLite 或 PostgreSQL。

继续编码，享受创造的乐趣！