---
url: https://www.dreamlu.net/mica-net.md
---

# mica-net Java 网络框架

[![Java CI](https://github.com/lets-mica/mica-net/actions/workflows/test-and-build.yml/badge.svg)](https://github.com/lets-mica/mica-net/actions/workflows/test-and-build.yml)
[![Mica net Maven release](https://img.shields.io/maven-central/v/net.dreamlu/mica-net-core.svg?style=flat-square)](https://central.sonatype.com/artifact/net.dreamlu/mica-net-core/versions)

> 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-core | TCP / UDP 通信核心，含 `TcpHandler`、`UdpHandler`、三段式编解码 |
| mica-net-http | HTTP / HTTPS / WebSocket 服务端，`HttpServerStarter` + `HttpRouter` + SSE |
| mica-net-mcp | MCP 服务端实现 |

## 📖 使用文档

> 各模块的「上手即用」文档汇集在 [使用文档索引](/mica-net/usage/) 中，与代码示例保持一致。

| 模块 | 文档主题 |
| ---- | -------- |
| mica-net-core | TCP 使用 — `AsynchronousSocketChannel` 的 TCP 通信，含服务端/客户端、心跳、SSL、PROXY Protocol、集群 |
| mica-net-core | UDP 使用 — 基于 `DatagramChannel` 的 NIO UDP，含 `UdpChannel`/`UdpHandler` 三段式协议 |
| mica-net-http | HTTP 使用 — `HttpServerStarter` + `HttpRouter` + SSE，覆盖路由/过滤器/异常/JSON |
| mica-net-http | WebSocket 使用 — `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` / `UdpHandler` | TCP/UDP 业务处理接口，强类型泛型化 |
| `ReadCompletionHandler` / `WriteCompletionHandler` | 异步读 / 写完成处理器 |
| `TcpDecodeRunnable` | TCP 解码任务（粘包/半包处理） |
| `HandlerRunnable` | 业务处理任务 |
| `TcpSendRunnable` | TCP 发送任务（批量处理、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