FastAPI WebSocket：你的双向通信通道为何如此丝滑？

扫描二维码

关注或者微信搜一搜：编程智域前端至全栈交流与成长

发现1000+提升效率与开发的AI工具和实用程序：https://tools.cmdragon.cn/

# 示例代码运行环境

# Python 3.8+

# 安装依赖：pip install fastapi==0.68.0 uvicorn==0.15.0 websockets==10.3 pydantic==1.10.7

一、WebSocket路由声明规范

1.1 基础路由定义

使用@app.websocket装饰器声明WebSocket路由：

from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws/chat/{room_id}")

async def websocket_chat(websocket: WebSocket, room_id: int):

    await websocket.accept()

    try:

        while True:

            data = await websocket.receive_text()

            await websocket.send_text(f"Room {room_id}: {data}")

    except WebSocketDisconnect:

        print("Client disconnected")

关键要点解析：

路径参数通过URL直接传递（如{room_id}）
WebSocket对象自动注入到路由函数
必须显式调用await websocket.accept()建立连接
receive_text()和send_text()实现双向通信

1.2 路由参数验证

结合路径参数与查询参数进行复合验证：

from fastapi import Query, WebSocket

@app.websocket("/ws/secure/{client_id}")

async def secure_ws(

        websocket: WebSocket,

        client_id: int = Path(..., gt=0),

        token: str = Query(..., min_length=8)

):

    if not validate_token(token):

        await websocket.close(code=1008)

        return

    # ...连接处理逻辑...

二、客户端连接建立与握手验证

2.1 握手过程控制

自定义握手验证流程：

@app.websocket("/ws/auth")

async def auth_ws(websocket: WebSocket):

    # 手动控制握手过程

    await websocket.accept()

    # 获取握手时的请求头

    headers = websocket.headers

    auth_token = headers.get("authorization")

    if not verify_jwt_token(auth_token):

        await websocket.close(code=1008, reason="Invalid credentials")

        return

    # 验证通过后的处理逻辑

2.2 验证失败处理模式

graph TD
A[客户端请求连接] --> B{验证Headers}
B -- 成功 --> C[返回101状态码]
B -- 失败 --> D[返回403状态码]
C --> E[建立双向通信]
D --> F[关闭TCP连接]

三、连接状态维护与生命周期管理

3.1 连接状态跟踪

使用字典维护活跃连接：

from typing import Dict

active_connections: Dict[str, WebSocket] = {}

@app.websocket("/ws/status")

async def status_ws(websocket: WebSocket):

    await websocket.accept()

    client_id = str(websocket.client)

    active_connections[client_id] = websocket

    try:

        while True:

            # 保持连接活跃

            await websocket.receive_text()

    except WebSocketDisconnect:

        del active_connections[client_id]

3.2 心跳检测机制

import asyncio

async def heartbeat(websocket: WebSocket, interval: int = 30):

    try:

        while True:

            await asyncio.sleep(interval)

            await websocket.send_json({

                "type": "heartbeat",

                "timestamp": time.time()

            })

    except WebSocketDisconnect:

        print("Heartbeat terminated")

@app.websocket("/ws/realtime")

async def realtime_ws(websocket: WebSocket):

    await websocket.accept()

    # 启动独立心跳任务

    heartbeat_task = asyncio.create_task(heartbeat(websocket))

    try:

        # 主消息处理循环

        while True:

            data = await websocket.receive_json()

            # 处理业务逻辑...

    finally:

        heartbeat_task.cancel()

        await websocket.close()

课后 Quiz

当客户端发送非文本格式数据时如何处理？

# 正确处理方法

try:

    data = await websocket.receive_json()

except WebSocketDisconnect:

# 处理断开逻辑

except ValueError:

    await websocket.send_text("ERROR: 仅支持JSON格式")

# 错误处理方法：直接使用未校验的receive()

如何获取客户端的真实IP地址？

# 正确方法

client_ip = websocket.client.host

# 常见错误：直接读取X-Forwarded-For头

# 需要配合代理设置处理

常见报错解决方案

错误1：403 Handshake Failed

现象：客户端连接时立即断开

分析：未通过握手验证，常见于：

缺少必要认证头
验证逻辑返回False后未及时close()

解决：

# 在拒绝连接时立即关闭

if not valid:

    await websocket.close(code=1008)

    return  # 必须立即返回

错误2：1006 Abnormal Closure

现象：客户端非正常断开

处理方案：

try:

    while True:

        data = await websocket.receive_text()

except WebSocketDisconnect as e:

    print(f"断开代码：{e.code}")

错误3：TypeError: 'str' expected

场景：发送非文本数据时

正确做法：

# 发送二进制数据

await websocket.send_bytes(binary_data)

# 发送文本数据

await websocket.send_text("message")

# 发送JSON

await websocket.send_json({"key": "value"})

余下文章内容请点击跳转至个人博客页面或者扫码关注或者微信搜一搜：编程智域前端至全栈交流与成长

，阅读完整的文章：如何在FastAPI中玩转WebSocket，让实时通信不再烦恼？

往期文章归档：

免费好用的热门在线工具

FastAPI WebSocket：你的双向通信通道为何如此丝滑？的更多相关文章

happyChat开发系列：使用websocket.io实现双向通信的乐聊大前端开发
一.前言乐聊是一个自己用websocket写一个完整的应用,虽然功能比较欠缺,但是实现了基本的文字聊天,以及群聊,私聊,机器人聊天等功能.因为这个自己做了PC端,无线端(手机端),以及使用cordo ...
FastAPI（56）- 使用 Websocket 打造一个迷你聊天室
背景在实际项目中,可能会通过前端框架使用 WebSocket 和后端进行通信这里就来详细讲解下 FastAPI 是如何操作 WebSocket 的模拟 WebSocket 客户端 #!usr/b ...
WebSocket 浅析
版权声明:本文由史燕飞原创文章,转载请注明出处: 文章原文链接:https://www.qcloud.com/community/article/241 来源:腾云阁 https://www.qclo ...
【腾讯Bugly干货分享】WebSocket 浅析
本文来自于腾讯Bugly公众号(weixinBugly),未经作者同意,请勿转载,原文地址:http://mp.weixin.qq.com/s/7aXMdnajINt0C5dcJy2USg 前言在W ...
websocket的子协议stomp协议
stomp协议Spring实现服务器注册EndPoint 用来与客户端建立websocket连接 websocket连接的建立应该与客户端与服务器之间的通道无关 jdk中 javax下的websoc ...
websocket基本概念
(1)websocket 协议与 http协议 websocket 协议,双工通道 socket连接不断开 http 协议 ,只能请求响应 (用户主动获取) socket连接断开都是基于socke ...
Spring Chapter4 WebSocket 胡乱翻译（二）
书接上文,Spring Chapter4 WebSocket 胡乱翻译 (一) 4.4.4. 消息流一旦暴露了STOMP端点,Spring应用程序就成为连接客户端的STOMP代理. 本节介绍服务器端 ...
HTML5(十二)——一文读懂 WebSocket 原理
一.WebSocket 由来 WebSocket 是一个持久化的协议,通过第一次 HTTP Request 建立连接之后,再把通信协议升级成 websocket,保持连接状态,后续的数据交换不需要再重 ...
JAVA使用netty建立websocket连接
依赖  <dependency> <gr ...
FastAPI快速查阅
官方文档主要侧重点是循序渐进地学习FastAPI, 不利于有其他框架使用经验的人快速查阅故本文与官方文档不一样, 并补充了一些官方文档没有的内容安装包括安装uvicorn $pip instal ...

随机推荐

Visual Studio Browser Link
用Visual Studio 2013 | 2015(不知道其他版本会不会)创建的项目(WebForm & MVC), 直接运行访问的页面源码会出现如下内容: 而这个莫名其妙多出来的Visua ...
C#/.NET/.NET Core技术前沿周刊 | 第 33 期（2025年4.1-4.6）
前言 C#/.NET/.NET Core技术前沿周刊,你的每周技术指南针!记录.追踪C#/.NET/.NET Core领域.生态的每周最新.最实用.最有价值的技术文章.社区动态.优质项目和学习资源等. ...
mybatis——分页插件PageHelper的使用
项目开发中涉及列表查询时,经常会需要对查询结果进行分页处理:常用的一个插件--PageHelper,是国内非常优秀的一款开源的mybatis分页插件,它支持基本主流与常用的数据库,一致支持mysql. ...
PHP 实现微信异步回调数据打印知识分享
一.引言在微信支付.微信公众号消息推送等场景中,微信服务器会通过异步回调的方式将处理结果发送给我们的服务器.为了便于调试和监控,我们需要获取并打印这些回调数据.本文将详细介绍如何使用 PHP 的 f ...
sonarqube+gitlab+jenkins+maven集成搭建 (五)
Jenkins与SonarQube Jenkins 配置 SonarQube在 SonarQube 中生成 Server authentication token登录 SonarQube 后,在 &q ...
在AI大爆发的背景下，企业管理软件有什么冲击
今天与同行开会提到在AI大爆发的背景下,未来企业管理软件究竟有什么冲击? 我和同事对此问题进行了探讨,一些拙见,与大家分享.先直接说观点:在未来的5到10年,制造业的管理软件市场将几乎消失.下面我来聊 ...
36.3K star！开发者专属PPT神器，Markdown秒变炫酷幻灯片！
嗨,大家好,我是小华同学,关注我们获得"最新.最全.最优质"开源项目和高效工作学习方法 Slidev 是专为开发者打造的现代化幻灯片制作工具,基于 Markdown + Vue 技 ...
AI法律助手：打造普惠法律服务的未来
当法律服务遇见人工智能,普通人的维权之路将不再艰难当法律服务成为奢侈品,AI或许是唯一出路 2025年的一个深夜,我刷着手机,一条新闻让我停下了滑动的手指: "某平台家装工人因合同纠纷讨薪 ...
【语义分割专栏】先导篇：评价指标(PA,CPA,IoU,mIoU,FWIoU,F1)
目录前言混淆矩阵计算混淆矩阵评价指标像素准确率(Pixel Accuracy,PA) 类别像素准确率(Class Pixel Accuracy,CPA) 类别平均像素准确率(Mean Pix ...
VS Code + Cline + 魔搭MCP Server 实现抓取网页内容。
MCP的诞生,可以说是为AI带来一波新的活力. ‌MCP(Model Context Protocol)‌是由Anthropic公司在2024年11月推出的一种开放标准协议,旨在为大型语言模型(LLM ...