ChannelPipeline是Netty中每个Channel自动创建的双向事件处理器链，入站事件从head向tail传播，出站事件反向传播；必须在EventLoop线程内安全添加/移除handler，严格按职责顺序配置编解码器与业务处理器。
ChannelPipeline 就是 Netty 里那个自动串好的双向处理器链
它不是你手动 new 出来的工具类，而是每个 Channel 创建时就自带的“事件流水线”。入站（比如收到字节、连接建立）和出站（比如写数据、关闭连接）事件，都会按顺序经过 pipeline 上注册的 ChannelHandler。不理解这点，后面加 handler、调顺序、查漏处理逻辑，全都会错位。
常见错误现象：fireChannelRead 触发了但业务 handler 没执行；writeAndFlush 后数据没加密或没编码；甚至 exceptionCaught 根本没被调到——八成是 handler 没加对位置，或者加成了出站 handler 却想处理入站异常。
- 必须用
pipeline.addLast()或带名字的变体添加 handler，直接 new Handler 不生效 - 入站事件（
channelRead,exceptionCaught等）从 head 往 tail 传播；出站事件（write,bind等）反向，从 tail 往 head 传播 - 同一个 handler 如果既实现
ChannelInboundHandler又实现ChannelOutboundHandler，它在链表中只占一个节点，但会响应两个方向的事件
怎么安全地往 pipeline 插入自定义 handler
最常踩的坑：在 channel 还没注册到 eventLoop 前就调 pipeline.addLast()，抛 UnsupportedOperationException；或者在 handler 执行过程中（比如 channelRead 方法里）又去改 pipeline 结构，触发 ConcurrentModificationException。
正确做法永远只有一条：确保操作发生在 EventLoop 线程内，且避开 handler 自身生命周期方法的执行期。
- 推荐在
initChannel回调里添加（ServerBootstrap.childHandler()或Bootstrap.handler()中传入的ChannelInitializer） - 运行时动态添加？必须用
channel.eventLoop().execute(() -> pipeline.addLast(...)) - 不要在
channelRead里调pipeline.remove(this)，改用ctx.fireChannelRead(msg)后再ctx.pipeline().remove(ctx.name())
为什么 handler 顺序不能随便调，尤其是解码器和业务逻辑之间
Netty 不检查 handler 类型是否匹配事件流向，它只管按链表顺序转发。把 StringDecoder 放在业务 SimpleChannelInboundHandler<String> 后面，结果就是业务 handler 收到的是原始 ByteBuf，直接 ClassCastException；反过来，如果 LengthFieldBasedFrameDecoder 在 StringEncoder 后面，出站数据会被二次编码，服务端根本解析不了。
典型安全顺序（入站方向）：ByteToMessageDecoder → MessageToMessageDecoder → 业务 handler；出站则倒过来：业务 handler → MessageToMessageEncoder → MessageToByteEncoder。
-
addFirst()插到 head 后，适合放日志、监控等通用拦截器 -
addBefore("xxx")和addAfter("xxx")比硬编码索引更可靠，尤其 pipeline 可能被其他模块动态修改 - 用
pipeline.context(YourHandler.class)查找已有 handler，比遍历更准，也避免空指针
pipeline 遍历时拿到的是 ChannelHandlerContext，不是 handler 本身
很多人以为 for (ChannelHandler h : pipeline) 能直接拿到 handler 实例，其实拿到的是 ChannelHandlerContext 包装对象。它封装了 handler、执行线程绑定、前后节点引用，还缓存了 handler 的事件传播能力。直接强转或调用 handler 方法，大概率出错。
真正需要 handler 实例时，应该显式调 context.handler()；而绝大多数场景（如跳过当前 handler、触发下游事件），都应该用 context.fireChannelRead(...) 或 context.pipeline().fireXXX()。
- 遍历 pipeline 仅建议用于调试或监控，比如打印所有 handler 名称：
pipeline.contexts().forEach(c -> System.out.println(c.name())) - 不要在遍历中调
context.remove()，会导致迭代器失效；应先收集要删的 context 名，再循环 remove -
ChannelHandlerContext是线程绑定的，跨 eventLoop 调用它的方法（如write）会自动提交任务，但别依赖这个机制做关键路径调度
真正难的不是加几个 handler，而是想清楚每个 handler 的职责边界在哪、谁该响应哪个事件、传播中断点设在哪里。很多线上问题，追到最后都是某个 handler 吞了异常没 fire，或者忘了调 fireChannelRead 导致后续 handler 彻底失联。
