10.1 WebSocket 协议基础
FastAPI教程：WebSocket协议基础入门与实战
本教程详细讲解WebSocket协议基础，包括工作原理、与HTTP对比，并指导如何在FastAPI中实现WebSocket以实现实时双向通信，适合新人学习，配有代码示例和简单易懂的解释。
WebSocket 协议基础：在 FastAPI 中实现实时通信
引言
WebSocket 是一种在现代 Web 应用中常用的通信协议，它允许服务器和客户端之间建立持久连接，实现低延迟、双向的实时数据交换。对于需要即时更新（如聊天应用、实时游戏、股票报价等）的场景，WebSocket 提供了比传统 HTTP 轮询更高效的解决方案。
FastAPI 是一个高性能的 Python Web 框架，内置了对 WebSocket 的支持，让开发者可以轻松构建实时功能。本教程将从基础概念入手，帮助新人理解 WebSocket 协议，并学会在 FastAPI 中使用它。
什么是 WebSocket？
WebSocket 是一个独立的 TCP 协议，定义在 RFC 6455 中。它通过一个初始的 HTTP 握手升级到 WebSocket 连接，之后在同一个 TCP 连接上进行全双工通信。这意味着客户端和服务器可以随时相互发送数据，而不需要像 HTTP 那样每次请求-响应都需要重新建立连接。
关键特点：
- 持久连接：一旦建立，连接保持打开状态，直到显式关闭。
- 双向通信：服务器和客户端都可以主动发送消息。
- 低开销：减少了 HTTP 的头信息和延迟，适合高频数据传输。
WebSocket 与 HTTP 对比
为了更好地理解 WebSocket，我们来对比一下它与 HTTP 的区别：
| 特性 | HTTP | WebSocket |
|---|---|---|
| 连接类型 | 无状态，每次请求独立 | 持久连接，双向通信 |
| 数据交换 | 请求-响应模式，服务器不能主动推送 | 服务器和客户端都可以主动发送消息 |
| 延迟 | 较高，每次需要握手 | 较低，连接后直接通信 |
| 用例 | 网页加载、API 调用 | 实时聊天、游戏、通知推送 |
HTTP 主要用于单向数据获取（例如加载网页），而 WebSocket 专为实时交互设计。
WebSocket 协议基础
握手过程
WebSocket 连接以 HTTP 请求开始：客户端发送一个升级请求到服务器，如果服务器支持 WebSocket，它会响应一个 101 状态码，切换协议到 WebSocket。握手后，连接升级到 WebSocket 协议，使用二进制或文本帧传输数据。
这个过程是自动处理的，在 FastAPI 中，您不需要手动实现握手——框架会为您处理。
数据传输
连接建立后，数据以帧（Frame）的形式传输。帧可以是文本（如 JSON）或二进制数据。帧很小，开销低，支持高效传输。
连接生命周期
WebSocket 连接可以通过关闭帧来终止，也可以通过超时或错误来中断。在开发中，需要处理连接、消息接收和关闭事件。
在 FastAPI 中使用 WebSocket
FastAPI 提供了 WebSocket 类来简化 WebSocket 实现。您需要创建一个 WebSocket 路由来处理连接。
安装和设置
首先，确保安装了 FastAPI 和 Uvicorn（ASGI 服务器）：
pip install fastapi uvicorn
创建 WebSocket 路由
在 FastAPI 应用中，您可以使用 @app.websocket() 装饰器定义一个 WebSocket 端点。
示例代码：创建一个简单的 WebSocket 聊天服务器
from fastapi import FastAPI, WebSocket
from fastapi.responses import HTMLResponse
app = FastAPI()
# 提供一个简单的 HTML 客户端界面
html = """
<!DOCTYPE html>
<html>
<head>
<title>WebSocket Chat</title>
</head>
<body>
<h1>WebSocket Chat</h1>
<form action="" onsubmit="sendMessage(event)">
<input type="text" id="messageText" autocomplete="off"/>
<button>Send</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):
# 接受 WebSocket 连接
await websocket.accept()
try:
while True:
# 接收消息
data = await websocket.receive_text()
# 回显消息给客户端
await websocket.send_text(f"Message text was: {data}")
except Exception as e:
# 处理连接关闭或错误
print(f"WebSocket error: {e}")
finally:
await websocket.close()
代码解释
- HTML 客户端：提供了一个简单的网页，使用 JavaScript WebSocket API 连接到服务器。
- WebSocket 路由：
@app.websocket("/ws")定义了一个 WebSocket 端点，路径为/ws。 - 连接处理：
await websocket.accept()接受连接，然后进入循环接收消息。 - 消息收发：
await websocket.receive_text()接收文本消息，await websocket.send_text()发送回响应。 - 错误处理：使用 try-except 捕获异常，确保连接正确关闭。
运行服务器：
uvicorn main:app --reload
然后打开浏览器访问 http://localhost:8000/，就可以测试聊天功能了。
进阶话题
一旦掌握基础，您可以探索更多：
- 认证：在 WebSocket 握手时验证用户身份，例如使用 JWT 令牌。
- 多个客户端管理：使用列表或字典跟踪连接的 WebSocket 实例，实现广播消息。
- 二进制数据：处理二进制帧，适合传输图像或文件。
- 错误处理：添加更健壮的错误恢复机制。
- 集成其他功能：结合 FastAPI 的依赖注入、背景任务等。
总结
WebSocket 协议是构建实时 Web 应用的关键技术，它通过持久双向连接优化了数据传输。FastAPI 使得实现 WebSocket 变得简单高效，只需几行代码就能启动一个实时服务器。作为新人，从基础协议理解开始，逐步实践，您将能快速掌握在 FastAPI 中使用 WebSocket 的技能。
推荐下一步学习：深入 FastAPI 文档，探索更多高级功能，如 WebSocket 与数据库交互或部署到生产环境。祝您学习愉快！