websocket子协议是客户端与服务端在握手阶段协商应用层语义的标准机制，通过sec-websocket-protocol头严格字符串匹配实现多版本api路由与向前兼容，命名须语义化（如"v2.chat.example.com"），前端按降级顺序传数组，服务端匹配首个支持项并绑定对应处理器，协商失败则ws.protocol为空导致静默解析错误。
WebSocket 子协议（Subprotocol）不是版本标签，而是客户端和服务端协商“讲哪种话”的标准机制。它让新旧客户端能共用同一个 WebSocket 端口，靠协议名匹配自动路由到对应处理逻辑，无需拆分端口或路径。
子协议命名要体现语义版本
协议名必须清晰表达兼容范围和行为边界，不能模糊或动态化：
- "v2.chat.example.com"——明确指向第二版聊天协议，含字段格式、错误码、心跳规则等完整契约
- "api-1.5+json"——声明支持 1.5 及以上版本，且仅接受 JSON 载体，服务端可据此启用新字段解析
- "legacy-v1"——专用于兜底老客户端，不返回新增字段，不触发新校验逻辑
- 避免用"chat"或"myapp"这类无区分度名称；也不要在协议里塞时间戳、用户ID等动态值
前端按降级顺序声明候选协议
客户端需把支持的协议按兼容性从高到低排列，让服务端有明确选择依据：
Java JDK 25
下载
Java JDK 25 来自 OpenJDK 官方归档，版本为 JDK 25，本条下载地址已指向官方 Windows x64 zip 安装包直链，适合调试旧项目或兼容旧版 Java 运行环境。
- 新版页面传 ["v3.api.example.com", "v2.api.example.com", "legacy-v1"]
- 旧版 App 仍可只传 ["legacy-v1"] 或 ["v2.api.example.com"]，连接照常建立
- 服务端收到后，从左到右匹配首个自己支持的协议并确认——这就天然形成“降级链”
- 构造时必须用第二个参数，类型只能是 string 或 string[]，不能是对象、null 或带空格字符串（如["chat v2"]会失败）
服务端严格匹配并绑定处理器
子协议协商成功后，ws.protocol 才有值；否则为空，后续所有按协议设计的解析都会静默失效：
- FastAPI 中必须显式调用
await websocket.accept(subprotocol=xxx)，且值必须精确等于客户端数组中的某一项（大小写敏感） - Node.js（如 ws 库）需在 upgrade 事件中检查
req.headers['sec-websocket-protocol']，从中选取首个支持项，再写入响应头 - 每个协议名应绑定独立的消息处理器：v2 处理器不解析 v3 新字段，legacy-v1 处理器跳过所有 v2+ 的校验逻辑
- 协议一旦协商完成，连接生命周期内不可变更，版本切换需重连
避免常见握手失败陷阱
子协议协商失败不会报错，但会导致语义断连——消息发出去了，对方却按错协议解析：
- 客户端漏传第二个参数，或传了 undefined → 请求头无
Sec-WebSocket-Protocol，服务端无法协商 - 服务端 accept 时没传
subprotocol参数 → 响应头缺失该字段，浏览器认为协商失败 - 代理（如 Nginx）过滤或重写了
Upgrade、Connection、Sec-WebSocket-Key等关键 header → 握手直接中断 - 反向代理需禁用缓冲（
proxy_buffering off）、延长超时（proxy_read_timeout 60），确保轮询降级通道畅通（若同时启用）
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
