10.7 与前端 WebSocket 客户端通信

FastAPI WebSocket入门教程：与前端实时通信的Python初学者指南

FastAPI 教程

面向Python初学者的FastAPI WebSocket入门教程，无Web开发经验也能快速上手。通过生活化类比和简单示例，教你如何实现与前端WebSocket客户端的实时通信。包含代码实践和成功时刻，建立信心。

FastAPI WebSocket入门教程：与前端WebSocket客户端通信

欢迎来到这个面向Python初学者的FastAPI WebSocket教程！如果你有一些Python基础，但对Web开发一窍不通，别担心——这个教程将带你快速上手，通过简单实践，让你感受到成功的喜悦。我们将聚焦于如何用FastAPI实现与前端WebSocket客户端的实时通信。WebSocket就像打电话一样，让你和前端可以随时双向聊天，而不仅仅是像HTTP那样邮寄信件。

一、什么是WebSocket？一个简单的类比

想象一下：HTTP就像你给朋友寄一封信，你发送请求，然后等待回信，一次只能做一件事。而WebSocket就像是你们俩在打电话——连接一旦建立，你们可以随时说话和听对方说话，实现实时互动。在Web开发中，WebSocket常用于聊天应用、游戏更新或实时数据流。

二、前提条件：准备好你的Python环境

在开始之前，确保你安装了Python 3.7或更高版本。如果你还没有，可以下载Python。同时，打开你的终端（或命令提示符），我们将使用pip来安装必要的包。

三、快速上手：5分钟内创建你的第一个WebSocket服务器

让我们立即动手，跳过理论，直接体验成功时刻！

步骤1：安装FastAPI和Uvicorn

首先，创建一个虚拟环境来管理依赖（可选，但推荐）。然后，运行以下命令来安装FastAPI和Uvicorn（一个快速ASGI服务器）：

pip install fastapi uvicorn websockets

步骤2：创建一个简单的Python脚本

创建一个新文件，命名为main.py，并写入以下代码。这段代码定义了一个基本的FastAPI应用，并添加了一个WebSocket端点。

from fastapi import FastAPI, WebSocket
from fastapi.responses import HTMLResponse
import asyncio

app = FastAPI()  # 创建一个FastAPI应用实例，就像建立一个网站的基础框架

# 提供一个简单的HTML页面作为前端测试，让初学者能看到效果
html = """
<!DOCTYPE html>
<html>
    <head>
        <title>WebSocket Test</title>
    </head>
    <body>
        <h1>FastAPI WebSocket测试</h1>
        <p>打开浏览器控制台（按F12），看看WebSocket消息！</p>
        <script>
            let ws = new WebSocket("ws://localhost:8000/ws");  // 连接到我们的WebSocket端点
            ws.onopen = function(event) {
                console.log("WebSocket连接成功！");
                ws.send("Hello, FastAPI!");  // 发送一条消息
            };
            ws.onmessage = function(event) {
                console.log("从服务器收到消息: " + event.data);
            };
            ws.onerror = function(error) {
                console.error("WebSocket错误: ", error);
            };
        </script>
    </body>
</html>
"""

@app.get("/")  # 定义HTTP GET端点，用于访问HTML页面
async def get():
    return HTMLResponse(html)  # 返回HTML页面，让用户可以直接在浏览器中测试

@app.websocket("/ws")  # 定义一个WebSocket端点，路径为/ws，就像设置一个聊天室入口
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()  # 接受WebSocket连接，就像接起电话
    print("WebSocket客户端已连接！")  # 服务器端打印，确认成功连接
    await websocket.send_text("欢迎来到FastAPI WebSocket！")  # 发送一条欢迎消息给客户端
    while True:
        data = await websocket.receive_text()  # 接收客户端发送的消息
        print(f"收到消息: {data}")  # 服务器端打印收到的消息
        # 回显消息给客户端，就像在电话中重复对方的话，让用户立即看到效果
        await websocket.send_text(f"服务器回显: {data}")

步骤3：运行你的WebSocket服务器

在终端中，导航到包含main.py的目录，并运行以下命令启动服务器：

uvicorn main:app --reload

main:app 指的是从main.py文件中导入app实例。
--reload 参数让服务器在代码更改时自动重启，方便调试。

你应该会看到类似这样的输出，表示服务器正在运行：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

成功时刻！ 你现在已经运行了一个FastAPI WebSocket服务器！

步骤4：测试WebSocket通信

打开浏览器，访问 http://localhost:8000。你会看到一个简单的HTML页面。
按F12打开浏览器的开发者工具，切换到控制台（Console）选项卡。
在控制台中，你应该看到消息："WebSocket连接成功！" 和 "从服务器收到消息: 欢迎来到FastAPI WebSocket！"。
服务器端（在终端中）也会打印："WebSocket客户端已连接！" 和 "收到消息: Hello, FastAPI!"。

哇，太棒了！你已经成功实现了与前端WebSocket客户端的通信。每一次连接和消息交换都是一个"成功时刻"，帮助你建立信心。

四、深入理解：WebSocket基本概念

让我们稍微深入一点，但保持简单。WebSocket的核心是：

连接：通过websocket.accept()建立连接，就像拨通电话。
发送消息：使用websocket.send_text()发送文本消息，你可以说这是服务器主动"说话"。
接收消息：使用websocket.receive_text()接收消息，监听客户端的"说话"。
关闭连接：通常通过循环持续监听，直到连接中断，但在这个示例中，我们保持连接活跃以演示实时性。

五、更多成功时刻示例

为了巩固信心，这里有几个简单示例，让你可以修改main.py并立即看到效果。

示例1：发送计数消息

修改WebSocket端点，每秒发送一个计数消息给客户端，就像在聊天中自动更新。

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    count = 0
    while True:
        count += 1
        await websocket.send_text(f"这是第 {count} 条消息")
        await asyncio.sleep(1)  # 等待1秒，模拟实时更新
        data = await websocket.receive_text()
        print(f"收到: {data}")

运行后，在浏览器中，控制台会每秒显示新的计数消息。这是一个简单的"实时"体验。

示例2：处理多个客户端

FastAPI使用异步处理，可以同时处理多个WebSocket连接，就像一部电话可以接多个来电。在真实应用中，你可能需要管理用户会话，但这超出了初学者范围。我们只需知道，这个结构天生支持并发。

示例3：与JavaScript前端深入互动

在HTML中，我们可以添加更多交互。例如，修改<script>部分，让用户可以输入消息并发送。

<script>
    let ws = new WebSocket("ws://localhost:8000/ws");
    ws.onopen = function(event) {
        console.log("连接成功！");
    };
    ws.onmessage = function(event) {
        console.log("服务器说: " + event.data);
        document.getElementById("output").innerHTML += "<p>" + event.data + "</p>";
    };
    function sendMessage() {
        let input = document.getElementById("message").value;
        ws.send(input);
        document.getElementById("message").value = "";  // 清空输入框
    }
</script>
<body>
    <input type="text" id="message" placeholder="输入消息">
    <button onclick="sendMessage()">发送</button>
    <div id="output"></div>
</body>

这个修改让你可以在页面上输入消息并实时看到回显，真正感受到WebSocket的双向通信。

六、总结与下一步

恭喜你！通过这个教程，你已经学会了：

用FastAPI创建WebSocket端点，实现与前端实时通信。
通过简单类比和动手实践，理解了WebSocket的基本原理。
体验了多个成功时刻，从安装到运行，再到交互，建立了Web开发的信心。

下一步建议：尝试创建一个简单的聊天应用，或者集成其他功能如数据库查询。记住，FastAPI文档是很好的资源，但专注于实践会更快进步。

常见问题

Q: 如果服务器停了怎么办？ A: WebSocket连接会断开，就像电话挂断。重新运行uvicorn命令即可恢复。
Q: 如何部署到真实服务器？ A: 初学者可以先在本地练习，后续再学习部署到云服务如Heroku或AWS。

保持实践，享受编码的乐趣！如果你有任何问题，欢迎进一步探索FastAPI官方文档或社区。

上一章 10.6 WebSocket 认证与安全

下一章 11.1 小型项目结构（单一文件）