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.

34 KiB

Raw Blame History Unescape Escape

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）

// 伪代码示例
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）

职责：
- 协议注册和发现
- 协议版本管理
- 协议识别和选择
- 编解码器管理

关键接口

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）

职责：
- 连接的创建、维护、销毁
- 连接分组管理
- 连接查询和操作
- 跨连接操作

关键接口

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）- 重新设计

职责：
- 路由注册和匹配（支持多种匹配策略）
- 路由分组管理
- 路由中间件绑定

关键接口

// 路由匹配器接口
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过期管理

关键接口

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 识别时机

连接建立时：通过握手消息识别
首次消息时：通过第一个消息识别
特定消息时：通过包含版本信息的特定消息识别

3.1.2 识别方式

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 内置协议支持

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 插件系统应用场景

协议转换插件：
- 将HTTP请求转换为内部协议
- 将MQTT消息转换为内部协议
数据统计插件：
- 统计业务指标（如：用户在线时长、消息发送量）
- 将统计数据推送到监控系统
消息队列插件：
- 将消息异步推送到Kafka、RabbitMQ等
- 实现消息的持久化和异步处理
缓存插件：
- 提供分布式缓存功能
- 缓存热点数据，提升性能
限流插件：
- 实现多种限流算法（令牌桶、漏桶等）
- 支持分布式限流
数据同步插件：
- 将数据同步到数据库
- 实现数据的持久化

3.5 生命周期钩子设计

// 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）

TCP协议支持
基础路由系统（支持字符串匹配）
基础中间件系统
连接管理（基础功能）
基础配置管理
基础日志系统
健康检查接口

Phase 2: 协议与数据处理

协议版本管理（包括无帧头协议支持）
编解码系统
粘包拆包处理
内置nnet协议
UDP、WebSocket协议支持
路由系统扩展（帧头匹配、帧数据匹配）

Phase 3: 高级功能

Session管理（默认内存存储）
拦截器系统
连接分组
TLS支持
Unix Domain Socket支持
内置nnet客户端
生命周期管理（Server + Connection）

Phase 4: 扩展功能

插件系统
Metrics监控（Prometheus格式）
串口等扩展协议
高级配置功能
测试完善（覆盖率80%+）

Phase 5: 优化与完善

性能优化
文档完善
示例代码
最佳实践
Shell连接支持（低优先级）

五、设计原则

接口驱动设计：核心功能通过接口定义，便于扩展和测试
依赖倒置：高层模块不依赖低层模块，都依赖抽象
单一职责：每个模块只负责一个功能
开闭原则：对扩展开放，对修改关闭
最小依赖：核心功能不依赖第三方库
高性能优先：充分利用gnet的性能特性
易用性：提供简洁的API，降低使用门槛

六、客户端设计

6.1 客户端架构

┌─────────────────────────────────────────────────────────────┐
│                     客户端应用层                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │ 请求发送 │  │ 响应接收 │  │ 消息推送 │                  │
│  └──────────┘  └──────────┘  └──────────┘                  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                     客户端核心层                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │连接管理  │  │协议管理  │  │编解码    │  │重连管理  │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                     传输层                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │  TCP     │  │  UDP     │  │WebSocket │                  │
│  └──────────┘  └──────────┘  └──────────┘                  │
└─────────────────────────────────────────────────────────────┘

6.2 客户端接口设计

// 客户端接口
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 客户端使用示例

// 创建客户端
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
状态: 已根据用户反馈更新

34 KiB Raw Blame History Unescape Escape

nnet 网络库 - 需求提炼与设计方案

一、需求提炼与整合

1. 核心功能模块

1.1 多协议支持层

1.2 协议版本管理系统

1.3 路由系统（重新设计）

1.4 中间件系统

1.5 数据报文拦截器（责任链模式）

1.6 编解码与序列化系统

1.7 内置nnet协议

1.8 连接管理系统

1.9 Session管理系统

1.10 Context系统

1.11 配置管理系统

1.12 日志系统（日志门面）

1.13 指标监控（Metrics）

1.14 插件系统

1.15 生命周期管理

1.16 客户端支持

1.17 健康检查接口

1.18 Shell连接支持（低优先级）

1.19 测试支持

2. 非功能性需求

2.1 性能要求

2.2 可扩展性

2.3 可维护性

2.4 依赖管理

二、架构设计

2.1 整体架构

2.2 核心模块设计

2.2.1 服务器核心（Server Core）

2.2.2 协议管理器（Protocol Manager）

2.2.3 连接管理器（Connection Manager）

2.2.4 路由管理器（Router）- 重新设计

2.2.5 Session管理器（Session Manager）

2.3 数据流设计

2.4 目录结构设计

三、关键技术设计

3.1 协议版本识别策略

3.1.1 识别时机

3.1.2 识别方式

3.1.3 版本持久化

3.1.4 无帧头协议的特殊处理

3.2 粘包拆包解决方案

3.2.1 内置协议支持

3.2.2 协议识别与粘包拆包

3.3 中间件与拦截器区别

3.4 插件系统应用场景

3.5 生命周期钩子设计

3.6 gnet集成设计

四、实现优先级建议

Phase 1: 核心功能（MVP）

Phase 2: 协议与数据处理

Phase 3: 高级功能

Phase 4: 扩展功能

Phase 5: 优化与完善

五、设计原则

六、客户端设计

6.1 客户端架构

6.2 客户端接口设计

6.3 客户端使用示例

34 KiB

Raw Blame History Unescape Escape