FastAPI 异步路径操作入门教程：Python 初学者的轻松指南

欢迎来到 FastAPI 世界！

嘿，如果你是 Python 新手，但想尝试 Web 开发，那么你找对地方了！FastAPI 是一个现代、快速的 Web 框架，它让构建 API 变得超级简单。今天，我们将专注于异步路径操作，听起来有点高级，但别担心——我会用简单的方式解释，保证你很快就能上手！

目标：学完本教程后，你将能创建一个简单的异步 FastAPI 应用，并体验到“我做到了！”的成功时刻。

类比：想象异步就像在餐厅点菜。传统方式（同步）中，服务员一次只服务一桌，点菜-上菜-结账，完成后再去下一桌。而异步方式，服务员可以同时处理多桌，比如点完菜后，在你等待时去服务其他桌，这样大家都不用干等。在 FastAPI 中，异步路径操作就是让你同时处理多个请求，提高效率，而不会卡住整个应用。

准备工作

确保你安装了 Python（建议 3.7+）。如果还没有，去 python.org 下载安装。

在终端或命令行中，运行以下命令安装所需包：

pip install fastapi uvicorn

• fastapi: 我们的主角框架。
• uvicorn: 一个轻量级的服务器，用来运行 FastAPI 应用。

第一部分：你的第一个 FastAPI 应用（同步版）

让我们从简单的开始，先建一个同步应用热热身。这有助于建立信心，理解基本结构。

1. 创建一个新文件：比如叫 main.py，用你喜欢的代码编辑器打开它。

2. 编写代码：复制以下代码到 main.py。

from fastapi import FastAPI

app = FastAPI()  # 创建一个 FastAPI 实例，就像开一个新店

# 定义一个路径操作。路径是根路径 "/"，操作是 GET 请求
@app.get("/")
def read_root():
    return {"message": "Hello, World!"}  # 返回一个简单的 JSON 响应

# 另一个路径操作
@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id, "message": "Item details"}

解释：

• app = FastAPI(): 创建一个应用实例。
• @app.get("/"): 这是一个装饰器，告诉 FastAPI 当有人访问根路径时，调用下面的函数。
• 函数 read_root(): 返回一个字典，FastAPI 会自动转换成 JSON 响应。

3. 运行应用：在终端中，导航到文件所在目录，运行：

uvicorn main:app --reload

• main: 指的是你的文件名（不带 .py 扩展名）。
• app: 指的是 app = FastAPI() 中的变量名。
• --reload: 自动重载，修改代码后服务器会刷新，方便调试。

4. 成功时刻！：打开浏览器，访问 http://127.0.0.1:8000。你会看到 {"message": "Hello, World!"} 显示出来！🎉 试试访问 http://127.0.0.1:8000/items/42，它会动态显示 {"item_id": 42, "message": "Item details"}。

哇，你已经创建了一个 Web API！是不是感觉很简单？

第二部分：引入异步路径操作

现在，我们升级到异步版本。在 FastAPI 中，异步路径操作就是用 async 关键字来定义函数。这会让你的应用在等待外部资源（比如数据库查询、网络请求）时，不阻塞其他请求。

回顾类比：就像服务员处理多桌一样，异步操作允许服务器同时处理多个请求，而不是一个接一个地处理。

1. 修改同步应用为异步：在 main.py 中，修改代码。

首先，保留之前的同步版本做对比，但我们可以新建异步路径。让我们添加一个异步函数。

from fastapi import FastAPI
import asyncio  # Python 的异步模块，用于模拟延迟

app = FastAPI()

# 原来的同步路径操作（可保留）
@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

# 新的异步路径操作
@app.get("/async-hello")
async def async_hello():
    # 模拟等待某个任务，比如读取数据库或 API 调用
    await asyncio.sleep(2)  # 等待 2 秒，但不会阻塞服务器
    return {"message": "Async Hello after waiting 2 seconds!"}

解释：

• async def async_hello(): 使用 async 关键字定义异步函数。
• await asyncio.sleep(2): await 表示“等待这个异步操作完成”，asyncio.sleep(2) 模拟一个耗时 2 秒的操作。关键是，在等待期间，FastAPI 可以处理其他请求，而不会卡住整个应用。

2. 运行并测试：保持 uvicorn main:app --reload 运行。打开浏览器，访问 http://127.0.0.1:8000/async-hello。

• 访问时，你会注意到页面加载后需要大约 2 秒才显示消息。但关键是，在此期间，你可以在新标签页中访问 http://127.0.0.1:8000/ 或 http://127.0.0.1:8000/items/1，它们会立即响应！这就是异步的魔力。

成功时刻！：在浏览器中同时打开多个标签访问不同路径，观察非阻塞行为。看到同步路径立即响应，异步路径等待时不影响其他请求，这就是成功！🌟

第三部分：理解核心概念

为了加深理解，让我们回顾一下：

• 同步操作：一次处理一个请求，完成后再处理下一个。简单，但可能慢。
• 异步操作：可以同时处理多个请求，当某个请求需要等待时，服务器去处理其他请求，提高效率。

类比扩展：想象你在图书馆借书。同步是排长队，一个一个借。异步是多个工作人员，有人借书时，如果有人卡住（比如查资料），工作人员可以先去服务其他人。

在 FastAPI 中，使用 async 和 await 来编写异步代码。大部分时候，FastAPI 会自动处理异步，你只需定义函数。

第四部分：更多示例和动手实践

让我们再做一个例子，模拟从外部 API 获取数据（常见异步用例）。

1. 添加新路径操作：在 main.py 中，继续添加。

首先，安装一个包来模拟 HTTP 请求（实战中常用）：

pip install httpx

然后，更新代码：

from fastapi import FastAPI
import httpx

app = FastAPI()

@app.get("/fetch-data")
async def fetch_data():
    # 模拟调用外部 API
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.github.com")
        return {"status": response.status_code, "data": "Data fetched successfully!"}

解释：

• 使用 httpx 库进行异步 HTTP 请求。
• async with httpx.AsyncClient() as client: 创建一个异步 HTTP 客户端。
• await client.get(...): 等待获取数据，期间服务器可处理其他请求。

2. 运行并测试：保持服务器运行，访问 http://127.0.0.1:8000/fetch-data。你会看到返回了 GitHub API 的状态码和消息。同时，其他路径如 / 仍可快速访问。

总结与下一步

恭喜！你已经掌握了 FastAPI 中的异步路径操作基础。通过简单步骤，你：

1. 创建了同步和异步的 Web API。
2. 体验了异步非阻塞的优势。
3. 使用了生活化类比来理解概念。

关键点：

• 使用 async def 定义异步函数。
• 用 await 调用其他异步操作。
• FastAPI 自动优化，即使有异步代码，也保持简单。

进一步学习：

• 探索更多路径操作（POST, PUT, DELETE 等）。
• 添加参数和验证（FastAPI 的强大之处）。
• 查看官方文档：https://fastapi.tiangolo.com/async/

记住，Web 开发并不难——从这些小步骤开始，逐渐构建复杂应用。祝你学习愉快！

如果你有任何问题或需要更多帮助，欢迎搜索 FastAPI 社区或教程。动手实践是最好的学习方式，保持编码的热情！🚀