mica-net Java 网络框架 ​

Java CIMica net Maven release

mica-net 是 mica-mqtt 的底层网络框架。

基于 Java AIO 的轻量、高性能非阻塞网络通信框架：TCP 使用 AsynchronousSocketChannel，UDP 使用 DatagramChannel。

✨ 能力一览 ​

  • TCP/UDP 网络通信 — TCP 基于 AIO AsynchronousSocketChannel，UDP 基于 NIO DatagramChannel
  • HTTP/HTTPS 与 WebSocket — 内置编解码器，支持 SSE、Stream、Router
  • MCP（Model Context Protocol）服务端 — 完整实现 tools、resources、prompts、sampling 等协议能力
  • TCP 代理协议 — 支持 PROXY protocol V1/V2，可解析 nginx、ELB 转发的原始 IP
  • SSL/TLS — 双向认证、PKCS12 证书，可自定义协议版本与加密套件
  • 集群与节点管理 — 内置集群同步、节点选择、心跳与重连

📦 模块导航 ​

模块说明
mica-net-coreTCP / UDP 通信核心，含 TcpHandler、UdpHandler、三段式编解码
mica-net-httpHTTP / HTTPS / WebSocket 服务端，HttpServerStarter + HttpRouter + SSE
mica-net-mcpMCP 服务端实现

📖 使用文档 ​

各模块的「上手即用」文档汇集在 使用文档索引 中，与代码示例保持一致。

模块文档主题
mica-net-coreTCP 使用 — AsynchronousSocketChannel 的 TCP 通信，含服务端/客户端、心跳、SSL、PROXY Protocol、集群
mica-net-coreUDP 使用 — 基于 DatagramChannel 的 NIO UDP，含 UdpChannel/UdpHandler 三段式协议
mica-net-httpHTTP 使用 — HttpServerStarter + HttpRouter + SSE，覆盖路由/过滤器/异常/JSON
mica-net-httpWebSocket 使用 — WsServerStarter + IWsMsgHandler，支持文本/二进制/握手扩展/主动推送

阅读建议

  • 新接入 mica-net：先读 TCP 文档，理解 TcpHandler、三段式编解码、连接上下文；
  • HTTP 服务（REST、SSE、流式响应）请直接看 HTTP 使用；
  • 实时双向通信请看 WebSocket 使用；
  • IoT、实时上报、低开销短报文请看 UDP 使用；
  • MCP / 集群 / 高级特性请参考对应源码模块。

🏗️ 核心设计 ​

核心组件分层 ​

┌─────────────────────────────────────────────────────────────┐
│                         Tio (API层)                          │
│  提供所有对外API：send、close、bind、unbind等操作              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│          NetChannel / ChannelContext / UdpChannel           │
│  • NetChannel：抽象网络通道接口（send、close）                │
│  • ChannelContext：TCP 连接上下文                            │
│  • UdpChannel：UDP 通道抽象                                  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                 TcpHandler / UdpHandler                     │
│  TcpHandler：TCP 业务处理接口（增强类型安全，泛型化）         │
│  UdpHandler：UDP 业务处理接口（基于 UdpChannel）             │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────┬──────────────────┬───────────────────────┐
│TcpDecodeRunnable │ HandlerRunnable  │  TcpSendRunnable      │
│  (解码任务)       │  (业务处理任务)   │   (发送任务)           │
└──────────────────┴──────────────────┴───────────────────────┘

三层任务队列 ​

[网络I/O] → [解码队列] → [处理队列] → [发送队列] → [网络I/O]
    ↓            ↓            ↓            ↓
ReadCompletionHandler  TcpDecodeRunnable  HandlerRunnable  TcpSendRunnable

核心类职责 ​

类职责
TioConfig全局配置管理（线程池、统计、心跳、SSL 等）
NetChannel抽象网络通道接口（send、close），TCP/UDP 统一抽象
ChannelContext连接上下文（状态、队列、统计、绑定关系），实现 NetChannel
TcpHandler / UdpHandlerTCP/UDP 业务处理接口，强类型泛型化
ReadCompletionHandler / WriteCompletionHandler异步读 / 写完成处理器
TcpDecodeRunnableTCP 解码任务（粘包/半包处理）
HandlerRunnable业务处理任务
TcpSendRunnableTCP 发送任务（批量处理、SSL 加密）

🔊 开发提示 ​

  • Tio.close 关闭连接时可保留客户端重连等维护逻辑，适用于客户端；
  • Tio.remove 关闭连接后不再进行重连等维护，适用于服务端。

📝 2.0 变更要点 ​

基础改造

  • 最低编译版本 Java 8
  • 包名从 org.tio 迁移到 net.dreamlu.mica.net
  • 不强制依赖 fastjson，支持 Jackson2/3、Fastjson、Fastjson2、Gson、Hutool-json、Snack3/4

内存优化

  • ChannelContext 采用二进制位标识状态位，预留 isAccepted、isBizStatus 给业务
  • Packet 使用位域压缩，将 boolean 标志合并到 byte
  • 组级统计用 LongAdder 降低竞争；并发集合替换锁
  • TioConfig / ChannelStat / Node 按 JVM 对齐原则重排字段，减少 padding

性能优化

  • 无锁异步写入（移除 ReentrantLock）
  • gathering write 批量发送，避免缓冲区合并复制
  • SSL 解密用 slice() 替代字节复制
  • 自适应批量发送大小；滑动窗口慢包检测

网络与协议

  • UDP 统一为 UdpChannel 抽象
  • TCP Proxy Protocol v1/v2、SSL 双向认证、PKCS12 证书、服务端 backlog 配置

功能特性

  • MCP 服务端（Tools / Resources / Prompts / Sampling / Roots）
  • HttpRouter、SSE、时间轮心跳、HeartbeatTimeoutStrategy
  • module-info.java（JPMS）、SSLEngineCustomizer
  • 内置 FileQueue（支持 GraalVM）

📄 License ​

Apache License v2