FastAPI 入门教程：Python 初学者的 Web 开发之路

欢迎来到 FastAPI 入门教程！如果你已经掌握了 Python 基础语法，但还没有接触过 Web 开发，那么这个教程就是为你准备的。我们将通过动手实践，避免复杂理论，用生活化的类比帮助你快速上手。

什么是 FastAPI？

想象一下，Web 开发就像开一家餐厅。FastAPI 是你的高效厨师，能快速响应客人（用户）的请求。它比传统方法（如 Flask 或 Django）更快，就像用微波炉加热食物一样迅速。FastAPI 是一个现代 Web 框架，专为构建 API（应用程序接口）而设计，非常适合初学者入门。

成功时刻：在几分钟内，你就能创建自己的第一个 Web 应用，并看到它在浏览器中运行！

设置环境：安装 FastAPI

首先，确保你已经安装了 Python。如果没有，去 Python 官网 下载并安装。

打开你的终端或命令提示符，运行以下命令安装 FastAPI 和一个 ASGI 服务器（如 Uvicorn）。ASGI 服务器就像一个服务员，负责把你的应用端给客人。

pip install fastapi uvicorn

如果安装成功，你会看到类似“Successfully installed”的信息。这是你的第一个成功时刻：环境准备就绪！

创建第一个 FastAPI 应用：Hello World

让我们开始动手吧。创建一个新文件，命名为 main.py。用任何文本编辑器打开它（比如记事本或 VS Code），并输入以下代码：

from fastapi import FastAPI

app = FastAPI()  # 创建一个 FastAPI 实例，就像是开张你的餐厅

@app.get("/")  # 装饰器：定义一个处理 GET 请求的路径，像是设置一个菜单项
async def read_root():
    return {"message": "Hello, World!"}  # 当访问根路径时，返回这个 JSON 响应

生活化类比：@app.get("/") 就像是餐厅里挂出一个招牌，写着“欢迎光临”，客人访问时，你就回应“你好，世界！”。

运行你的应用

在终端中，导航到 main.py 所在的目录，然后运行：

uvicorn main:app --reload

• main:app 告诉服务器从 main.py 文件中的 app 实例启动。
• --reload 参数启用自动重载，当代码更改时服务器会自动重启，方便调试。

你会看到类似 Uvicorn running on http://127.0.0.1:8000 的输出。打开浏览器，访问 http://127.0.0.1:8000，你应该看到 JSON 消息：{"message": "Hello, World!"}。

成功时刻：你的第一个 FastAPI 应用运行起来了！这就像是餐厅开门迎客，第一个客人说“你好”时，你成功回应了。

添加更多功能：路径参数和查询参数

现在，让我们让餐厅更有互动性。在 main.py 中添加更多代码：

@app.get("/items/{item_id}")  # 路径参数：item_id 是一个变量，像是菜单上的特定菜品编号
async def read_item(item_id: int, q: str = None):  # 查询参数：q 是可选的，像是客人点菜时的特殊要求
    if q:
        return {"item_id": item_id, "query": q}
    else:
        return {"item_id": item_id}

解释：

• 路径 "/items/{item_id}" 允许你通过 URL 传递 item_id，例如访问 http://127.0.0.1:8000/items/5 会返回 {"item_id": 5}。
• 查询参数 q 可以通过 URL 如 http://127.0.0.1:8000/items/5?q=test 传递，返回 {"item_id": 5, "query": "test"}。

重启服务器（如果用了 --reload，它会自动更新），在浏览器中测试这些 URL。

成功时刻：现在你的应用能处理不同的请求，像是餐厅能根据客人点单提供不同菜品。

处理数据：使用 Pydantic 模型

为了让点餐更规范，FastAPI 使用 Pydantic 来定义数据模型。在 main.py 中添加：

from pydantic import BaseModel  # 导入 Pydantic
from typing import Optional

class Item(BaseModel):  # 定义一个数据模型，就像是餐厅的菜单模板
    name: str
    price: float
    is_offer: Optional[bool] = None  # 可选字段，像是菜品是否有促销

@app.post("/items/")
async def create_item(item: Item):  # 使用模型接收数据
    return item  # 返回接收到的数据，像是确认点单

现在，你需要一个工具来测试 POST 请求。可以使用 Postman 或浏览器扩展。发送一个 POST 请求到 http://127.0.0.1:8000/items/，Body 为 JSON：{"name": "Burger", "price": 5.99, "is_offer": true}。你会收到同样的 JSON 响应。

成功时刻：你的应用现在能接收和验证数据，就像是餐厅有了标准点单系统，确保客人信息准确。

创建一个简单项目：待办事项 API

让我们整合所学，构建一个简单的待办事项 API。在 main.py 中更新代码：

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List, Optional

app = FastAPI()

# 定义一个待办事项模型
class TodoItem(BaseModel):
    id: int
    title: str
    completed: bool = False

# 模拟数据库：使用一个列表
fake_db = []

@app.get("/todos", response_model=List[TodoItem])  # 返回待办事项列表
async def read_todos():
    return fake_db

@app.post("/todos", response_model=TodoItem)  # 创建新待办事项
async def create_todo(todo: TodoItem):
    fake_db.append(todo)
    return todo

@app.get("/todos/{todo_id}", response_model=TodoItem)  # 获取特定待办事项
async def read_todo(todo_id: int):
    for todo in fake_db:
        if todo.id == todo_id:
            return todo
    return {"error": "Todo not found"}

测试这个 API：

• GET http://127.0.0.1:8000/todos：返回空列表 []。
• POST http://127.0.0.1:8000/todos 并发送 JSON {"id": 1, "title": "Learn FastAPI", "completed": false}：返回创建的项目。
• GET http://127.0.0.1:8000/todos/1：返回刚创建的项目。

成功时刻：你刚刚构建了一个完整的 CRUD（创建、读取）API！就像是餐厅有了完整的点单和查询系统。

总结和下一步

恭喜你！通过这个教程，你已经掌握了 FastAPI 的基础：

• 设置环境和创建应用。
• 处理 GET 和 POST 请求。
• 使用路径参数和查询参数。
• 定义数据模型并验证输入。
• 构建一个简单的待办事项 API。

建立信心：每一步都有可运行的示例，让你亲身体验 Web 开发的乐趣。如果你遇到问题，FastAPI 有优秀的文档和社区支持。

展望未来：现在你已经入门，可以探索更多高级主题，比如集成数据库（如 SQLite 或 PostgreSQL）和外部服务。例如，学习如何使用 SQLAlchemy 连接数据库，或者添加身份验证功能。这就像是扩展餐厅，加入库存管理系统或在线预订服务。

记住，实践是最好的老师。继续修改代码，尝试添加删除和更新功能，或者构建你自己的小项目。祝你学习愉快！