nnet/docs/kb/development/CODE_STRUCTURE.md

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等事件

关键结构：

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等

协议接口：

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: 路由项定义

关键接口：

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