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.

11 KiB

Raw Blame History Unescape Escape

nnet 架构设计文档

一、整体架构

1.1 架构层次

┌─────────────────────────────────────────────────────────────┐
│                        应用层 (Application)                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  路由    │  │ 中间件   │  │ 拦截器   │  │ 处理器   │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      核心层 (Core)                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │连接管理  │  │Session   │  │Context   │  │生命周期  │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      协议层 (Protocol)                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │协议管理  │  │版本管理  │  │编解码    │  │粘包拆包  │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      传输层 (Transport)                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  TCP     │  │  UDP     │  │WebSocket │  │  Unix    │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                 │
│  │  TLS     │  │  串口    │  │  扩展    │                 │
│  └──────────┘  └──────────┘  └──────────┘                 │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      基础设施层 (Infrastructure)              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  配置    │  │  日志    │  │ 监控     │  │  插件    │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                          ┌───────┐
                          │ gnet  │
                          └───────┘

1.2 核心模块

服务器核心（Server Core）

配置管理
协议管理器
连接管理器
路由管理器
中间件链
拦截器链
Session管理器
生命周期管理器
插件管理器
日志系统
Metrics监控

服务器通过可复用的 MetricsHandler、HealthHandler 和 ExportMetrics 接口向外暴露监控数据，使用者需要在自有的HTTP服务中挂载这些处理器。

协议层（Protocol Layer）

协议注册和发现
协议版本管理
协议识别和选择
编解码器管理
粘包拆包处理

路由系统（Router）

字符串匹配
帧头匹配
帧数据匹配
自定义匹配
路由分组
路由优先级

连接管理（Connection）

连接生命周期管理
连接分组
分组广播
跨连接操作

Session管理（Session）

数据存储
存储策略（内存/文件/Redis）
Session过期管理

Context系统（Context）

状态管理
请求/响应数据
连接信息
键值对存储

二、数据流程

2.1 请求处理流程

客户端数据
    │
    ▼
[传输层接收] (gnet事件)
    │
    ▼
[粘包拆包] (Unpacker) ──→ 处理半包/粘包，提取完整消息
    │
    ▼
[协议头解析] (Protocol.Decode) ──→ 提取帧头和数据体
    │
    ▼
[Codec选择] (CodecResolver) ──→ 优先级：版本 > 上下文/Session > Header > 原始探测 > 默认
    │
    ▼
[应用层解码] (Codec.Decode) ──→ 将数据体解码为结构化对象（JSON/Msgpack等）或保持原始字节（binary/plain）
    │
    ▼
[路由匹配] (Router) ──→ 基于完全解码的数据进行匹配（Raw/Header/Data）
    │
    ▼
[强类型解码] (Codec.Decode) ──→ 如有需要，将数据解码到路由指定的强类型结构体
    │
    ▼
[拦截器链] (InterceptorChain)
    │
    ▼
[中间件链] (MiddlewareChain)
    │
    ▼
[业务处理] (Handler) ──→ 直接同步执行，依赖Context超时控制
    │
    ▼
[编码] (Encoder)
    │
    ▼
[拦截器链] (InterceptorChain)
    │
    ▼
[传输层发送] (gnet事件)
    │
    ▼
客户端

2.2 自动解析流程

1. 数据到达 → Connection.Read()
   ↓
2. 粘包拆包 → Unpacker.Unpack() → 完整消息列表
   ↓
3. 协议头解析 → Protocol.Decode() → Header + DataBytes
   ↓
4. Codec选择 → CodecResolver.resolveCodecGeneric()
   - 优先级：协议版本 > 上下文/Session > Header.codec > 原始数据探测 > 默认(binary)
   ↓
5. 应用层预解码 → Codec.Decode() → 通用对象（map/interface{}）或原始字节
   ↓
6. 路由匹配 → Router.Match() → 基于完全解码的数据（Raw/Header/Data）
   ↓
7. 强类型解码（可选）→ Codec.Decode() → 路由指定的结构体类型
   ↓
8. Handler执行 → req.Data().(*MyStruct) (直接使用)

2.3 自动编码流程

1. Handler调用 → resp.Write(struct)
   ↓
2. 编解码器编码 → Codec.Encode() → []byte
   ↓
3. 协议编码 → Protocol.Encode() → Header + Data
   ↓
4. 写入连接 → Connection.Write()

三、关键设计原则

3.1 接口驱动设计

核心功能通过接口定义，便于扩展和测试
依赖倒置：高层模块不依赖低层模块，都依赖抽象

3.2 单一职责

每个模块只负责一个功能
Context只负责状态管理
Request负责数据读取
Response负责数据写入

3.3 开闭原则

对扩展开放，对修改关闭
通过接口和插件系统扩展功能

3.4 最小依赖

核心功能不依赖第三方库
可选功能通过接口隔离

3.5 高性能优先

充分利用gnet的事件驱动模型
减少内存分配和GC压力
支持连接池和对象池

四、目录结构

nnet/
├── cmd/                    # 命令行工具和示例
├── internal/              # 内部实现（不对外暴露）
│   ├── server/            # 服务器核心
│   ├── protocol/          # 协议实现
│   ├── router/            # 路由实现
│   ├── middleware/        # 中间件实现
│   ├── interceptor/       # 拦截器实现
│   ├── connection/        # 连接管理
│   ├── session/           # Session管理
│   ├── codec/             # 编解码器
│   ├── unpacker/          # 粘包拆包
│   ├── client/            # 客户端实现
│   └── ...
├── pkg/                   # 对外暴露的包
│   ├── nnet/              # 主包（入口）
│   ├── protocol/          # 协议接口
│   ├── router/            # 路由接口
│   ├── middleware/        # 中间件接口
│   ├── interceptor/       # 拦截器接口
│   ├── connection/        # 连接接口
│   ├── session/           # Session接口
│   ├── codec/             # 编解码接口
│   └── ...
├── examples/              # 示例代码
├── test/                  # 测试代码
└── docs/                  # 文档

五、扩展点

5.1 协议扩展

实现pkg/protocol/Protocol接口
在internal/protocol/下创建新协议目录
注册到协议管理器

5.2 匹配器扩展

实现pkg/router/Matcher接口
在internal/router/matcher/下创建新匹配器
注册到路由器

5.3 存储扩展

实现pkg/session/Storage接口
在internal/session/storage/下创建新存储
注册到Session管理器

5.4 插件扩展

实现pkg/plugin/Plugin接口
注册到插件管理器

六、参考文档

文档版本: v1.0
最后更新: 2024

11 KiB Raw Blame History Unescape Escape