# 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