---
alwaysApply: true
---

# nnet 网络库开发规则

本文档定义了 nnet 网络库的开发规则和知识库关联。

## 知识库关联

使用 `@file` 指令关联知识库文档：

### 设计文档
@file docs/kb/design/ARCHITECTURE.md
@file docs/kb/design/DESIGN.md

### 需求文档
@file docs/kb/requirements/REQUIREMENTS.md

### 开发文档
@file docs/kb/development/CODE_STRUCTURE.md
@file docs/kb/development/IMPLEMENTATION.md

### 测试文档
@file docs/kb/testing/TEST_COVERAGE.md

### 状态文档
@file docs/kb/status/PROJECT_STATUS.md

### 用户指南
@file docs/kb/user-guide/ROUTER_EXAMPLES.md
@file docs/kb/user-guide/PROTOCOL_FRAME_EXPLANATION.md

## 项目概述

nnet 是一个基于 golang 1.25.4 和 gnet 2.9.5 实现的高性能、功能完备的网络库。

### 核心特性

- 多协议支持：TCP、UDP、WebSocket、Unix Domain Socket、TLS、串口等
- 现代化的路由系统：支持字符串匹配、帧头匹配、帧数据匹配
- 灵活的中间件系统：全局中间件、路由级中间件
- 协议版本管理：支持单协议多版本，灵活的版本识别策略
- 连接管理：连接分组、跨连接操作
- Session管理：支持内存、文件、Redis等存储策略
- 内置客户端：支持TCP、UDP、WebSocket等协议
- 插件系统：可扩展的插件架构
- 指标监控：Prometheus格式的Metrics
- 健康检查：内置健康检查接口

## 代码组织

### 目录结构

```
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/                  # 文档
    └── kb/                # 知识库
```

### 设计原则

1. **接口驱动设计**：核心功能通过接口定义，便于扩展和测试
2. **单一职责**：每个模块只负责一个功能
3. **开闭原则**：对扩展开放，对修改关闭
4. **最小依赖**：核心功能不依赖第三方库
5. **高性能优先**：充分利用gnet的事件驱动模型

## 开发规则

### 1. 代码风格

- 遵循 Go 官方代码规范
- 使用 `gofmt` 格式化代码
- 使用 `golint` 检查代码
- 使用有意义的变量和函数名

### 2. 接口设计

- 接口定义在 `pkg/` 目录
- 实现放在 `internal/` 目录
- 接口应该小而专注
- 避免接口污染

### 3. 错误处理

- 使用 `pkg/errors` 包处理错误
- 错误信息应该清晰明确
- 使用错误包装提供上下文
- 避免吞掉错误

### 4. 测试

- 每个功能都应该有对应的测试
- 测试覆盖率目标：80%+
- 使用表格驱动测试
- 测试文件命名：`*_test.go`

### 5. 文档

- 公共API必须有文档注释
- 使用 `godoc` 格式
- 示例代码放在 `examples/` 目录
- 设计文档放在 `docs/kb/` 目录

### 6. 性能

- 避免不必要的内存分配
- 使用对象池减少GC压力
- 充分利用gnet的事件驱动模型
- 进行性能测试和基准测试

## 开发流程

### 1. 功能开发

1. 查看需求文档和设计文档
2. 设计接口和实现
3. 编写单元测试
4. 实现功能
5. 运行测试
6. 更新文档

### 2. Bug修复

1. 复现问题
2. 编写测试用例
3. 修复问题
4. 运行测试
5. 更新文档

### 3. 代码审查

1. 检查代码风格
2. 检查接口设计
3. 检查错误处理
4. 检查测试覆盖
5. 检查文档完整性

## 注意事项

1. **向后兼容**：修改公共API时需要考虑向后兼容性
2. **性能影响**：修改核心代码时需要考虑性能影响
3. **测试覆盖**：新功能必须有对应的测试
4. **文档更新**：修改功能时同步更新文档
5. **依赖管理**：添加新依赖时需要评估必要性

## 参考资源

- [Go官方文档](https://golang.org/doc/)
- [gnet文档](https://github.com/panjf2000/gnet)
- [项目知识库](docs/kb/README.md)

---

**最后更新**: 2024