|
|
# nnet 代码结构详细说明
|
|
|
|
|
|
## 一、整体目录结构
|
|
|
|
|
|
```
|
|
|
nnet/
|
|
|
├── cmd/ # 命令行工具和示例程序
|
|
|
│ ├── server/ # 服务器示例
|
|
|
│ │ ├── main.go # 服务器主程序
|
|
|
│ │ └── examples/ # 各种使用示例
|
|
|
│ └── client/ # 客户端示例
|
|
|
│ ├── main.go # 客户端主程序
|
|
|
│ └── examples/ # 各种使用示例
|
|
|
│
|
|
|
├── internal/ # 内部实现（不对外暴露，用户不应直接使用）
|
|
|
│ ├── server/ # 服务器核心实现
|
|
|
│ │ ├── server.go # Server主结构
|
|
|
│ │ ├── engine.go # gnet引擎封装
|
|
|
│ │ └── handler.go # 事件处理器
|
|
|
│ │
|
|
|
│ ├── protocol/ # 协议实现层
|
|
|
│ │ ├── manager.go # 协议管理器
|
|
|
│ │ ├── version.go # 版本管理器
|
|
|
│ │ ├── tcp/ # TCP协议实现
|
|
|
│ │ │ ├── tcp.go
|
|
|
│ │ │ └── codec.go
|
|
|
│ │ ├── udp/ # UDP协议实现
|
|
|
│ │ │ ├── udp.go
|
|
|
│ │ │ └── codec.go
|
|
|
│ │ ├── websocket/ # WebSocket协议实现
|
|
|
│ │ │ ├── websocket.go
|
|
|
│ │ │ └── upgrade.go
|
|
|
│ │ ├── unix/ # Unix Domain Socket实现
|
|
|
│ │ │ └── unix.go
|
|
|
│ │ ├── tls/ # TLS协议实现
|
|
|
│ │ │ ├── tls.go
|
|
|
│ │ │ └── config.go
|
|
|
│ │ ├── serial/ # 串口协议实现（扩展）
|
|
|
│ │ │ └── serial.go
|
|
|
│ │ └── nnet/ # 内置nnet协议实现
|
|
|
│ │ ├── protocol.go # 协议定义
|
|
|
│ │ ├── codec.go # 编解码器
|
|
|
│ │ └── unpacker.go # 粘包拆包
|
|
|
│ │
|
|
|
│ ├── router/ # 路由系统实现
|
|
|
│ │ ├── router.go # 路由核心
|
|
|
│ │ ├── matcher.go # 匹配器实现
|
|
|
│ │ │ ├── string.go # 字符串匹配器
|
|
|
│ │ │ ├── frame_header.go # 帧头匹配器
|
|
|
│ │ │ ├── frame_data.go # 帧数据匹配器
|
|
|
│ │ │ └── custom.go # 自定义匹配器
|
|
|
│ │ ├── group.go # 路由分组
|
|
|
│ │ └── route.go # 路由项
|
|
|
│ │
|
|
|
│ ├── middleware/ # 中间件实现
|
|
|
│ │ ├── chain.go # 中间件链
|
|
|
│ │ ├── middleware.go # 中间件接口实现
|
|
|
│ │ └── builtin/ # 内置中间件
|
|
|
│ │ ├── auth.go # 认证中间件
|
|
|
│ │ ├── logging.go # 日志中间件
|
|
|
│ │ ├── recovery.go # 错误恢复中间件
|
|
|
│ │ └── ratelimit.go # 限流中间件
|
|
|
│ │
|
|
|
│ ├── interceptor/ # 拦截器实现
|
|
|
│ │ ├── chain.go # 拦截器链
|
|
|
│ │ └── interceptor.go # 拦截器接口实现
|
|
|
│ │
|
|
|
│ ├── connection/ # 连接管理
|
|
|
│ │ ├── manager.go # 连接管理器
|
|
|
│ │ ├── connection.go # 连接实现
|
|
|
│ │ ├── group.go # 连接分组
|
|
|
│ │ └── pool.go # 连接池
|
|
|
│ │
|
|
|
│ ├── session/ # Session管理
|
|
|
│ │ ├── manager.go # Session管理器
|
|
|
│ │ ├── session.go # Session接口实现
|
|
|
│ │ └── storage/ # 存储实现
|
|
|
│ │ ├── memory.go # 内存存储（默认）
|
|
|
│ │ ├── file.go # 文件存储
|
|
|
│ │ └── redis.go # Redis存储
|
|
|
│ │
|
|
|
│ ├── codec/ # 编解码器
|
|
|
│ │ ├── codec.go # 编解码器接口
|
|
|
│ │ ├── json.go # JSON编解码器
|
|
|
│ │ ├── binary.go # 二进制编解码器
|
|
|
│ │ └── registry.go # 编解码器注册表
|
|
|
│ │
|
|
|
│ ├── unpacker/ # 粘包拆包
|
|
|
│ │ ├── unpacker.go # 拆包器接口
|
|
|
│ │ ├── fixed_length.go # 固定长度
|
|
|
│ │ ├── length_field.go # 长度字段
|
|
|
│ │ ├── delimiter.go # 分隔符
|
|
|
│ │ └── frame_header.go # 帧头
|
|
|
│ │
|
|
|
│ ├── version/ # 版本管理
|
|
|
│ │ ├── identifier.go # 版本识别器
|
|
|
│ │ ├── manager.go # 版本管理器
|
|
|
│ │ └── strategy.go # 识别策略
|
|
|
│ │
|
|
|
│ ├── config/ # 配置管理
|
|
|
│ │ ├── config.go # 配置结构
|
|
|
│ │ ├── loader.go # 配置加载器
|
|
|
│ │ │ ├── file.go # 文件加载
|
|
|
│ │ │ ├── env.go # 环境变量加载
|
|
|
│ │ │ └── code.go # 代码配置
|
|
|
│ │ └── validator.go # 配置验证
|
|
|
│ │
|
|
|
│ ├── logger/ # 日志实现
|
|
|
│ │ ├── logger.go # 日志接口实现
|
|
|
│ │ ├── std.go # 标准库实现（默认）
|
|
|
│ │ └── adapters/ # 第三方适配器
|
|
|
│ │ ├── logrus.go # logrus适配器
|
|
|
│ │ ├── zap.go # zap适配器
|
|
|
│ │ └── zerolog.go # zerolog适配器
|
|
|
│ │
|
|
|
│ ├── plugin/ # 插件系统
|
|
|
│ │ ├── manager.go # 插件管理器
|
|
|
│ │ ├── plugin.go # 插件接口实现
|
|
|
│ │ └── registry.go # 插件注册表
|
|
|
│ │
|
|
|
│ ├── lifecycle/ # 生命周期管理
|
|
|
│ │ ├── lifecycle.go # 生命周期管理器
|
|
|
│ │ ├── hook.go # 钩子接口
|
|
|
│ │ └── server.go # Server生命周期
|
|
|
│ │
|
|
|
│ └── client/ # 客户端实现
|
|
|
│ ├── client.go # 客户端核心
|
|
|
│ ├── connection.go # 客户端连接
|
|
|
│ ├── pool.go # 连接池
|
|
|
│ └── reconnect.go # 重连管理
|
|
|
│
|
|
|
├── pkg/ # 对外暴露的包（用户可直接使用）
|
|
|
│ ├── nnet/ # 主包（入口）
|
|
|
│ │ ├── server.go # Server创建和配置
|
|
|
│ │ ├── client.go # Client创建和配置
|
|
|
│ │ └── errors.go # 错误定义
|
|
|
│ │
|
|
|
│ ├── protocol/ # 协议接口
|
|
|
│ │ ├── protocol.go # Protocol接口
|
|
|
│ │ ├── version.go # Version接口
|
|
|
│ │ └── codec.go # Codec接口
|
|
|
│ │
|
|
|
│ ├── router/ # 路由接口
|
|
|
│ │ ├── router.go # Router接口
|
|
|
│ │ ├── matcher.go # Matcher接口
|
|
|
│ │ ├── group.go # RouterGroup接口
|
|
|
│ │ └── route.go # Route接口
|
|
|
│ │
|
|
|
│ ├── middleware/ # 中间件接口
|
|
|
│ │ └── middleware.go # Middleware接口
|
|
|
│ │
|
|
|
│ ├── interceptor/ # 拦截器接口
|
|
|
│ │ └── interceptor.go # Interceptor接口
|
|
|
│ │
|
|
|
│ ├── connection/ # 连接接口
|
|
|
│ │ ├── connection.go # Connection接口
|
|
|
│ │ ├── manager.go # ConnectionManager接口
|
|
|
│ │ └── group.go # ConnectionGroup接口
|
|
|
│ │
|
|
|
│ ├── session/ # Session接口
|
|
|
│ │ ├── session.go # Session接口
|
|
|
│ │ └── storage.go # Storage接口
|
|
|
│ │
|
|
|
│ ├── codec/ # 编解码接口
|
|
|
│ │ ├── codec.go # Codec接口
|
|
|
│ │ ├── encoder.go # Encoder接口
|
|
|
│ │ └── decoder.go # Decoder接口
|
|
|
│ │
|
|
|
│ ├── metrics/ # 指标接口与导出
|
|
|
│ │ ├── metrics.go # Metrics接口实现
|
|
|
│ │ └── prometheus.go # Prometheus文本导出器
|
|
|
│ │
|
|
|
│ ├── context/ # Context接口
|
|
|
│ │ └── context.go # Context接口
|
|
|
│ │
|
|
|
│ └── config/ # 配置接口
|
|
|
│ └── config.go # Config接口
|
|
|
│
|
|
|
├── examples/ # 示例代码
|
|
|
│ ├── basic_server/ # 基础服务器示例
|
|
|
│ ├── basic_client/ # 基础客户端示例
|
|
|
│ ├── router_examples/ # 路由使用示例
|
|
|
│ ├── middleware_examples/ # 中间件使用示例
|
|
|
│ ├── protocol_examples/ # 协议使用示例
|
|
|
│ └── advanced/ # 高级用法示例
|
|
|
│
|
|
|
├── test/ # 测试代码
|
|
|
│ ├── unit/ # 单元测试
|
|
|
│ ├── integration/ # 集成测试
|
|
|
│ ├── benchmark/ # 性能测试
|
|
|
│ └── fixtures/ # 测试辅助数据
|
|
|
│
|
|
|
├── docs/ # 文档
|
|
|
│ ├── DESIGN.md # 设计方案
|
|
|
│ ├── REQUIREMENTS.md # 需求文档
|
|
|
│ ├── CODE_STRUCTURE.md # 代码结构（本文档）
|
|
|
│ ├── ROUTER_EXAMPLES.md # 路由示例
|
|
|
│ └── API.md # API文档
|
|
|
│
|
|
|
├── go.mod # Go模块定义
|
|
|
├── go.sum # 依赖校验和
|
|
|
├── .gitignore # Git忽略文件
|
|
|
├── Makefile # 构建脚本
|
|
|
└── README.md # 项目说明
|
|
|
```
|
|
|
|
|
|
## 二、核心模块说明
|
|
|
|
|
|
### 2.1 服务器核心 (internal/server)
|
|
|
|
|
|
**职责**：服务器的主入口和生命周期管理
|
|
|
|
|
|
**主要文件**：
|
|
|
- `server.go`: Server结构体，包含所有核心组件
|
|
|
- `engine.go`: gnet引擎的封装，处理事件循环
|
|
|
- `handler.go`: 事件处理器，处理OnOpen、OnClose、OnTraffic等事件
|
|
|
|
|
|
**关键结构**：
|
|
|
```go
|
|
|
type Server struct {
|
|
|
*gnetServer
|
|
|
metrics metrics.Metrics
|
|
|
healthChecker health.Checker
|
|
|
serverLifecycleHooks []lifecycle.ServerLifecycleHook
|
|
|
connLifecycleHooks []lifecycle.ConnectionLifecycleHook
|
|
|
}
|
|
|
```
|
|
|
|
|
|
Server 通过 `MetricsHandler()`, `HealthHandler()` 和 `ExportMetrics(io.Writer)` 暴露监控接口，方便挂载到外部 HTTP 服务或自定义导出流程。
|
|
|
|
|
|
### 2.2 协议层 (internal/protocol)
|
|
|
|
|
|
**职责**：协议实现、版本管理、编解码
|
|
|
|
|
|
**主要模块**：
|
|
|
- `manager.go`: 协议注册、发现、选择
|
|
|
- `version.go`: 版本识别和管理
|
|
|
- 各协议实现：TCP、UDP、WebSocket等
|
|
|
|
|
|
**协议接口**：
|
|
|
```go
|
|
|
type Protocol interface {
|
|
|
Name() string
|
|
|
Versions() []Version
|
|
|
Identify(data []byte) (Version, error)
|
|
|
CreateCodec(version Version) (Codec, error)
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 2.3 路由层 (internal/router)
|
|
|
|
|
|
**职责**：路由注册、匹配、分组管理
|
|
|
|
|
|
**主要文件**：
|
|
|
- `router.go`: 路由核心，路由注册和匹配
|
|
|
- `matcher.go`: 匹配器实现
|
|
|
- `string.go`: 字符串匹配器
|
|
|
- `frame_header.go`: 帧头匹配器
|
|
|
- `frame_data.go`: 帧数据匹配器
|
|
|
- `custom.go`: 自定义匹配器
|
|
|
- `group.go`: 路由分组
|
|
|
- `route.go`: 路由项定义
|
|
|
|
|
|
**关键接口**：
|
|
|
```go
|
|
|
type Matcher interface {
|
|
|
Match(input MatchInput, ctx Context) bool
|
|
|
Priority() int
|
|
|
}
|
|
|
|
|
|
type Router interface {
|
|
|
Register(matcher Matcher, handler Handler) Route
|
|
|
RegisterString(pattern string, handler Handler) Route
|
|
|
RegisterFrameHeader(field, operator string, value interface{}, handler Handler) Route
|
|
|
RegisterFrameData(path, operator string, value interface{}, handler Handler) Route
|
|
|
Group() RouterGroup
|
|
|
Match(input MatchInput, ctx Context) (Handler, []Matcher, error)
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 2.4 连接管理 (internal/connection)
|
|
|
|
|
|
**职责**：连接生命周期管理、连接分组、跨连接操作
|
|
|
|
|
|
**主要文件**：
|
|
|
- `manager.go`: 连接管理器，管理所有连接
|
|
|
- `connection.go`: 连接实现，封装gnet连接
|
|
|
- `group.go`: 连接分组管理
|
|
|
- `pool.go`: 连接池（客户端使用）
|
|
|
|
|
|
### 2.5 Session管理 (internal/session)
|
|
|
|
|
|
**职责**：Session数据存储
|
|
|
|
|
|
**主要文件**：
|
|
|
- `manager.go`: Session管理器
|
|
|
- `session.go`: Session实现
|
|
|
- `storage/`: 存储策略实现
|
|
|
- `memory.go`: 内存存储（默认）
|
|
|
- `file.go`: 文件存储
|
|
|
- `redis.go`: Redis存储
|
|
|
|
|
|
### 2.6 客户端 (internal/client)
|
|
|
|
|
|
**职责**：客户端实现
|
|
|
|
|
|
**主要文件**：
|
|
|
- `client.go`: 客户端核心
|
|
|
- `connection.go`: 客户端连接
|
|
|
- `pool.go`: 连接池
|
|
|
- `reconnect.go`: 自动重连
|
|
|
|
|
|
## 三、包设计原则
|
|
|
|
|
|
### 3.1 internal/ 包
|
|
|
- **不对外暴露**：用户不应直接导入internal包
|
|
|
- **实现细节**：包含所有具体实现
|
|
|
- **可修改**：内部实现可以随时改变，不影响用户代码
|
|
|
|
|
|
### 3.2 pkg/ 包
|
|
|
- **对外暴露**：用户可以直接使用
|
|
|
- **接口定义**：主要定义接口和公共类型
|
|
|
- **稳定API**：接口设计稳定，向后兼容
|
|
|
|
|
|
### 3.3 模块划分
|
|
|
- **单一职责**：每个模块只负责一个功能
|
|
|
- **低耦合**：模块间通过接口交互
|
|
|
- **高内聚**：相关功能集中在同一模块
|
|
|
|
|
|
## 四、依赖关系
|
|
|
|
|
|
```
|
|
|
pkg/nnet (用户入口)
|
|
|
↓
|
|
|
internal/server (服务器核心)
|
|
|
├── internal/protocol (协议层)
|
|
|
├── internal/router (路由层)
|
|
|
├── internal/connection (连接管理)
|
|
|
├── internal/session (Session管理)
|
|
|
├── internal/middleware (中间件)
|
|
|
├── internal/interceptor (拦截器)
|
|
|
├── internal/codec (编解码)
|
|
|
├── internal/unpacker (粘包拆包)
|
|
|
├── internal/version (版本管理)
|
|
|
├── internal/config (配置管理)
|
|
|
├── internal/logger (日志)
|
|
|
├── pkg/metrics (监控)
|
|
|
├── internal/plugin (插件)
|
|
|
└── internal/lifecycle (生命周期)
|
|
|
```
|
|
|
|
|
|
## 五、代码组织原则
|
|
|
|
|
|
1. **接口与实现分离**：接口在pkg/，实现在internal/
|
|
|
2. **按功能模块划分**：每个功能一个目录
|
|
|
3. **避免循环依赖**：通过接口解耦
|
|
|
4. **最小暴露原则**：只暴露必要的接口
|
|
|
5. **易于测试**：接口设计便于Mock和测试
|
|
|
|
|
|
## 六、扩展点
|
|
|
|
|
|
### 6.1 协议扩展
|
|
|
- 实现`pkg/protocol/Protocol`接口
|
|
|
- 在`internal/protocol/`下创建新协议目录
|
|
|
- 注册到协议管理器
|
|
|
|
|
|
### 6.2 匹配器扩展
|
|
|
- 实现`pkg/router/Matcher`接口
|
|
|
- 在`internal/router/matcher/`下创建新匹配器
|
|
|
- 注册到路由器
|
|
|
|
|
|
### 6.3 存储扩展
|
|
|
- 实现`pkg/session/Storage`接口
|
|
|
- 在`internal/session/storage/`下创建新存储
|
|
|
- 注册到Session管理器
|
|
|
|
|
|
### 6.4 插件扩展
|
|
|
- 实现`pkg/plugin/Plugin`接口
|
|
|
- 注册到插件管理器
|
|
|
|
|
|
---
|
|
|
|
|
|
**文档版本**: v1.0
|
|
|
**最后更新**: 2024
|
|
|
|