10.3 双向实时通信实现

FastAPI WebSockets 双向实时通信入门教程 - Python初学者快速上手

FastAPI 教程

本教程面向Python初学者，教你如何使用FastAPI的WebSockets实现双向实时通信。通过生活化类比和简单示例，无需Web开发经验，快速上手并建立信心。

FastAPI 双向实时通信实现入门教程

引言：什么是双向实时通信？

想象一下你在用手机和朋友通话：你们可以随时说话和听到对方的声音，这就是双向实时通信。在Web开发中，我们使用WebSockets来实现类似功能。FastAPI是一个现代、快速的Python Web框架，它内置支持WebSockets，让你轻松构建实时应用。本教程将引导你从零开始，用简单的例子实现这个功能。

准备工作：安装必要的工具

在开始之前，确保你已经安装了Python（建议Python 3.7+）。然后，打开终端或命令行，运行以下命令来安装FastAPI和Web服务器uvicorn：

pip install fastapi uvicorn

安装完成后，你就准备好了一切！

生活化类比：把WebSockets当作电话线

想象WebSocket像一条持久的电话线：当你建立连接后，客户端和服务器可以随时发送消息，而不用每次重新拨号（不像传统HTTP请求那样）。这非常适合聊天应用、实时游戏或协作工具。

第一个成功时刻：创建简单的WebSocket服务器

让我们创建一个最简单的WebSocket服务器，你可以在几行代码内看到效果。

创建一个新文件，命名为 main.py，并用文本编辑器打开它。
输入以下代码：

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

app = FastAPI()

# 一个简单的HTML页面作为客户端来测试
html = """
<!DOCTYPE html>
<html>
    <head>
        <title>WebSocket测试</title>
    </head>
    <body>
        <h1>FastAPI WebSocket聊天</h1>
        <form action="" onsubmit="sendMessage(event)">
            <input type="text" id="messageText" autocomplete="off"/>
            <button>发送</button>
        </form>
        <ul id='messages'>
        </ul>
        <script>
            var ws = new WebSocket("ws://localhost:8000/ws");
            ws.onmessage = function(event) {
                var messages = document.getElementById('messages');
                var message = document.createElement('li');
                var content = document.createTextNode(event.data);
                message.appendChild(content);
                messages.appendChild(message);
            };
            function sendMessage(event) {
                var input = document.getElementById("messageText");
                ws.send(input.value);
                input.value = '';
                event.preventDefault();
            }
        </script>
    </body>
</html>
"""

@app.get("/")
async def get():
    return HTMLResponse(html)

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()  # 接受连接
    while True:
        data = await websocket.receive_text()  # 接收客户端消息
        await websocket.send_text(f"服务器回复：{data}")  # 发送回复

保存文件。

运行服务器并测试

回到终端，运行以下命令来启动服务器：

uvicorn main:app --reload

你会看到类似 INFO: Uvicorn running on http://127.0.0.1:8000 的输出。现在，打开浏览器，访问 http://localhost:8000。你会看到一个简单的聊天界面！

成功时刻：在输入框中输入一条消息（比如“Hello”），然后点击发送。你会立即在下方看到服务器回复的“服务器回复：Hello”。恭喜！你刚刚实现了双向实时通信！服务器和浏览器可以实时交换消息。

解释代码：一步步理解

app = FastAPI()：创建一个FastAPI应用实例。
@app.websocket("/ws")：定义一个WebSocket端点，路径为 /ws。这就像告诉服务器：“这里有一个电话线接口”。
await websocket.accept()：接受客户端的连接请求。
websocket.receive_text() 和 websocket.send_text()：接收和发送文本消息。
HTML部分提供了一个简单的Web客户端，用JavaScript的WebSocket API连接到服务器。

更多成功时刻：扩展示例

现在，让我们尝试一个小扩展，让聊天更有趣。

修改 main.py 中的WebSocket端点代码，添加一个计数器来显示消息数：

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    message_count = 0
    while True:
        data = await websocket.receive_text()
        message_count += 1
        await websocket.send_text(f"消息 #{message_count}: 你说: {data}")

保存文件并重新启动服务器（如果使用了 --reload，它会自动重启）。
刷新浏览器页面，再次发送消息。现在你会看到类似“消息 #1: 你说: Hello”的回复。

这展示了如何跟踪状态并在通信中使用它。试试发送多条消息，看看计数器如何递增！

生活化类比回顾

就像在聊天中，你不仅回复对方，还能记住对话历史。WebSocket连接保持打开，让你可以持续交换数据。

总结和下一步

你已成功使用FastAPI实现了双向实时通信！关键点：

WebSockets提供持久连接，适合实时应用。
FastAPI让定义WebSocket端点变得简单。
通过动手实践，你已经建立了信心，能够处理基本通信。

下一步建议：探索更多功能，如处理多个客户端连接、发送JSON数据或集成到实际应用中。FastAPI文档（https://fastapi.tiangolo.com/）是很好的资源。保持实践，享受编码乐趣！

如果你遇到问题，确保代码正确复制，并检查网络连接。祝你学习愉快！

上一章 10.2 WebSocket 端点定义

下一章 10.4 WebSocket 连接管理