nnet/docs/kb/requirements/REQUIREMENTS.md

# nnet 网络库 - 需求提炼文档

## 一、需求分类与提炼

### 1. 协议支持需求

#### 1.1 基础协议
- ✅ TCP协议支持
- ✅ UDP协议支持
- ✅ WebSocket协议支持
- ✅ Unix Domain Socket支持

#### 1.2 安全协议
- ✅ TLS/SSL支持（支持TLS 1.2、1.3等版本）
- ✅ 证书管理（支持证书加载、验证）

#### 1.3 扩展协议
- ✅ 串口通信支持（Serial Port）
- ✅ 命名管道支持（Named Pipe，可选）
- ✅ 其他gnet不支持的协议扩展机制

#### 1.4 协议抽象
- ✅ 统一的协议接口
- ✅ 协议注册机制
- ✅ 协议自动识别

### 2. 协议版本管理需求

#### 2.1 多版本支持
- ✅ 单协议多版本支持
- ✅ 版本自动识别
- ✅ 版本手动指定
- ✅ 版本协商机制

#### 2.2 版本识别方式
- ✅ **协议头识别**：通过固定位置的版本字段识别
- ✅ **消息头识别**：通过消息头中的版本信息识别
- ✅ **消息体识别**：通过特定消息（如设备注册消息）中的软件版本号、硬件版本号等字段识别
- ✅ **用户自定义识别**：支持用户自定义版本识别逻辑

#### 2.3 版本持久化
- ✅ 版本信息与连接绑定
- ✅ 重连后版本信息保持（通过连接标识或Session）
- ✅ 版本信息查询

#### 2.4 版本选择策略
- ✅ 自动识别优先
- ✅ 手动指定覆盖
- ✅ 版本不匹配处理

### 3. 路由系统需求（重新设计）

#### 3.1 路由匹配策略（高度可扩展）
- ✅ **基于URL/String匹配**：传统的字符串路由匹配（如："/user/login"）
- ✅ **基于协议帧头匹配**：通过协议帧头的特定字段进行路由匹配（如：消息类型、命令码等）
- ✅ **基于协议帧数据匹配**：通过协议帧数据内容的某部分进行路由匹配（如：消息体中的字段值）
- ✅ **组合匹配**：支持多种匹配策略组合使用
- ✅ **自定义匹配器**：支持用户自定义匹配逻辑

#### 3.2 路由分组
- ✅ 功能模块分组
- ✅ 权限分组
- ✅ 嵌套分组
- ✅ 分组级别的中间件绑定
- ✅ 分组可绑定匹配策略

#### 3.3 函数集式路由
- ✅ 多个处理函数组合
- ✅ 路由级别的中间件
- ✅ 路由级别的协议版本限制

#### 3.4 路由优先级
- ✅ 路由优先级设置
- ✅ 精确匹配优先于通配符
- ✅ 帧头匹配优先于帧数据匹配

### 4. 中间件系统需求

#### 4.1 中间件类型
- ✅ **全局中间件**：所有请求执行
- ✅ **路由级中间件**：特定路由执行
- ✅ **分组级中间件**：路由组执行

#### 4.2 中间件功能
- ✅ 前置中间件（Before）
- ✅ 后置中间件（After）
- ✅ 错误处理中间件（Error）
- ✅ 认证中间件（Auth）
- ✅ 限流中间件（RateLimit）
- ✅ 日志中间件（Logging）

#### 4.3 中间件链
- ✅ 中间件执行顺序控制
- ✅ 中间件中断机制
- ✅ 中间件参数传递

### 5. 数据拦截器需求

#### 5.1 拦截器链（责任链模式）
- ✅ 多个拦截器顺序执行
- ✅ 拦截器中断机制
- ✅ 拦截器条件执行

#### 5.2 拦截点
- ✅ **接收拦截**：数据接收后、解析前
- ✅ **解析拦截**：数据解析后、路由前
- ✅ **路由拦截**：路由匹配后、处理前
- ✅ **处理拦截**：业务处理中
- ✅ **响应拦截**：响应生成后、发送前

#### 5.3 拦截器功能
- ✅ 数据验证
- ✅ 数据转换
- ✅ 数据加密/解密
- ✅ 数据压缩/解压
- ✅ 数据统计

### 6. 编解码与序列化需求

#### 6.1 编解码器
- ✅ 编码器接口（Encoder）
- ✅ 解码器接口（Decoder）
- ✅ 协议级别编解码器
- ✅ 消息级别编解码器

#### 6.2 序列化格式
- ✅ JSON序列化
- ✅ Protobuf序列化（可选）
- ✅ MessagePack序列化（可选）
- ✅ Binary序列化
- ✅ 自定义序列化器

#### 6.3 序列化功能
- ✅ 结构体到字节流
- ✅ 字节流到结构体
- ✅ 序列化器注册
- ✅ 序列化器选择

### 7. 粘包拆包处理需求

#### 7.1 内置协议支持
- ✅ **固定长度协议**：固定长度的消息
- ✅ **长度字段协议**：消息前N字节表示长度（支持大端/小端）
- ✅ **分隔符协议**：通过分隔符区分消息
- ✅ **自定义帧头协议**：通过帧头识别消息边界

#### 7.2 自定义处理
- ✅ 用户自定义粘包拆包逻辑
- ✅ 多协议混合使用（通过协议识别器区分）
- ✅ 协议级别的Unpacker配置

### 8. 内置nnet协议需求

#### 8.1 协议特点
- ✅ 简单高效（最小化协议开销）
- ✅ 功能强大（满足游戏服务器、物联网等场景）
- ✅ 可扩展（支持协议版本升级）

#### 8.2 协议功能
- ✅ 消息类型区分（请求/响应/推送）
- ✅ 消息ID支持（请求-响应匹配）
- ✅ 压缩支持（可选）
- ✅ 加密支持（可选）
- ✅ 校验和（可选）

### 9. 连接管理需求

#### 9.1 连接生命周期
- ✅ 连接建立
- ✅ 连接保持
- ✅ 连接关闭
- ✅ 连接超时检测

#### 9.2 连接操作
- ✅ 读取连接数据
- ✅ 写入连接数据
- ✅ 关闭连接
- ✅ 获取连接信息（IP、端口、协议版本等）
- ✅ **跨连接操作**：在A连接的处理中操作B连接

#### 9.3 连接分组
- ✅ **服务端控制分组**：服务端主动将连接加入/移出分组
- ✅ **消息控制分组**：通过消息内容（如用户ID、设备类型）自动分组
- ✅ 分组内广播消息
- ✅ 分组查询（查询分组内的连接列表）

#### 9.4 连接标识
- ✅ 连接ID（唯一标识）
- ✅ 连接标签（支持给连接打标签，便于查询和分组）

### 10. Session管理需求

#### 10.1 Session职责（重要）
- ✅ **仅作为数据存储**：Session只负责存储键值对数据
- ✅ **不负责广播**：广播功能由连接管理器实现
- ✅ **职责分离**：Session与连接管理解耦

#### 10.2 Session存储策略
- ✅ **内存存储（Memory）**：默认实现，高性能（默认使用）
- ✅ **文件存储（File）**：持久化到本地文件
- ✅ **Redis存储**：分布式Session支持
- ✅ **自定义存储**：用户可实现自定义存储策略

#### 10.3 Session操作
- ✅ 创建Session
- ✅ 获取Session
- ✅ 更新Session
- ✅ 删除Session
- ✅ Session过期管理

#### 10.4 Session与连接关联
- ✅ 连接可获取关联的Session
- ✅ Session可获取关联的连接（通过连接管理器）
- ✅ 支持一个Session关联多个连接（如多设备登录）

### 11. Context系统需求

#### 11.1 Context类型
- ✅ 请求上下文（包含请求相关信息）
- ✅ 连接上下文（包含连接相关信息）
- ✅ 用户上下文（包含用户相关信息）
- ✅ 协议上下文（包含协议版本、编解码器等信息）

#### 11.2 Context功能
- ✅ Context值设置和获取
- ✅ Context在中间件、拦截器、处理器之间传递
- ✅ Context超时和取消
- ✅ 用户自定义Context字段

### 12. 配置管理需求

#### 12.1 配置来源
- ✅ 配置文件（JSON、YAML、TOML等格式）
- ✅ 环境变量
- ✅ 代码配置
- ✅ 配置优先级：代码配置 > 环境变量 > 配置文件 > 默认值

#### 12.2 配置项
- ✅ 服务器配置（监听地址、端口、协议类型等）
- ✅ 性能配置（连接数限制、缓冲区大小、超时时间等）
- ✅ 协议配置（协议版本、编解码器选择等）
- ✅ 中间件配置（中间件的启用/禁用、参数配置）
- ✅ Session配置（存储策略、过期时间等）
- ✅ 日志配置（日志级别、输出格式等）
- ✅ Metrics配置（监控指标配置）

### 13. 日志系统需求

#### 13.1 日志接口（日志门面）
- ✅ 统一的日志接口
- ✅ 日志级别（Debug、Info、Warn、Error、Fatal）
- ✅ 结构化日志
- ✅ 日志字段（Fields）

#### 13.2 默认实现
- ✅ 使用Go标准库log实现
- ✅ 日志输出到控制台、文件

#### 13.3 第三方集成
- ✅ logrus集成
- ✅ zap集成
- ✅ zerolog集成
- ✅ 用户自定义日志实现

#### 13.4 日志配置
- ✅ 日志级别控制
- ✅ 日志格式配置
- ✅ 日志轮转配置

### 14. 指标监控需求

#### 14.1 监控协议
- ✅ **Prometheus格式**：仅支持Prometheus格式（业内最流行）

#### 14.2 监控指标
- ✅ 连接数（当前连接数、总连接数、连接建立速率）
- ✅ 请求数（请求总数、请求速率、请求耗时分布）
- ✅ 错误数（错误总数、错误率、错误类型分布）
- ✅ 流量（接收字节数、发送字节数、流量速率）
- ✅ 协议统计（各协议版本的请求数、错误数）

#### 14.3 指标导出
- ✅ HTTP端点导出（/metrics）
- ✅ 推送到监控系统（可选）
- ✅ 自定义指标

### 15. 插件系统需求

#### 15.1 插件接口
- ✅ 标准的插件接口
- ✅ 插件生命周期（初始化、启动、停止、销毁）

#### 15.2 插件类型
- ✅ **协议插件**：扩展新的协议支持
- ✅ **中间件插件**：提供可复用的中间件
- ✅ **编解码插件**：提供新的编解码器
- ✅ **存储插件**：提供新的Session存储实现
- ✅ **监控插件**：扩展监控功能
- ✅ **工具插件**：提供开发工具和辅助功能

#### 15.3 插件管理
- ✅ 插件注册
- ✅ 插件加载（支持动态加载）
- ✅ 插件卸载
- ✅ 插件依赖管理

#### 15.4 插件应用场景示例
- ✅ **协议转换插件**：将HTTP协议转换为内部协议
- ✅ **数据统计插件**：统计特定业务数据
- ✅ **消息队列插件**：将消息推送到消息队列
- ✅ **缓存插件**：提供缓存功能
- ✅ **限流插件**：提供限流功能

### 16. 生命周期管理需求

#### 16.1 Server生命周期阶段
- ✅ **初始化（Init）**：配置加载、组件初始化
- ✅ **启动前（BeforeStart）**：启动前的准备工作
- ✅ **启动（Start）**：服务启动，开始监听
- ✅ **运行中（Running）**：服务正常运行
- ✅ **停止前（BeforeStop）**：停止前的清理工作
- ✅ **停止（Stop）**：服务停止，停止监听
- ✅ **销毁（Destroy）**：资源释放

#### 16.2 Connection生命周期阶段
- ✅ **连接建立（OnOpen）**：连接建立时触发
- ✅ **数据接收（OnTraffic）**：数据到达时触发
- ✅ **连接关闭（OnClose）**：连接关闭时触发
- ✅ **连接错误（OnError）**：连接错误时触发

#### 16.3 生命周期钩子
- ✅ 在每个阶段注册钩子函数
- ✅ 钩子函数的执行顺序控制
- ✅ 钩子函数的错误处理

#### 16.4 优雅关闭
- ✅ 优雅关闭（Graceful Shutdown）
- ✅ 等待正在处理的请求完成
- ✅ 关闭空闲连接
- ✅ 资源清理

### 17. 客户端支持需求

#### 17.1 内置nnet客户端
- ✅ 支持TCP、UDP、WebSocket等协议连接
- ✅ 支持TLS连接
- ✅ 支持协议版本协商
- ✅ 支持自动重连
- ✅ 支持连接池

#### 17.2 客户端功能
- ✅ 请求-响应模式（同步/异步）
- ✅ 异步消息推送
- ✅ 连接状态管理
- ✅ 超时控制
- ✅ 错误处理

### 18. 健康检查需求

#### 18.1 健康检查接口
- ✅ 提供简单的HTTP健康检查接口（/health）
- ✅ 返回服务状态（健康/不健康）
- ✅ 可扩展健康检查逻辑

#### 18.2 健康检查内容
- ✅ 服务运行状态
- ✅ 连接数统计
- ✅ 资源使用情况（可选）

### 19. Shell连接支持需求（低优先级）

#### 19.1 Shell连接功能
- ✅ 支持Shell连接建立
- ✅ 支持Shell命令执行
- ✅ 支持子进程管理
- ✅ 支持数据传输
- ✅ 支持连接控制

#### 19.2 应用场景
- ✅ 远程命令执行
- ✅ 系统管理
- ✅ 调试工具

### 20. 测试需求

#### 20.1 测试类型
- ✅ 单元测试（各模块的单元测试）
- ✅ 集成测试（模块间的集成测试）
- ✅ 性能测试（压力测试、性能基准测试）

#### 20.2 测试工具
- ✅ 测试辅助工具
- ✅ Mock对象
- ✅ 测试覆盖率统计

#### 20.3 测试覆盖率
- ✅ **测试覆盖率目标：80%+**

### 21. 代码质量需求

#### 21.1 性能要求
- ✅ 充分利用gnet的事件驱动模型
- ✅ 减少内存分配和GC压力
- ✅ 支持连接池和对象池
- ✅ 高性能的序列化/反序列化

#### 21.2 可扩展性
- ✅ 模块化设计，低耦合高内聚
- ✅ 接口驱动，便于扩展
- ✅ 插件化架构，支持功能扩展

#### 21.3 可维护性
- ✅ 代码简洁清晰
- ✅ 充分的注释和文档
- ✅ 遵循Go代码规范

#### 21.4 依赖管理
- ✅ 最小化外部依赖
- ✅ 核心功能不依赖第三方库
- ✅ 可选功能通过接口隔离，支持可选依赖

#### 21.5 新特性使用
- ✅ 充分利用Golang 1.25.4新特性
- ✅ 充分利用gnet 2.9.5新特性

## 二、需求优先级

### P0 - 核心功能（必须实现）
1. TCP协议支持
2. 基础路由系统（支持字符串匹配）
3. 基础中间件系统
4. 连接管理（基础功能）
5. 基础配置管理
6. 基础日志系统
7. 协议版本管理（核心需求，包括无帧头协议支持）
8. 编解码系统
9. 粘包拆包处理
10. 健康检查接口

### P1 - 重要功能（应该实现）
1. Session管理（默认内存存储）
2. 拦截器系统
3. 连接分组
4. UDP、WebSocket协议支持
5. 内置nnet协议
6. Context系统
7. TLS支持
8. 路由系统扩展（帧头匹配、帧数据匹配）
9. 内置nnet客户端
10. 生命周期管理（Server + Connection）

### P2 - 扩展功能（建议实现）
1. 插件系统
2. Metrics监控（Prometheus格式）
3. Unix Domain Socket支持
4. 高级配置功能
5. 序列化格式扩展
6. 测试完善（覆盖率80%+）

### P3 - 可选功能（按需实现）
1. 串口等扩展协议
2. 性能优化工具
3. 开发工具插件
4. Shell连接支持（低优先级）

## 三、特殊需求说明

### 3.1 单协议多版本识别
- **需求背景**：在实际开发中，某些协议由于历史原因，未在协议头设计版本字段，但可能在特定消息体（如设备注册消息）中包含软件版本号、硬件版本号等信息
- **特殊场景**：有些自定义协议没有帧头、帧内容区分，版本识别策略需要考虑这种场景
- **解决方案**：
  1. 支持通过协议头、消息头识别版本（适用于有帧头的协议）
  2. 支持通过特定消息的消息体内容识别版本
  3. 支持通过消息内容特征识别版本（适用于无帧头/帧内容区分的协议）：
     - 通过消息内容的特征识别（如：特定字段的位置、值）
     - 通过消息长度识别
     - 通过消息格式识别（如：JSON结构、字段名等）
     - 通过用户自定义的识别逻辑
  4. 版本识别后与连接绑定，重连后无需重新识别（通过连接标识或Session）

### 3.2 Session职责分离
- **需求背景**：Session应该只作为数据存储功能存在，广播功能应该在连接管理器中实现
- **解决方案**：
  1. Session接口只提供数据存储功能（Get/Set/Delete）
  2. 广播功能在ConnectionManager中实现
  3. 连接可以通过ConnectionManager获取其他连接，进而获取其他连接的Session

### 3.3 插件系统作用
- **应用场景**：
  1. 协议转换（如HTTP转内部协议）
  2. 数据统计和监控
  3. 消息队列集成
  4. 缓存功能扩展
  5. 限流功能扩展
  6. 数据同步功能

### 3.4 生命周期管理
- **目的**：确保系统资源的正确初始化和释放
- **应用场景**：
  1. 数据库连接初始化
  2. 缓存连接初始化
  3. 定时任务启动
  4. 优雅关闭处理

## 四、参考项目

建议参考以下优秀开源项目的设计：

1. **Gin**：路由设计、中间件系统
2. **Echo**：Context设计、中间件链
3. **Fiber**：性能优化、API设计
4. **gnet**：事件驱动模型、高性能实现
5. **gRPC**：协议设计、编解码
6. **Kratos**：架构设计、插件系统
7. **Go-zero**：配置管理、中间件设计

---

**文档版本**: v1.0  
**创建日期**: 2024  
**待审核**: 待用户确认