|
|
# 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
|
|
|
|