# nnet 网络库 - 需求提炼与设计方案 ## 一、需求提炼与整合 ### 1. 核心功能模块 #### 1.1 多协议支持层 - **基础协议**：TCP、UDP、WebSocket、Unix Domain Socket - **安全协议**：TLS/SSL（支持多种TLS版本和配置） - **扩展协议**：串口通信（Serial Port）、命名管道（Named Pipe）等gnet不直接支持的协议 - **协议抽象**：统一的协议接口，便于扩展新协议类型 #### 1.2 协议版本管理系统 - **多版本识别机制**： - 协议头识别：通过固定位置的版本字段识别 - 消息头识别：通过消息头中的版本信息识别 - 消息体识别：通过特定消息（如设备注册消息）中的软件版本号、硬件版本号等字段识别 - 用户自定义识别：支持用户自定义版本识别逻辑 - **版本选择策略**： - 自动识别：系统自动根据识别规则选择版本 - 手动指定：允许用户手动指定协议版本 - 版本协商：支持客户端与服务端进行版本协商 - **版本持久化**：连接建立后，版本信息与连接绑定，重连时无需重新识别（通过连接标识或Session） #### 1.3 路由系统（重新设计） - **路由匹配策略**（高度可扩展）： - **基于URL/String匹配**：传统的字符串路由匹配（如："/user/login"） - **基于协议帧头匹配**：通过协议帧头的特定字段进行路由匹配（如：消息类型、命令码等） - **基于协议帧数据匹配**：通过协议帧数据内容的某部分进行路由匹配（如：消息体中的字段值） - **组合匹配**：支持多种匹配策略组合使用 - **自定义匹配器**：支持用户自定义匹配逻辑 - **路由分组**： - 按功能模块分组（如：用户模块、设备模块） - 按权限分组（如：公开路由、认证路由） - 支持嵌套分组（分组内可再分组） - 分组可绑定匹配策略 - **函数集式路由**： - 支持多个处理函数组合成路由链 - 支持路由级别的中间件绑定 - 支持路由级别的协议版本限制 - **路由优先级**： - 支持路由优先级设置 - 精确匹配优先于通配符 - 帧头匹配优先于帧数据匹配 #### 1.4 中间件系统 - **全局中间件**： - 在所有请求处理前后执行 - 支持中间件链的执行顺序控制 - 支持中间件的启用/禁用 - **路由级中间件**： - 绑定到特定路由或路由组 - 支持中间件参数传递 - **中间件类型**： - 前置中间件（Before）：请求处理前执行 - 后置中间件（After）：请求处理后执行 - 错误处理中间件（Error）：异常捕获和处理 - 认证中间件（Auth）：身份验证 - 限流中间件（RateLimit）：请求限流 - 日志中间件（Logging）：请求日志记录 #### 1.5 数据报文拦截器（责任链模式） - **拦截器链**： - 支持多个拦截器按顺序执行 - 支持拦截器的中断（提前返回） - 支持拦截器的跳过（条件执行） - **拦截点**： - 接收拦截：数据接收后、解析前 - 解析拦截：数据解析后、路由前 - 路由拦截：路由匹配后、处理前 - 处理拦截：业务处理中 - 响应拦截：响应生成后、发送前 - **拦截器功能**： - 数据验证 - 数据转换 - 数据加密/解密 - 数据压缩/解压 - 数据统计 #### 1.6 编解码与序列化系统 - **编解码器接口**： - 编码器（Encoder）：将消息对象编码为字节流 - 解码器（Decoder）：将字节流解码为消息对象 - 支持协议级别的编解码器 - 支持消息级别的编解码器 - **序列化器**： - 支持多种序列化格式：JSON、Protobuf、MessagePack、Binary等 - 支持自定义序列化器 - 结构体到字节流的序列化 - 字节流到结构体的反序列化 - **粘包拆包处理**： - 内置支持常见协议： - 固定长度协议 - 长度字段协议（支持大端/小端） - 分隔符协议 - 自定义帧头协议 - 支持用户自定义粘包拆包逻辑 - 支持多协议混合使用（通过协议识别器区分） #### 1.7 内置nnet协议 - **协议特点**： - 简单高效：最小化协议开销 - 功能强大：支持游戏服务器、物联网等场景 - 可扩展：支持协议版本升级 - **协议格式**（建议）： ``` [Magic(2B)][Version(1B)][Type(1B)][Length(4B)][Payload(NB)][Checksum(2B)] ``` - **协议功能**： - 消息类型区分（请求/响应/推送） - 消息ID支持（请求-响应匹配） - 压缩支持（可选） - 加密支持（可选） #### 1.8 连接管理系统 - **连接生命周期管理**： - 连接建立 - 连接保持 - 连接关闭 - 连接超时检测 - **连接操作**： - 读取连接数据 - 写入连接数据 - 关闭连接 - 获取连接信息（IP、端口、协议版本等） - 跨连接操作：在A连接的处理中操作B连接 - **连接分组**： - 服务端控制分组：服务端主动将连接加入/移出分组 - 消息控制分组：通过消息内容（如用户ID、设备类型）自动分组 - 分组操作：向分组内所有连接广播消息 - 分组查询：查询分组内的连接列表 - **连接标识**： - 连接ID：唯一标识一个连接 - 连接标签：支持给连接打标签，便于查询和分组 #### 1.9 Session管理系统 - **Session职责**： - **仅作为数据存储**：Session只负责存储键值对数据 - **不负责广播**：广播功能由连接管理器实现 - **职责分离**：Session与连接管理解耦 - **Session存储策略**： - **内存存储（Memory）**：默认实现，高性能（默认使用） - 文件存储（File）：持久化到本地文件 - Redis存储：分布式Session支持 - 自定义存储：用户可实现自定义存储策略 - **Session操作**： - 创建Session - 获取Session - 更新Session - 删除Session - Session过期管理 - **Session与连接关联**： - 连接可获取关联的Session - Session可获取关联的连接（通过连接管理器） - 支持一个Session关联多个连接（如多设备登录） #### 1.10 Context系统 - **丰富的Context功能**： - 请求上下文：包含请求相关的所有信息 - 连接上下文：包含连接相关的信息 - 用户上下文：包含用户相关的信息 - 协议上下文：包含协议版本、编解码器等信息 - **Context传递**： - 在中间件、拦截器、处理器之间传递 - 支持Context值的设置和获取 - 支持Context的超时和取消 - **Context扩展**： - 支持用户自定义Context字段 - 支持Context的序列化和反序列化（用于跨进程传递） #### 1.11 配置管理系统 - **配置来源**： - 配置文件：支持JSON、YAML、TOML等格式 - 环境变量：支持从环境变量读取配置 - 代码配置：支持通过代码直接配置 - 配置优先级：代码配置 > 环境变量 > 配置文件 > 默认值 - **配置项**： - 服务器配置：监听地址、端口、协议类型等 - 性能配置：连接数限制、缓冲区大小、超时时间等 - 协议配置：协议版本、编解码器选择等 - 中间件配置：中间件的启用/禁用、参数配置 - Session配置：存储策略、过期时间等 - 日志配置：日志级别、输出格式等 - Metrics配置：监控指标配置 #### 1.12 日志系统（日志门面） - **日志接口**： - 定义统一的日志接口 - 支持日志级别：Debug、Info、Warn、Error、Fatal - 支持结构化日志 - 支持日志字段（Fields） - **默认实现**： - 使用Go标准库log实现 - 支持日志输出到控制台、文件 - **第三方集成**： - 支持logrus - 支持zap - 支持zerolog - 支持用户自定义日志实现 - **日志配置**： - 日志级别控制 - 日志格式配置 - 日志轮转配置 #### 1.13 指标监控（Metrics） - **监控协议**： - **Prometheus格式**：仅支持Prometheus格式（业内最流行） - **监控指标**： - 连接数：当前连接数、总连接数、连接建立速率 - 请求数：请求总数、请求速率、请求耗时分布 - 错误数：错误总数、错误率、错误类型分布 - 流量：接收字节数、发送字节数、流量速率 - 协议统计：各协议版本的请求数、错误数 - **指标导出**： - 提供HTTP Handler（推荐挂载 `/metrics`）由使用者的HTTP服务调用 - 支持直接写出Prometheus文本以适配自定义传输（`ExportMetrics`） - 支持自定义指标 #### 1.14 插件系统 - **插件接口**： - 定义标准的插件接口 - 支持插件的初始化、启动、停止、销毁 - **插件类型**： - **协议插件**：扩展新的协议支持 - **中间件插件**：提供可复用的中间件 - **编解码插件**：提供新的编解码器 - **存储插件**：提供新的Session存储实现 - **监控插件**：扩展监控功能 - **工具插件**：提供开发工具和辅助功能 - **插件管理**： - 插件注册 - 插件加载（支持动态加载） - 插件卸载 - 插件依赖管理 - **插件示例场景**： - **协议转换插件**：将HTTP协议转换为内部协议 - **数据统计插件**：统计特定业务数据 - **消息队列插件**：将消息推送到消息队列 - **缓存插件**：提供缓存功能 - **限流插件**：提供限流功能 #### 1.15 生命周期管理 - **Server生命周期阶段**： 1. **初始化（Init）**：配置加载、组件初始化 2. **启动前（BeforeStart）**：启动前的准备工作 3. **启动（Start）**：服务启动，开始监听 4. **运行中（Running）**：服务正常运行 5. **停止前（BeforeStop）**：停止前的清理工作 6. **停止（Stop）**：服务停止，停止监听 7. **销毁（Destroy）**：资源释放 - **Connection生命周期阶段**： 1. **连接建立（OnOpen）**：连接建立时触发 2. **数据接收（OnTraffic）**：数据到达时触发 3. **连接关闭（OnClose）**：连接关闭时触发 4. **连接错误（OnError）**：连接错误时触发 - **生命周期钩子**： - 支持Server生命周期钩子注册 - 支持Connection生命周期钩子注册 - 支持钩子函数的执行顺序控制 - 支持钩子函数的错误处理 - **优雅关闭**： - 支持优雅关闭（Graceful Shutdown） - 等待正在处理的请求完成 - 关闭空闲连接 - 资源清理 #### 1.16 客户端支持 - **内置nnet客户端**： - 支持TCP、UDP、WebSocket等协议连接 - 支持TLS连接 - 支持协议版本协商 - 支持自动重连 - 支持连接池 - **客户端功能**： - 请求-响应模式 - 异步消息推送 - 连接状态管理 - 超时控制 - 错误处理 #### 1.17 健康检查接口 - **健康检查端点**： - 提供简单的HTTP健康检查接口（/health） - 返回服务状态（健康/不健康） - 可扩展健康检查逻辑 - **健康检查内容**： - 服务运行状态 - 连接数统计 - 资源使用情况（可选） #### 1.18 Shell连接支持（低优先级） - **Shell连接功能**： - 支持Shell连接建立 - 支持Shell命令执行 - 支持子进程管理 - 支持数据传输 - 支持连接控制 - **应用场景**： - 远程命令执行 - 系统管理 - 调试工具 #### 1.19 测试支持 - **单元测试**：各模块的单元测试 - **集成测试**：模块间的集成测试 - **性能测试**：压力测试、性能基准测试 - **测试工具**：提供测试辅助工具和Mock对象 - **测试覆盖率**：目标80%+ ### 2. 非功能性需求 #### 2.1 性能要求 - 充分利用gnet的事件驱动模型 - 减少内存分配和GC压力 - 支持连接池和对象池 - 高性能的序列化/反序列化 #### 2.2 可扩展性 - 模块化设计，低耦合高内聚 - 接口驱动，便于扩展 - 插件化架构，支持功能扩展 #### 2.3 可维护性 - 代码简洁清晰 - 充分的注释和文档 - 遵循Go代码规范 #### 2.4 依赖管理 - 最小化外部依赖 - 核心功能不依赖第三方库 - 可选功能通过接口隔离，支持可选依赖 ## 二、架构设计 ### 2.1 整体架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 应用层 (Application) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 路由 │ │ 中间件 │ │ 拦截器 │ │ 处理器 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ 核心层 (Core) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │连接管理 │ │Session │ │Context │ │生命周期 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ 协议层 (Protocol) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │协议管理 │ │版本管理 │ │编解码 │ │粘包拆包 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ 传输层 (Transport) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ TCP │ │ UDP │ │WebSocket │ │ Unix │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ TLS │ │ 串口 │ │ 扩展 │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ 基础设施层 (Infrastructure) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 配置 │ │ 日志 │ │ 监控 │ │ 插件 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌───────┐ │ gnet │ └───────┘ ``` ### 2.2 核心模块设计 #### 2.2.1 服务器核心（Server Core） ```go // 伪代码示例 type Server struct { // 配置 config *Config // 协议管理器 protocolManager *ProtocolManager // 连接管理器 connManager *ConnectionManager // 路由管理器 router *Router // 中间件链 middlewares []Middleware // 拦截器链 interceptors []Interceptor // Session管理器 sessionManager *SessionManager // 生命周期管理器 lifecycle *Lifecycle // 插件管理器 pluginManager *PluginManager // 日志 logger Logger // Metrics metrics Metrics } ``` #### 2.2.2 协议管理器（Protocol Manager） - **职责**： - 协议注册和发现 - 协议版本管理 - 协议识别和选择 - 编解码器管理 - **关键接口**： ```go type Protocol interface { Name() string Versions() []Version Identify(data []byte) (Version, error) CreateCodec(version Version) (Codec, error) } type Version interface { Version() string Identify(data []byte) bool } ``` #### 2.2.3 连接管理器（Connection Manager） - **职责**： - 连接的创建、维护、销毁 - 连接分组管理 - 连接查询和操作 - 跨连接操作 - **关键接口**： ```go type ConnectionManager interface { Add(conn Connection) error Remove(connID string) error Get(connID string) (Connection, error) Group(groupID string) ConnectionGroup Broadcast(groupID string, data []byte) error } type Connection interface { ID() string Write(data []byte) error Close() error Context() Context Session() Session } ``` #### 2.2.4 路由管理器（Router）- 重新设计 - **职责**： - 路由注册和匹配（支持多种匹配策略） - 路由分组管理 - 路由中间件绑定 - **关键接口**： ```go // 路由匹配器接口 type Matcher interface { Match(input MatchInput, ctx Context) bool Priority() int // 优先级，数字越大优先级越高 } // 字符串匹配器（传统URL匹配） type StringMatcher struct { pattern string } // 帧头匹配器（基于协议帧头） type FrameHeaderMatcher struct { field string // 字段名（如：消息类型、命令码） operator string // 操作符（如：==、!=、>、<等） value interface{} } // 帧数据匹配器（基于协议帧数据内容） type FrameDataMatcher struct { path string // 数据路径（如：JSON路径、字段路径） operator string // 操作符 value interface{} } // 自定义匹配器 type CustomMatcher struct { fn func(input MatchInput, ctx Context) bool } // 路由接口 type Router interface { // 注册路由（使用匹配器） Register(matcher Matcher, handler Handler) Route // 便捷方法：字符串匹配 RegisterString(pattern string, handler Handler) Route // 便捷方法：帧头匹配 RegisterFrameHeader(field string, operator string, value interface{}, handler Handler) Route // 便捷方法：帧数据匹配 RegisterFrameData(path string, operator string, value interface{}, handler Handler) Route // 路由分组 Group() RouterGroup // 路由匹配 Match(input MatchInput, ctx Context) (Handler, []Matcher, error) } ``` #### 2.2.5 Session管理器（Session Manager） - **职责**： - Session的创建、获取、更新、删除 - Session存储策略管理 - Session过期管理 - **关键接口**： ```go type SessionManager interface { Create(connID string) (Session, error) Get(sessionID string) (Session, error) Delete(sessionID string) error } type Session interface { ID() string Get(key string) (interface{}, error) Set(key string, value interface{}) error Delete(key string) error } ``` ### 2.3 数据流设计 ``` 客户端数据 │ ▼ [传输层接收] (gnet事件) │ ▼ [协议识别] (ProtocolManager) │ ▼ [粘包拆包] (Unpacker) │ ▼ [版本识别] (VersionManager) ──→ [版本持久化] │ ▼ [解码] (Decoder) │ ▼ [拦截器链] (InterceptorChain) │ ▼ [路由匹配] (Router) │ ▼ [中间件链] (MiddlewareChain) │ ▼ [业务处理] (Handler) │ ▼ [编码] (Encoder) │ ▼ [拦截器链] (InterceptorChain) │ ▼ [传输层发送] (gnet事件) │ ▼ 客户端 ``` ### 2.4 目录结构设计 ``` nnet/ ├── cmd/ # 命令行工具和示例 │ ├── server/ # 服务器示例 │ └── client/ # 客户端示例 ├── internal/ # 内部实现（不对外暴露） │ ├── server/ # 服务器核心 │ ├── protocol/ # 协议实现 │ │ ├── tcp/ # TCP协议 │ │ ├── udp/ # UDP协议 │ │ ├── websocket/ # WebSocket协议 │ │ ├── unix/ # Unix Domain Socket │ │ ├── tls/ # TLS协议 │ │ ├── serial/ # 串口协议 │ │ └── nnet/ # 内置nnet协议 │ ├── router/ # 路由实现 │ ├── middleware/ # 中间件实现 │ ├── interceptor/ # 拦截器实现 │ ├── connection/ # 连接管理 │ ├── session/ # Session管理 │ │ ├── memory/ # 内存存储 │ │ ├── file/ # 文件存储 │ │ └── redis/ # Redis存储 │ ├── codec/ # 编解码器 │ ├── unpacker/ # 粘包拆包 │ ├── version/ # 版本管理 │ ├── config/ # 配置管理 │ ├── logger/ # 日志实现 │ ├── metrics/ # 指标监控 │ ├── plugin/ # 插件系统 │ └── lifecycle/ # 生命周期 ├── pkg/ # 对外暴露的包 │ ├── nnet/ # 主包 │ ├── protocol/ # 协议接口 │ ├── router/ # 路由接口 │ ├── middleware/ # 中间件接口 │ ├── interceptor/ # 拦截器接口 │ ├── connection/ # 连接接口 │ ├── session/ # Session接口 │ ├── codec/ # 编解码接口 │ └── context/ # Context接口 ├── examples/ # 示例代码 ├── test/ # 测试代码 ├── docs/ # 文档 ├── go.mod ├── go.sum └── README.md ``` ## 三、关键技术设计 ### 3.1 协议版本识别策略 #### 3.1.1 识别时机 1. **连接建立时**：通过握手消息识别 2. **首次消息时**：通过第一个消息识别 3. **特定消息时**：通过包含版本信息的特定消息识别 #### 3.1.2 识别方式 ```go type VersionIdentifier interface { // 通过协议头识别（适用于有帧头的协议） IdentifyByHeader(data []byte) (Version, bool) // 通过消息头识别（适用于有消息头的协议） IdentifyByMessageHeader(msg Message) (Version, bool) // 通过消息体识别（如设备注册消息中的硬件版本号） IdentifyByMessageBody(msg Message) (Version, bool) // 用户自定义识别（适用于无帧头/帧内容区分的协议） IdentifyCustom(data []byte, ctx Context) (Version, bool) } // 对于无帧头/帧内容区分的协议 // 可以通过以下方式识别： // 1. 通过消息内容的特征识别（如：特定字段的位置、值） // 2. 通过消息长度识别 // 3. 通过消息格式识别（如：JSON结构、字段名等） // 4. 通过用户自定义的识别逻辑 ``` #### 3.1.3 版本持久化 - 版本信息与连接ID绑定 - 存储在连接上下文中 - 支持通过Session持久化（跨重连） #### 3.1.4 无帧头协议的特殊处理 - **识别策略**： - 对于没有帧头、帧内容区分的协议，版本识别需要基于： - 消息内容的特征（字段位置、值、格式等） - 消息长度 - 消息结构（JSON结构、字段名等） - 用户自定义识别逻辑 - **实现方式**： - 提供灵活的版本识别接口 - 支持基于消息内容的版本识别 - 支持延迟识别（等待足够信息后再识别） ### 3.2 粘包拆包解决方案 #### 3.2.1 内置协议支持 ```go type Unpacker interface { // 从缓冲区中提取完整消息 Unpack(buffer []byte) ([]Message, []byte, error) } // 内置实现 type FixedLengthUnpacker struct { length int } type LengthFieldUnpacker struct { offset int length int endian Endian } type DelimiterUnpacker struct { delimiter []byte } type FrameHeaderUnpacker struct { headerSize int lengthOffset int } ``` #### 3.2.2 协议识别与粘包拆包 - 每个协议版本可配置独立的Unpacker - 支持协议级别的Unpacker选择 - 支持动态Unpacker切换（协议升级场景） ### 3.3 中间件与拦截器区别 - **中间件（Middleware）**： - 作用在请求-响应层面 - 可以修改请求和响应 - 可以中断请求处理 - 主要用于：认证、限流、日志、错误处理等 - **拦截器（Interceptor）**： - 作用在数据报文层面 - 可以修改原始数据 - 可以用于：数据验证、数据转换、数据加密等 - 更底层，在编解码前后执行 ### 3.4 插件系统应用场景 1. **协议转换插件**： - 将HTTP请求转换为内部协议 - 将MQTT消息转换为内部协议 2. **数据统计插件**： - 统计业务指标（如：用户在线时长、消息发送量） - 将统计数据推送到监控系统 3. **消息队列插件**： - 将消息异步推送到Kafka、RabbitMQ等 - 实现消息的持久化和异步处理 4. **缓存插件**： - 提供分布式缓存功能 - 缓存热点数据，提升性能 5. **限流插件**： - 实现多种限流算法（令牌桶、漏桶等） - 支持分布式限流 6. **数据同步插件**： - 将数据同步到数据库 - 实现数据的持久化 ### 3.5 生命周期钩子设计 ```go // Server生命周期钩子 type ServerLifecycleHook interface { OnInit(server *Server) error OnBeforeStart(server *Server) error OnStart(server *Server) error OnRunning(server *Server) error OnBeforeStop(server *Server) error OnStop(server *Server) error OnDestroy(server *Server) error } // Connection生命周期钩子 type ConnectionLifecycleHook interface { OnOpen(conn Connection) error OnTraffic(conn Connection, data []byte) error OnClose(conn Connection) error OnError(conn Connection, err error) error } // 使用示例 server.AddServerLifecycleHook(&MyServerHook{}) server.AddConnectionLifecycleHook(&MyConnectionHook{}) ``` ### 3.6 gnet集成设计 - **充分利用gnet的事件循环**： - 使用gnet的OnOpen、OnClose、OnTraffic事件 - 在OnTraffic中处理数据接收 - 使用gnet的Write方法发送数据 - **连接封装**： - 将gnet的连接封装为nnet的Connection接口 - 保持gnet的高性能特性 - **多协议支持**： - 通过gnet的Engine支持TCP/UDP - WebSocket通过HTTP升级实现 - Unix Domain Socket通过gnet支持 - 串口等通过独立实现，统一接口 ## 四、实现优先级建议 ### Phase 1: 核心功能（MVP） 1. TCP协议支持 2. 基础路由系统（支持字符串匹配） 3. 基础中间件系统 4. 连接管理（基础功能） 5. 基础配置管理 6. 基础日志系统 7. 健康检查接口 ### Phase 2: 协议与数据处理 1. 协议版本管理（包括无帧头协议支持） 2. 编解码系统 3. 粘包拆包处理 4. 内置nnet协议 5. UDP、WebSocket协议支持 6. 路由系统扩展（帧头匹配、帧数据匹配） ### Phase 3: 高级功能 1. Session管理（默认内存存储） 2. 拦截器系统 3. 连接分组 4. TLS支持 5. Unix Domain Socket支持 6. 内置nnet客户端 7. 生命周期管理（Server + Connection） ### Phase 4: 扩展功能 1. 插件系统 2. Metrics监控（Prometheus格式） 3. 串口等扩展协议 4. 高级配置功能 5. 测试完善（覆盖率80%+） ### Phase 5: 优化与完善 1. 性能优化 2. 文档完善 3. 示例代码 4. 最佳实践 5. Shell连接支持（低优先级） ## 五、设计原则 1. **接口驱动设计**：核心功能通过接口定义，便于扩展和测试 2. **依赖倒置**：高层模块不依赖低层模块，都依赖抽象 3. **单一职责**：每个模块只负责一个功能 4. **开闭原则**：对扩展开放，对修改关闭 5. **最小依赖**：核心功能不依赖第三方库 6. **高性能优先**：充分利用gnet的性能特性 7. **易用性**：提供简洁的API，降低使用门槛 ## 六、客户端设计 ### 6.1 客户端架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 客户端应用层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 请求发送 │ │ 响应接收 │ │ 消息推送 │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ 客户端核心层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │连接管理 │ │协议管理 │ │编解码 │ │重连管理 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────┐ │ 传输层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ TCP │ │ UDP │ │WebSocket │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 6.2 客户端接口设计 ```go // 客户端接口 type Client interface { // 连接服务器 Connect(addr string) error // 断开连接 Disconnect() error // 发送请求（同步） Request(data []byte, timeout time.Duration) ([]byte, error) // 发送请求（异步） RequestAsync(data []byte, callback func([]byte, error)) error // 发送消息（无需响应） Send(data []byte) error // 注册消息处理器 OnMessage(handler func([]byte)) // 注册连接状态变化处理器 OnConnect(handler func()) OnDisconnect(handler func()) OnError(handler func(error)) // 获取连接状态 IsConnected() bool // 关闭客户端 Close() error } // 客户端配置 type ClientConfig struct { // 服务器地址 Addr string // 协议类型 Protocol string // TLS配置 TLS *TLSConfig // 重连配置 Reconnect *ReconnectConfig // 超时配置 Timeout time.Duration // 连接池配置 Pool *PoolConfig } ``` ### 6.3 客户端使用示例 ```go // 创建客户端 client := nnet.NewClient(&nnet.ClientConfig{ Addr: "tcp://127.0.0.1:8080", Protocol: "nnet", Timeout: 5 * time.Second, }) // 注册消息处理器 client.OnMessage(func(data []byte) { fmt.Println("收到消息:", string(data)) }) // 连接服务器 err := client.Connect("tcp://127.0.0.1:8080") if err != nil { log.Fatal(err) } // 发送请求 response, err := client.Request([]byte("hello"), 5*time.Second) if err != nil { log.Fatal(err) } // 关闭客户端 client.Close() ``` --- **设计文档版本**: v1.1 **设计日期**: 2024 **设计者**: AI Assistant **状态**: 已根据用户反馈更新