你不知道的 WebSocket：服务器实时推送的核心协议，新手也能秒会

一、引言

初次接触 WebSocket 的人，都会问同样的问题：我们已经有了 HTTP 协议，为什么还需要另一个协议？它能带来什么好处？

在我们之前的教程中，我们在树莓派 Pico 上用 HTML 开发了一个基于 HTTP 协议的网页服务器，以此控制树莓派 Pico 的硬件引脚：

https://freakstudio.cn/node/019bd0cf-8ca7-7e97-83fe-0b29d55c6f5c

image.png

image.png

这个方式非常简单，但缺点也非常明显：每次提交表单都需要完成一次完整的网络往返（也就是页面刷新），导致存在明显延迟，这种往返通信对用户体验很不友好，延迟会导致用户重复点击，或是感觉界面无响应。

HTTP 协议的核心模式是请求 - 响应：浏览器发起请求，服务器处理后返回响应。它属于​半双工​通信，同一时间只能单向传输数据，每次通信都需要重新建立握手连接。

对很多嵌入式项目来说，这种协议完全够用：比如用浏览器配置开发板参数，之后开发板独立运行一段时间，但是考虑下面两个情况：

  • ​温湿度实时记录和显示：​如果使用 HTTP，浏览器必须不断轮询（例如每隔 1 秒请求一次数据），服务器才能返回最新的温湿度值；这样会带来几个问题：
    • 请求频率高，浪费带宽和 MCU 资源；
    • 数据存在延迟（取决于轮询间隔）；
    • 设备功耗增加（频繁网络通信）。
  • ​在线网络聊天室：​如果使用 HTTP，客户端需要不断轮询服务器是否有新消息（例如每几百毫秒请求一次）。这样不仅效率低，还会造成：
    • 大量无效请求（大部分时候没有新消息）；
    • 服务器压力增大；
    • 消息延迟明显，体验差。

你可以看到，在需要服务器可以在有新消息时立即推送给所有客户端的情况下，使用 HTTP 通信并不友好。

那么，我们实际上可以选择另一种更优的方案：​在浏览器与服务器之间建立并保持一个长连接​​，实现全双工通信​。

在这种模式下，客户端和服务器都可以在任意时刻主动发送数据，不再受限于 HTTP “请求 - 响应”的单向通信机制，从而避免频繁轮询带来的性能浪费和延迟问题。

这种通信方式特别适合​需要实时数据更新和即时交互反馈的场景​，例如实时监控、在线聊天、远程控制等。

而实现这一能力的核心协议，就是 ​WebSocket​。

image.png

客户端（如浏览器）向服务器发起连接请求，经一次 HTTP 握手完成协议升级后，建立持久全双工长连接。

二、WebSocket 协议介绍

2.1 基本概念

它于 2008 年诞生，2011 年成为国际标准：

  1. WebSocket 最初在 HTML5 规范中以 TCPConnection 为名，作为基于 TCP 的套接字 API 的占位方案，用于解决浏览器端原生 TCP 通信的需求。
  2. 在 WebSocket 出现前，浏览器端端口 80 的全双工通信依赖 Comet 通道 技术，但存在两大核心缺陷：
    1. 实现复杂度高，部署与维护成本大；
    2. 因 TCP 三次握手、HTTP 请求头的额外开销，对小消息场景的传输效率极低。
  3. 2008 年 6 月，Michael Carter 牵头系列技术讨论，产出了首个名为「WebSocket」的协议版本，核心目标是在不破坏网络安全假设的前提下，解决 Comet 技术的痛点；
  4. 随后 Ian Hickson 与 Michael Carter 合作确定 WebSocket 这一名称，由 Ian Hickson 正式写入 HTML5 规范。

目前​所有浏览器均已原生支持​，无需额外插件，包括 Google Chrome、Firefox、Microsoft Edge、Internet Explorer、Safari 和 Opera，其属于​真正的双向平等对话​，支持服务器主动向客户端推送信息，也支持客户端主动向服务器发消息，属于主流的服务器推送技术之一。

其技术特点包括：

  • 基于 TCP​ 协议 构建，服务器端实现逻辑简单，适配性强。
  • 完美兼容 HTTP 生态，​默认共用 80（ws​​）、443（wss）端口​；
  • 握手阶段采用 HTTP 协议，不易被网络屏蔽，可顺利通过各类 HTTP 代理服务器。
  • 数据格式轻量化，​通信开销小、效率高​；
  • 支持文本、二进制数据双向传输，覆盖文字、文件、音视频等各类数据场景。
  • ​无同源限制​，客户端可与任意服务器建立连接，突破浏览器同源策略限制；
  • 协议标识符：​ws​（未加密）、​wss​（加密，类似 HTTPS），通信地址遵循 URL 规范，示例：ws://​example.com:80/some/path。

image.png

一句话概括就是，WebSocket 以​TCP​ 为基础、HTTP 兼容为桥梁、双向实时为核心​，兼具低延迟、高灵活、跨域自由的特点，完美适配浏览器与服务器的实时交互场景。

2.2 WebSocket 的工作流程

image.png

可以分为以下三个阶段：

  1. 握手阶段：HTTP 协议升级，建立持久连接（图中红色流程）
    1. 客户端发起 HTTP 升级请求：向服务器发送携带 Upgrade: websocket 头、随机密钥 Sec-WebSocket-Key 的 HTTP 请求，申请将当前 HTTP 连接升级为 WebSocket 连接。
    2. 服务器响应握手确认：通过约定算法生成响应密钥 Sec-WebSocket-Accept，返回给客户端完成协议升级。
    3. 连接正式建立：客户端验证响应密钥通过后，持久 TCP 长连接生效，图中标注 connection opened（连接已打开），握手阶段完成。
  2. 数据传输阶段：全双工双向实时通信（图中蓝色流程）
    1. 持久长连接生效：握手完成后，客户端与服务器维持 open and persistent connection（开放且持久的连接），全程无需重复建立连接。
    2. 双向实时消息传输：双方可随时主动向对方发送文本 / 二进制数据，实现真正的全双工通信，服务器可主动推送数据，彻底摆脱传统 HTTP 的客户端轮询限制。
    3. 心跳保活机制：双方通过 Ping（心跳请求）/Pong（心跳响应）控制帧周期性交互，维持连接存活，避免长连接因闲置被网络设备断开。
  3. 关闭阶段：优雅终止连接（图中黑色流程）
    1. 任意一方发起关闭请求：客户端或服务器可主动发送 Close 控制帧，申请关闭 WebSocket 连接。
    2. 双向确认关闭：对方收到关闭请求后，返回 Close 响应帧，完成双向确认。
    3. 连接正式关闭：双方确认后，彻底断开 TCP 长连接，图中标注 connection closed（连接已关闭），通信流程结束。

2.3 WebSocket 的数据帧格式

2.3.1 数据帧概述

WebSocket 在完成握手建立长连接后，​所有通信都以「数据帧​​（Frame）」为最小传输单位​，无论是业务数据还是连接控制指令，都封装在二进制帧中传输：

image.png

WebSocket 数据帧是​二进制格式​，整体分为帧头（Header）和有效载荷（Payload）两大部分，其中帧头又分为固定头部（前 2 字节 / 16bit） 和​可变扩展头部​（根据长度、掩码动态变化），结构如下：

image.png

其中：

  • 帧头：包含 FIN、Opcode、Masked、Payload length 等核心字段，用于控制帧的解析与类型。
    • FIN 字段（1bit，偏移 0）：标记当前帧是否为​完整消息的最后一帧​，用于消息分片。
      • ​取值规则​：
        • 1：最后一帧，代表消息传输完成；
        • 0：分片帧，代表消息未结束，后续还有数据帧。
      • 对应分片机制：
        • 非分片消息：单帧，FIN=1 且 Opcode≠0；
        • 分片消息：首帧 FIN=0、Opcode≠0（定义消息类型），中间帧 FIN=0、Opcode=0（延续帧），最后一帧 FIN=1、Opcode=0（延续帧，标记结束）。
      • 支持大消息分片传输，适合内存有限的嵌入式设备（如树莓派 Pico W），无需缓存完整消息即可边生成边发送。
    • RSV1/RSV2/RSV3 字段（各 1bit，偏移 1-3）：
      • 保留位，用于协议扩展，​默认必须为 0​，仅当客户端与服务器在握手阶段协商了扩展（如压缩）时，才会使用非 0 值。
      • ​对应压缩扩展​：permessage-deflate 压缩扩展会在握手时通过 Sec-WebSocket-Extensions: permessage-deflate 协商，启用后数据帧的 RSV1=1，表示 payload 为压缩数据。
    • Opcode 字段（4bit，偏移 4-7）：定义帧的类型，决定 payload 的解析方式，分为​非控制帧（数据帧​） 和控制帧两大类。
    • Masked 字段（1bit，偏移 8）：
      • ​作用​：标记帧是否经过掩码处理。
      • ​强制规则​：
        • ​客户端 → 服务器的所有帧：Masked必须为1​​（必须做掩码）​；
        • ​服务器 → 客户端的所有帧：Masked必须为0​​（禁止做掩码）​。
      • ​掩码原理​：用 32bit（4 字节）的随机 Masking key，对 payload 的每个字节做 XOR 运算。
    • Payload length 字段（7/7+16/7+64bit，偏移 9 开始）：
      • ​作用​：表示有效载荷（扩展数据 + 应用数据）的字节长度
        • 0-125：直接用 7bit 表示长度，适合 ≤125 字节的小消息；
        • 126：后续 16bit（2 字节）表示长度，适合 126-65535 字节的中等消息；
        • 127：后续 64bit（8 字节）表示长度，适合 > 65535 字节的大消息（最高位必须为 0，无符号）。
      • ​字节序​：大端（big-endian），无符号数。
      • ​优势​：小消息用短头，大消息用长头，最大化节省带宽。
    • Masking key 字段（32bit，可选）：
      • 仅当 Masked=1 时存在，是 4 字节的​随机数​，客户端每次发帧都需生成新的随机密钥，不可固定。
      • 作用：配合 Masked 字段，完成客户端到服务器的掩码处理。
  • 有效载荷：实际传输的业务数据（如聊天消息、传感器数据、控制指令）：
    • 分为两部分：
      • ​扩展数据​：仅协商了扩展（如压缩）时存在，长度由扩展定义；
      • ​应用数据​：实际的业务数据，如聊天消息、传感器数据、控制指令。
    • 总长度 = Payload length 字段的值。

2.3.2 Opcode 字段分类和含义

Opcode 字段分类和含义如下：

image.png

其中，控制帧核心特性为不可分片，payload 最大长度 125 字节，优先级高于数据帧，用于管理连接状态。

2.3.3 控制帧详解

控制帧用于管理连接状态，Opcode 为 0x08-0x0F，不可分片，payload 最大 125 字节：

image.png

2.3.4 分片传输

WebSocket 支持将一个大消息拆分为多个帧（分片）传输，核心规则如下：

  • ​非分片消息​：单帧完成传输，FIN=1 且 Opcode≠0，适合小消息。
  • ​分片消息​：≥2 帧完成传输，规则：
    • 首帧：FIN=0，Opcode≠0（定义消息类型，如文本 / 二进制）；
    • 中间帧：FIN=0，Opcode=0（延续帧，继承首帧的消息类型）；
    • 最后一帧：FIN=1，Opcode=0（延续帧，标记消息结束）。
  • ​核心价值​：
    • 适配嵌入式设备（如 Pico W）：内存有限，无需缓存完整大消息，边生成边分片发送；
    • 支持流式传输：如实时音视频，边采集边发送；
    • 避免大消息阻塞连接：可穿插控制帧（Ping/Pong），保证连接存活。

2.3.5 压缩扩展

WebSocket 的标准扩展（RFC 7692），用 DEFLATE 算法压缩数据消息，减少带宽占用，提升传输效率。

在握手阶段，客户端与服务器通过 Sec-WebSocket-Extensions: permessage-deflate 头协商启用压缩。

启用压缩后，数据消息的第一个帧 RSV1=1，表示 payload 为压缩数据，接收方需解压。

2.4 WebSocket 的接口

WebSocket 接口是客户端（如浏览器）与服务器建立、管理和终止 WebSocket 连接的核心工具，下面是基于 JavaScript 实现，提供了构造函数、方法、事件、属性和常量五大类接口：

image.png
image.png

WebSocket 接口按功能可分为五大类，各类接口相互配合，构成完整的通信控制逻辑：

  • ​构造函数（Constructor​​）​：核心用于初始化 WebSocket 实例，发起与服务器的连接握手，是建立 WebSocket 通信的起点。需传入目标 URL 和可选的子协议参数，URL 需遵循特定格式规范，否则会触发语法错误。
  • ​方法（Method​​）​：提供主动操作连接的能力，主要包括发送数据（send）和关闭连接（close）两个核心方法。发送数据时需注意数据格式和连接状态，关闭连接时需指定合法的状态码和关闭原因，避免异常。
  • ​事件（Event​​）​：用于监听 WebSocket 连接的各类状态变化和数据事件，是被动响应连接状态的核心方式。包括连接成功（open）、接收数据（message）、连接关闭（close）、连接错误（error）四种核心事件，可通过绑定事件回调函数，实现对连接状态的实时监控和业务逻辑处理。
  • ​属性（Attribute​​）​：用于配置或获取 WebSocket 连接的相关参数，主要包括二进制数据接收类型（binaryType），可根据业务需求修改，适配不同的二进制数据处理场景。
  • ​只读​属性（​​Read-only attribute）​：用于获取 WebSocket 连接的不可修改状态和参数，如连接 URL、待发送数据字节数、协商的子协议、连接状态等，为开发调试和状态判断提供依据。
  • ​常量（Constant​​）​：定义了 WebSocket 连接的四种核心状态，对应不同的通信阶段，可通过只读属性 readyState 获取当前状态，用于判断连接是否可收发数据、是否处于关闭过程等。

需要注意的是，所有接口的使用都依赖于 ​​WebSocket​​ 连接的当前状态（readyState），例如发送数据（send）仅能在连接处于“已连接”（OPEN）状态时调用，否则会触发异常；关闭连接（close）在不同状态下的行为也不同，需严格遵循接口规范。

三、async_websocket_client 库介绍

3.1 基本概念

这是一个​专为 MicroPython 设计的轻量级异步 WebSocket 客户端库​，实现了 WebSocket 协议（RFC 6455）的核心功能，支持 ws://（明文）和 wss://（TLS 加密）连接：

image.png

​源码地址：​https://pypi.org/project/micropython-async-websocket-client

提供了下面的能力：

image.png

其核心类是：AsyncWebsocketClient

image.png

其中初始化方法入口参数为：

def __init__(self, ms_delay_for_read: int = 5)
  • ms_delay_for_read：非阻塞 socket 读取的轮询间隔（毫秒），硬件性能越强可设越小，默认 5ms 适配多数 MCU。

核心方法如下：

image.png

常用常量定义如下：

  • ​操作码​（​​Opcodes）​：OP_TEXT（文本帧）、OP_BYTES（二进制帧）、OP_PING/OP_PONG（心跳）、OP_CLOSE（关闭）
  • ​关闭码（Close Codes​​）​：CLOSE_OK（正常关闭）、CLOSE_GOING_AWAY（客户端断开）、CLOSE_TOO_BIG（消息过大）等，符合 RFC 6455 标准

3.2 快速测试

这里，我们使用树莓派 Pico2w 开发板进行测试，借助外部网站：websocket-tester

这是 See-Tool 工具箱中「网络协议」分类下的一款 ​WebSocket 在线测试工具​，可输入 wss://​ws.postman-echo.com/raw 等服务地址建立连接，支持手动发送消息或定时自动发包，并在右侧调试面板实时查看收发日志与 JSON 解析，适合接口联调、实时通信排错和 WebSocket 连通性验证。

地址是：https://see-tool.com/websocket-tester

image.png

这是基于 Postman 官方 WebSocket 回显服务器的标准测试场景，核心逻辑是 「客户端发送什么内容，服务器就原样回显什么内容。

这里，我们首先在 upypi 上搜索 WebSocket 库并安装：

image.png

https://upypi.net/en/pkgs/async_websocket_client/1.0.0

复制安装命令：

mpremote mip install https://upypi.net/pkgs/async_websocket_client/1.0.0

image.png

这里，我们将下面 main.py 文件烧录到树莓派 Pico2w 中：

# Python env   : MicroPython v1.23.0
# -*- coding: utf-8 -*-
# @Time    : 2026/04/12
# @Author  :
# @File    : main.py
# @Description : Async WebSocket client usage example for MicroPython

# ======================================== 导入相关模块 =========================================

import network
import asyncio
import machine
import time
from async_websocketclient import AsyncWebsocketClient  # 导入你的WebSocket库

# ======================================== 全局变量 ============================================

# 配置WiFi (请替换为你的WiFi信息)
WIFI_SSID     = "Y/OURSPACE"
WIFI_PASSWORD = "qc123456789"

# 测试服务器地址 (Postman Echo)
TEST_URL = "wss://ws.postman-echo.com/raw"

# ======================================== 功能函数 ============================================

def connect_wifi():
    """
    连接 WiFi 并返回网络对象。

    Returns:
        network.WLAN: 已连接的 WLAN 对象；连接失败时返回 None。

    ==========================================

    Connect to WiFi and return the network object.

    Returns:
        network.WLAN: Connected WLAN object; None if connection fails.
    """
    # 初始化WiFi为STA模式（客户端模式）
    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)

    # 避免重复连接
    if not wlan.isconnected():
        print(f"Connecting to WiFi: {WIFI_SSID}")
        wlan.connect(WIFI_SSID, WIFI_PASSWORD)

        # 等待连接（最多等待10秒）
        timeout = 10
        while not wlan.isconnected() and timeout > 0:
            time.sleep(1)  # 替换utime.sleep为time.sleep
            timeout -= 1
            print(f"Connecting... {timeout}s remaining")

        if wlan.isconnected():
            # 打印连接信息（IP、子网掩码、网关、DNS）
            ip_info = wlan.ifconfig()
            print(f"WiFi connected")
            print(f"IP: {ip_info[0]}")
            print(f"Gateway: {ip_info[2]}")
            print(f"DNS: {ip_info[3]}")
        else:
            print("WiFi connection failed")
            return None
    else:
        print("WiFi already connected")

    return wlan

async def websocket_test():
    """
    WebSocket 测试主逻辑，依次完成连接、发送、接收和关闭。

    ==========================================

    Main WebSocket test logic: connect, send, receive, and close in sequence.
    """
    global ws_client
    
    try:
        # 1. 连接WiFi
        if not connect_wifi():
            return

        # 2. 连接WebSocket服务器
        print("Connecting: {}".format(TEST_URL))
        await ws_client.handshake(TEST_URL)
        print("WebSocket connected (WSS)")

        # 3. 发送测试消息
        test_message = "Hello from Pico2W!"
        print("Sending: {}".format(test_message))
        await ws_client.send(test_message)

        # 4. 循环接收消息
        for count in range(5):
            print("\nWaiting for message ({})...".format(count + 1))
            response = await ws_client.recv()

            if response:
                print("Received: {}".format(response))
                # 发送下一条消息
                next_msg = "Pico count: {}".format(count + 1)
                await ws_client.send(next_msg)
                await asyncio.sleep(1)
            else:
                print("No message received, connection may be closed")
                break

        # 5. 关闭连接
        print("\nTest complete, closing connection...")
        await ws_client.close()
        print("Connection closed")

    except Exception as e:
        print("\nException: {} - {}".format(type(e).__name__, e))
        await ws_client.close()

# ======================================== 自定义类 ============================================

# ======================================== 初始化配置 ===========================================

# 初始化WebSocket客户端
ws_client = AsyncWebsocketClient(ms_delay_for_read=5)

# ========================================  主程序  ===========================================

# 运行主程序
if __name__ == "__main__":
    asyncio.run(websocket_test())

烧录代码，运行结果如下：
image.png

这是树莓派 Pico2W 成功运行编写的异步 WebSocket 客户端库的测试结果：

代码成功连接到 wss://​ws.postman-echo.com/raw 回显服务器，完成了 WiFi 连接、WebSocket 握手、文本消息发送与接收的全流程，Pico 依次发送计数消息并收到服务器的正确回显，最后正常关闭连接。

eb6b459ccb3f99726a2fd06d98170352.png

e56a916b375ed771aab3187baee81773.png

posted @ 2026-04-14 14:09  FreakStudio  阅读(8)  评论(0)    收藏  举报