# nnet 架构设计文档 ## 一、整体架构 ### 1.1 架构层次 ``` ┌─────────────────────────────────────────────────────────────┐ │ 应用层 (Application) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 路由 │ │ 中间件 │ │ 拦截器 │ │ 处理器 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ 核心层 (Core) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │连接管理 │ │Session │ │Context │ │生命周期 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ 协议层 (Protocol) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │协议管理 │ │版本管理 │ │编解码 │ │粘包拆包 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ 传输层 (Transport) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ TCP │ │ UDP │ │WebSocket │ │ Unix │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ TLS │ │ 串口 │ │ 扩展 │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ 基础设施层 (Infrastructure) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 配置 │ │ 日志 │ │ 监控 │ │ 插件 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌───────┐ │ gnet │ └───────┘ ``` ### 1.2 核心模块 #### 服务器核心（Server Core） - 配置管理 - 协议管理器 - 连接管理器 - 路由管理器 - 中间件链 - 拦截器链 - Session管理器 - 生命周期管理器 - 插件管理器 - 日志系统 - Metrics监控 服务器通过可复用的 `MetricsHandler`、`HealthHandler` 和 `ExportMetrics` 接口向外暴露监控数据，使用者需要在自有的HTTP服务中挂载这些处理器。 #### 协议层（Protocol Layer） - 协议注册和发现 - 协议版本管理 - 协议识别和选择 - 编解码器管理 - 粘包拆包处理 #### 路由系统（Router） - 字符串匹配 - 帧头匹配 - 帧数据匹配 - 自定义匹配 - 路由分组 - 路由优先级 #### 连接管理（Connection） - 连接生命周期管理 - 连接分组 - 分组广播 - 跨连接操作 #### Session管理（Session） - 数据存储 - 存储策略（内存/文件/Redis） - Session过期管理 #### Context系统（Context） - 状态管理 - 请求/响应数据 - 连接信息 - 键值对存储 ## 二、数据流程 ### 2.1 请求处理流程 ``` 客户端数据 │ ▼ [传输层接收] (gnet事件) │ ▼ [粘包拆包] (Unpacker) ──→ 处理半包/粘包，提取完整消息 │ ▼ [协议头解析] (Protocol.Decode) ──→ 提取帧头和数据体 │ ▼ [Codec选择] (CodecResolver) ──→ 优先级：版本 > 上下文/Session > Header > 原始探测 > 默认 │ ▼ [应用层解码] (Codec.Decode) ──→ 将数据体解码为结构化对象（JSON/Msgpack等）或保持原始字节（binary/plain） │ ▼ [路由匹配] (Router) ──→ 基于完全解码的数据进行匹配（Raw/Header/Data） │ ▼ [强类型解码] (Codec.Decode) ──→ 如有需要，将数据解码到路由指定的强类型结构体 │ ▼ [拦截器链] (InterceptorChain) │ ▼ [中间件链] (MiddlewareChain) │ ▼ [业务处理] (Handler) ──→ 直接同步执行，依赖Context超时控制 │ ▼ [编码] (Encoder) │ ▼ [拦截器链] (InterceptorChain) │ ▼ [传输层发送] (gnet事件) │ ▼ 客户端 ``` ### 2.2 自动解析流程 ``` 1. 数据到达 → Connection.Read() ↓ 2. 粘包拆包 → Unpacker.Unpack() → 完整消息列表 ↓ 3. 协议头解析 → Protocol.Decode() → Header + DataBytes ↓ 4. Codec选择 → CodecResolver.resolveCodecGeneric() - 优先级：协议版本 > 上下文/Session > Header.codec > 原始数据探测 > 默认(binary) ↓ 5. 应用层预解码 → Codec.Decode() → 通用对象（map/interface{}）或原始字节 ↓ 6. 路由匹配 → Router.Match() → 基于完全解码的数据（Raw/Header/Data） ↓ 7. 强类型解码（可选）→ Codec.Decode() → 路由指定的结构体类型 ↓ 8. Handler执行 → req.Data().(*MyStruct) (直接使用) ``` ### 2.3 自动编码流程 ``` 1. Handler调用 → resp.Write(struct) ↓ 2. 编解码器编码 → Codec.Encode() → []byte ↓ 3. 协议编码 → Protocol.Encode() → Header + Data ↓ 4. 写入连接 → Connection.Write() ``` ## 三、关键设计原则 ### 3.1 接口驱动设计 - 核心功能通过接口定义，便于扩展和测试 - 依赖倒置：高层模块不依赖低层模块，都依赖抽象 ### 3.2 单一职责 - 每个模块只负责一个功能 - Context只负责状态管理 - Request负责数据读取 - Response负责数据写入 ### 3.3 开闭原则 - 对扩展开放，对修改关闭 - 通过接口和插件系统扩展功能 ### 3.4 最小依赖 - 核心功能不依赖第三方库 - 可选功能通过接口隔离 ### 3.5 高性能优先 - 充分利用gnet的事件驱动模型 - 减少内存分配和GC压力 - 支持连接池和对象池 ## 四、目录结构 ``` nnet/ ├── cmd/ # 命令行工具和示例 ├── internal/ # 内部实现（不对外暴露） │ ├── server/ # 服务器核心 │ ├── protocol/ # 协议实现 │ ├── router/ # 路由实现 │ ├── middleware/ # 中间件实现 │ ├── interceptor/ # 拦截器实现 │ ├── connection/ # 连接管理 │ ├── session/ # Session管理 │ ├── codec/ # 编解码器 │ ├── unpacker/ # 粘包拆包 │ ├── client/ # 客户端实现 │ └── ... ├── pkg/ # 对外暴露的包 │ ├── nnet/ # 主包（入口） │ ├── protocol/ # 协议接口 │ ├── router/ # 路由接口 │ ├── middleware/ # 中间件接口 │ ├── interceptor/ # 拦截器接口 │ ├── connection/ # 连接接口 │ ├── session/ # Session接口 │ ├── codec/ # 编解码接口 │ └── ... ├── examples/ # 示例代码 ├── test/ # 测试代码 └── docs/ # 文档 ``` ## 五、扩展点 ### 5.1 协议扩展 - 实现`pkg/protocol/Protocol`接口 - 在`internal/protocol/`下创建新协议目录 - 注册到协议管理器 ### 5.2 匹配器扩展 - 实现`pkg/router/Matcher`接口 - 在`internal/router/matcher/`下创建新匹配器 - 注册到路由器 ### 5.3 存储扩展 - 实现`pkg/session/Storage`接口 - 在`internal/session/storage/`下创建新存储 - 注册到Session管理器 ### 5.4 插件扩展 - 实现`pkg/plugin/Plugin`接口 - 注册到插件管理器 ## 六、参考文档 - [需求文档](../requirements/REQUIREMENTS.md) - [代码结构](../development/CODE_STRUCTURE.md) - [协议设计](../implementation-details/PROTOCOL_DESIGN.md) - [路由系统](../user-guide/ROUTER_EXAMPLES.md) --- **文档版本**: v1.0 **最后更新**: 2024