# 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 **待审核**: 待用户确认