|
|
---
|
|
|
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
|