You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

16 KiB

Raw Blame History Unescape Escape

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 - 核心功能（必须实现）

TCP协议支持
基础路由系统（支持字符串匹配）
基础中间件系统
连接管理（基础功能）
基础配置管理
基础日志系统
协议版本管理（核心需求，包括无帧头协议支持）
编解码系统
粘包拆包处理
健康检查接口

P1 - 重要功能（应该实现）

Session管理（默认内存存储）
拦截器系统
连接分组
UDP、WebSocket协议支持
内置nnet协议
Context系统
TLS支持
路由系统扩展（帧头匹配、帧数据匹配）
内置nnet客户端
生命周期管理（Server + Connection）

P2 - 扩展功能（建议实现）

插件系统
Metrics监控（Prometheus格式）
Unix Domain Socket支持
高级配置功能
序列化格式扩展
测试完善（覆盖率80%+）

P3 - 可选功能（按需实现）

串口等扩展协议
性能优化工具
开发工具插件
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. 优雅关闭处理

四、参考项目

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

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

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