WebSocketServerProtocolHandler必须置于pipeline最前端，因其需处理原始HTTP升级请求；若前置解码器已将其转为FullHttpRequest，则握手失败并抛IllegalStateException。
WebSocketServerProtocolHandler 为什么必须放在 pipeline 最前面？
因为 WebSocketServerProtocolHandler 需要拦截并处理原始 HTTP 升级请求，如果它前面有其他解码器（比如 HttpObjectDecoder 已经把请求转成 FullHttpRequest），它就收不到完整的、未解析的 HTTP 请求行和头 —— 握手会直接失败，日志里常出现 IllegalStateException: not an HTTP request 或静默关闭连接。
- 必须确保它紧接在
HttpServerCodec之后、任何业务ChannelInboundHandler之前 - 不要把它和
HttpObjectAggregator混用：聚合器会把握手请求也聚合成FullHttpRequest，导致握手失败 - 若需读取升级请求中的自定义 header（如
Sec-WebSocket-Protocol），得在WebSocketServerProtocolHandler之前加一个轻量 handler 提前捕获HttpRequest
如何正确处理 WebSocket 帧类型（TEXT/BINARY/PONG）？
Netty 的 WebSocketFrame 是抽象基类，实际收到的是 TextWebSocketFrame、BinaryWebSocketFrame、PongWebSocketFrame 等子类。直接写 channelRead 处理 Object 容易漏掉 PING/PONG，导致连接被对端超时断开。
- 务必重写多个
channelRead重载，或统一用instanceof判断帧类型，尤其别忽略PingWebSocketFrame和PongWebSocketFrame -
PingWebSocketFrame必须主动回PongWebSocketFrame，否则 Nginx 或浏览器可能认为连接已死 - 文本帧内容用
frame.text()获取字符串；二进制帧用frame.content()取ByteBuf，记得retain()再传递，否则可能被提前释放
为什么启用 compression 后客户端收不到消息？
Netty 5.0+ 的 WebSocketServerProtocolHandler 默认不开启压缩，但一旦手动加了 WebSocketServerCompressionHandler，就必须注意：它只压缩 TEXT/BINARY 帧，且要求客户端在握手时明确声明支持 permessage-deflate。Chrome/Firefox 默认带，但很多测试工具（如 wscat）不带，握手会被拒绝或后续帧解压失败。
- 检查客户端
Sec-WebSocket-Extensionsheader 是否含permessage-deflate - 服务端启用压缩需显式添加
WebSocketServerCompressionHandler，且必须放在WebSocketServerProtocolHandler之后 - 压缩 handler 对 PING/PONG 帧无影响，但若自定义逻辑误将非 WebSocketFrame 传给它，会抛
ClassCastException
如何安全地从 WebSocket 连接中获取原始 HTTP 请求信息？
握手完成后，原始 HttpRequest 就被 WebSocketServerProtocolHandler 丢弃了。如果需要读取 cookie、token、query 参数或 client IP，必须在握手完成前“截胡”。
- 在
WebSocketServerProtocolHandler前插入一个自定义SimpleChannelInboundHandler<HttpRequest>，重写channelRead0，把关键字段存到ChannelHandlerContext.channel().attr() - 避免在
userEventTriggered中取HandshakeComplete事件再反查 —— 此时 request 已不可用 - IP 地址优先用
channel.remoteAddress()，而非从 header 解析X-Forwarded-For，后者需前置代理配合且易伪造
WebSocket 握手不是一次“设置好就完事”的动作，而是一组严格依赖顺序、生命周期和类型判断的协作机制。最容易出问题的地方，往往藏在 handler 位置、帧类型分支遗漏、以及对“握手已完成”这个状态的错误假设里。
