IdleStateHandler是Netty提供的应用层空闲检测处理器，不依赖TCP Keepalive，能精准控制心跳节奏；配置时三个参数单位为秒，分别表示读空闲、写空闲、读写空闲时间；收到IdleStateEvent后应发心跳而非直接关闭连接，并确保心跳包兼容编解码器。
IdleStateHandler 是什么，为什么不能只靠 TCP Keepalive
IdleStateHandler 是 Netty 提供的、用于检测连接空闲状态的核心处理器。它不依赖操作系统层面的 TCP Keepalive（默认 2 小时才触发），而是基于 Netty 的事件循环，在应用层主动判断读/写/读写是否超时。TCP Keepalive 在 NAT 网关、负载均衡器或移动网络下经常失效，而 IdleStateHandler 能精准控制心跳节奏，是保活真正可靠的手段。
怎么配置 IdleStateHandler 的三个超时参数
构造 IdleStateHandler 时传入的三个 long 参数分别对应：读空闲、写空闲、读写空闲时间（单位：秒）。注意不是毫秒，也不是任意时间单位——Netty 内部用 TimeUnit.SECONDS 解析。
- 读空闲（
readerIdleTimeSeconds）：对端长时间没发数据，常见于客户端断网但未发 FIN - 写空闲（
writerIdleTimeSeconds）：本端长时间没发数据，需主动发心跳包（如PING） - 读写空闲（
allIdleTimeSeconds）：两者都满足时触发，一般少用；建议优先用前两个
示例：
pipeline.addLast(new IdleStateHandler(30, 25, 0));
表示：30 秒没收到数据就认为读空闲；25 秒没发送数据就认为写空闲；不监控全空闲。
收到 IdleStateEvent 后该做什么，别直接 close
IdleStateHandler 触发后，会向 pipeline 抛出 IdleStateEvent，你必须在自定义 ChannelInboundHandler 中重写 userEventTriggered 捕获它。常见错误是收到 READER_IDLE 就立刻 ctx.close()——这会导致误杀：比如客户端正在序列化大对象，只是暂时没发包。
- 对
WRITER_IDLE：应立即写一个轻量心跳（如ByteBuf写入单字节0x01），并确保调用ctx.writeAndFlush() - 对
READER_IDLE：可先发一次心跳并等待响应；若连续 2–3 次无回应，再关闭连接 - 务必检查
ctx.channel().isActive()，避免在已关闭 channel 上重复操作
心跳包设计与编码器兼容性问题
心跳本质是业务消息，必须能被你的编解码器正确处理。如果用了 LengthFieldBasedFrameDecoder 或自定义协议解析器，而心跳包没带长度头或不符合结构，就会导致解码失败、后续消息错位。
- 推荐心跳使用固定格式：比如纯字节数组
Unpooled.wrappedBuffer(new byte[]{0x01})，并确保解码器对单字节有兜底逻辑 - 若用 JSON/Protobuf 协议，心跳也得走同一流程，否则需在解码器中显式跳过特定 marker（如首字节为
0x01时直接 discard） - 不要在心跳里塞时间戳或随机数——增加无谓解析开销；保活只要“通”就行，不是为了校准时钟
真正难的不是加 IdleStateHandler，而是让心跳穿过整条 pipeline 不被丢、不解错、不阻塞主业务。很多线上问题都出在解码器没适配心跳，或者心跳响应没及时 flush 导致写空闲反复触发。
