10.1 WebSocket 协议基础

Python FastAPI 入门教程：快速上手Web开发，包含WebSocket基础

FastAPI 教程

这是一个面向Python初学者的FastAPI入门教程，从零开始学习构建Web API，包括基础概念、简单示例和WebSocket协议介绍，让您快速上手Web开发。

FastAPI 入门教程：让Python新手轻松构建Web应用

欢迎来到FastAPI入门教程！如果您有Python基础，但对Web开发一无所知，别担心。本教程将带您一步步走进FastAPI的世界，通过动手实践，让您在短时间内建立信心，感受成功的喜悦。就像学习骑自行车一样，我们先从简单的平衡开始，再慢慢加速。

第一章：什么是FastAPI？为什么学习它？

想象一下，您是一家餐厅的服务员，顾客通过菜单点餐（请求），您快速处理并上菜（响应）。FastAPI 就是一个帮助Python程序员快速构建这种“点餐系统”的工具，用于创建Web API（应用程序接口）。

FastAPI 是什么？ 它是一个现代、快速（高性能）的Web框架，用于构建API，基于Python 3.6+。
为什么学习它？ 因为它简单易学、文档清晰、性能出色，还能自动生成交互式API文档，适合新手快速上手。

成功时刻：安装FastAPI后，您将立刻创建一个Hello World API，体验到第一个Web应用的诞生！

第二章：环境设置

在开始之前，确保您已安装Python 3.6或更高版本。然后，打开终端或命令提示符，运行以下命令安装FastAPI和Uvicorn（一个ASGI服务器，用于运行FastAPI应用）。

pip install fastapi uvicorn

就像准备厨房一样，先备好工具。

第三章：第一个FastAPI应用：Hello World

让我们创建一个简单的Hello World应用，感受FastAPI的魅力。创建一个新文件，命名为 main.py，并写入以下代码：

from fastapi import FastAPI

app = FastAPI()  # 创建一个FastAPI应用实例，就像给餐厅起个名字

@app.get("/")  # 定义一个路由，处理GET请求到根路径 "/"，就像在门口放个欢迎牌
def read_root():
    return {"Hello": "World"}  # 返回一个JSON响应，就像说“欢迎光临”

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

uvicorn main:app --reload

main:app 表示从 main.py 文件中导入 app 实例。
--reload 参数让应用在代码更改时自动重载，方便开发。

现在，打开浏览器访问 http://127.0.0.1:8000，您将看到 {"Hello": "World"} 显示在屏幕上！恭喜您，第一个FastAPI应用运行成功了！

生活化类比：这就像开张第一天，顾客（浏览器）来到餐厅（您的应用），您热情地打招呼。

第四章：路由和请求处理

路由是处理不同请求的路径。让我们扩展应用，添加一个新路由处理用户信息。

在 main.py 中添加：

@app.get("/items/{item_id}")  # 定义带路径参数的路由，item_id是变量，就像根据不同桌号提供服务
def read_item(item_id: int):
    return {"item_id": item_id}  # 返回路径参数的值

保存文件，应用会自动重载。现在访问 http://127.0.0.1:8000/items/42，您将看到 {"item_id": 42}。这就是处理动态请求的例子！

第五章：数据验证与请求体

FastAPI 使用 Pydantic 进行数据验证，确保输入正确。让我们添加一个POST请求处理用户提交的数据。

首先，需要安装 Pydantic（FastAPI 通常已依赖它，但确保运行 pip install pydantic）。然后在 main.py 中添加：

from pydantic import BaseModel

# 定义一个数据模型，用于验证请求体
class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
def create_item(item: Item):  # 请求体会自动验证为Item模型
    return item  # 返回提交的数据，就像确认订单

保存后，您可以测试这个API。使用工具如curl或浏览器扩展，发送POST请求到 http://127.0.0.1:8000/items/，带上JSON体如 {"name": "Book", "price": 9.99}。您将看到返回相同数据，验证成功！

成功时刻：现在您不仅能处理GET请求，还能处理POST请求，并确保数据正确性。

第六章：自动API文档

FastAPI 的一个亮点是自动生成交互式API文档。访问 http://127.0.0.1:8000/docs，您会看到一个漂亮的Swagger UI界面，展示了所有路由，并可以测试它们。这就像有一个自助点餐机，顾客可以自己探索菜单。

第七章：引入WebSocket基础

既然您已掌握基础API，让我们看看WebSocket——一种用于实时双向通信的协议。把它想象成餐厅里的对讲机，服务员和厨房可以实时通话，而不必每次请求都重新连接。

在FastAPI中，WebSocket很容易实现。首先，导入WebSocket相关模块。

在 main.py 中添加：

from fastapi import WebSocket

@app.websocket("/ws")  # 定义一个WebSocket路由
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()  # 接受WebSocket连接，就像拿起对讲机
    while True:
        data = await websocket.receive_text()  # 接收客户端发送的消息
        # 处理消息，例如回显
        await websocket.send_text(f"Message received: {data}")  # 发送回显消息

要测试WebSocket，您需要一个客户端。可以使用简单的HTML页面或工具。例如，创建一个HTML文件 websocket_client.html：

<!DOCTYPE html>
<html>
<body>
    <script>
        const ws = new WebSocket("ws://127.0.0.1:8000/ws");
        ws.onopen = () => {
            ws.send("Hello from browser!");  // 发送消息
        };
        ws.onmessage = (event) => {
            console.log(event.data);  // 接收回显消息
        };
    </script>
    <p>打开浏览器控制台查看WebSocket消息。</p>
</body>
</html>

在浏览器中打开这个HTML文件，控制台将显示 Message received: Hello from browser!。这表明WebSocket连接成功并实时通信！

生活化类比：这就像在餐厅里，顾客（浏览器）和服务员（服务器）可以持续聊天，而不必每次都点菜。

第八章：总结与下一步

恭喜！您已经完成了FastAPI的入门之旅，从基础的Hello World到路由、数据验证，甚至引入了WebSocket实时通信。您学到了：

FastAPI 是一个快速构建API的Python框架。
如何设置环境、创建应用和处理请求。
使用数据验证确保输入正确。
通过WebSocket实现实时通信。

动手实践建议：尝试扩展应用，比如添加更多路由、处理数据库，或构建一个简单的聊天应用使用WebSocket。

继续探索FastAPI的官方文档，那里有更多高级功能如依赖注入、中间件等。记住，学习Web开发就像烹饪——从简单菜肴开始，逐步尝试复杂菜式。祝您编程愉快！

快速回顾：本教程引导您一步步构建FastAPI应用，侧重于实践和简单示例，让您在每个阶段都体验成功。如有问题，多动手实验，看看FastAPI的自动文档，它会帮您理解每个细节。

上一章 9.8 数据库连接池配置

下一章 10.2 WebSocket 端点定义