diff --git a/README.md b/README.md index acb42bd..e544fc6 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,75 @@ -# ouc_server -基于 Linux 网络库开发的 C++ 网络服务器 +# OUC Server + +本项目由中国海洋大学爱特工作室组织开发，目标是基于 Linux 构建一个 **高性能、可扩展的现代 C++ 网络编程库**，为学习和实践网络编程提供平台，同时探索事件驱动架构、异步 I/O、协议封装等关键技术。 + +## ✨ 项目目标 + +- 提供简洁易用的 **Socket 封装** 接口 +- 支持 **多路复用**（epoll/kqueue等） +- 内置 **事件循环** 与 **任务调度** +- 扩展常用协议（HTTP、WebSocket等） +- 作为教学和研究平台，便于社团成员学习与贡献 + +## 🚀 快速开始 + +### 环境要求 + +- C++ 17 或更高版本 +- CMake $\geq$ 3.15 +- Linux 环境（推荐 Debian 12） +- （可选）Docker 用于统一开发环境 + +### ⚙️ 构建步骤 + +```bash +git clone https://github.com/ITStudioOUC/ouc_server +cd ouc_server +mkdir build && cd build +cmake .. +make -j4 +``` + +### 📖 运行示例 + +```bash +./examples +``` + +### 📂 仓库结构 + +```bash +ouc_server +├── include/ # 公共头文件 +├── src/ # 源代码 +├── examples/ # 示例程序 +├── tests/ # 单元测试 +├── docs/ # 文档 +├── CMakeLists.txt +└── README.md +``` + +### 🤝 参与贡献 + +我们欢迎任何形式的贡献！ + +1. Fork 本仓库 +2. 从 dev 分支新建功能分支 feature/... +3. 提交 Pull Request，并等待 Review +4. 通过 CI 检查和 Review 后合并到主仓库 + +具体规范请参考 [CONTRIBUTING.md](/docs/CONTRIBUTING.md)。 + +## 📌 开发路线图 + +- [ ] 完成基本 TCP/UDP 封装 +- [ ] 引入 epoll/kqueue 事件循环 +- [ ] 提供线程池/协程调度器 +- [ ] 增加 HTTP 协议支持 +- [ ] 编写性能测试与文档 + +## 📚 学习资料 + +哈哈，没写 + +## 📜 许可证 +本项目采用 [MIT License](/LICENSE) 开源。 \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..b6aaaa1 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,105 @@ +# 贡献指南 + +感谢你对 OUC Server 的关注！ + +为了让团队协作更高效，请在贡献代码前阅读并遵循以下规范。 + +--- + +## 🌱 开发流程 + +1. **Fork 仓库** 到自己的 GitHub 账号下。 +2. **同步主仓库** 保持代码最新： + ```bash + git fetch upstream + git checkout dev + git pull upstream dev + ``` +3. **新建分支** 开发功能 + ```bash + git checkout -b feature/your-feature-name + ``` +4. 在本地完成开发，并确保编译和测试通过。 +5. **提交代码** 到自己 fork 的仓库。 +6. 发起 **Pull Request (PR)**，目标分支为 `dev`。 +7. 等待 **Code Review**，修改问题后再合并。 + +--- + +## 🌳 分支模型 + +- `main`：始终保持稳定可运行，仅在发布版本时合并。 +- `dev`：日常开发分支，所有功能和修复分支都基于此。 +- `feature/*`：新功能开发分支，例如 `feature/http-server`。 +- `bugfix/*`：修复分支，例如 `bugfix/memory-leak`。 + +--- + +## 📝 提交规范（Commit Message） + +请遵循以下格式： + +```: ``` + +常见 type： +- `feat`：新增功能 +- `fix`：修复 bug +- `docs`：文档更新 +- `test`：增加/修改测试 +- `refactor`：代码重构（无功能新增） +- `perf`：性能优化 +- `style`：代码格式调整（空格、缩进等） +- `chore`：构建/配置修改 + +示例： + +```feat: 添加基础 TCP socket 封装``` + +```fix: 修复 epoll 边缘触发模式下的阻塞问题``` + +--- + +## ✅ 测试与检查 + +- 每个功能/修复都必须附带相应的 **单元测试**。 +- 所有 PR 必须通过 **CI 构建**（CMake 编译 + 测试）。 +- 推荐在提交前运行： + ```bash + mkdir build && cd build + cmake .. + make -j4 + ctest + ``` + +--- + +## 🎨 代码风格 + +- 使用 **C++17** 标准。 +- 缩进统一为 **4 空格**。 +- 文件名统一小写，单词用下划线分隔（如 `event_loop.h`）。 +- 类名采用 **大驼峰命名**（如 `EventLoop`）。 +- 函数与变量采用 **小写加下划线**（如 `start_server()`，`buffer_size`）。 +- 公共接口需要写清楚 **Doxygen 风格注释**。 + +--- + +## 🔍 Code Review 原则 + +- 确认代码可读、可维护，避免冗余实现。 +- 注意异常处理、内存管理和线程安全问题。 +- 保证接口一致性和合理性。 +- 审查通过后，才能合并到 `dev` 分支。 + +--- + +## 📌 贡献者守则 + +请保持尊重、开放和协作的态度。 + +任何形式的歧视或攻击性言行都不被允许。 + +--- + +感谢你为项目贡献力量！ 🚀 + diff --git a/docs/code_style.md b/docs/code_style.md new file mode 100644 index 0000000..c40d849 --- /dev/null +++ b/docs/code_style.md @@ -0,0 +1,179 @@ +# OUC Server 代码规范 + +本规范适用于 OUC Server 项目，确保团队成员代码风格一致、可读性高、可维护性强。 + +## 1. C++ 版本与标准 + +- 使用 **C++17** 或更高版本。 +- 优先使用标准库功能，避免非必要的第三方依赖。 + +## 2. 文件与目录命名 + +- 文件名统一小写，单词间用下划线分隔：`event_loop.h`、`tcp_server.cpp` +- 目录名小写：`include/`、`src/`、`tests/`、`examples/` +- 头文件包含保护宏：`INCLUDE_OUCSERVER_` + 无后缀文件名，全部字母大写，单词间用下划线分隔 + ```cpp + #ifndef INCLUDE_OUCSERVER_EVENT_LOOP + #define INCLUDE_OUCSERVER_EVENT_LOOP + // ... + #endif // INCLUDE_OUCSERVER_EVENT_LOOP + ``` + +## 3. 类与命名 + +- 类名采用 **驼峰命名**： + ```cpp + class EventLoop {}; + class TcpServer {}; + ``` +- 枚举类型使用 **首字母大写的驼峰命名**： + ```cpp + enum class SocketState { Closed, Listening, Connected }; + ``` + +## 4. 命名空间 + +**不允许在全局环境下使用 `using namespace`!** + +- 所有模块都需要包含于 `ouc_server` 命名空间 +- 对于一个子模块，应该再包含于以模块的文件夹名为名的命名空间 + ```cpp + namespace ouc_server + { + namespace event + { + // ... + } + } + ``` + +## 5. 函数与变量 + +- 函数名使用 **小写加下划线**： + ```cpp + void start_server(); + int get_socket_fd() const; + ``` +- 成员变量使用 `m_` 前缀： + ```cpp + int m_socket_fd; + std::string m_host; + ``` +- 局部变量尽量短小有意义，避免滥用缩写。 +- 常量使用 **全大写加下划线**： + ```cpp + constexpr int MAX_CONNECTIONS = 1024; + ``` + +## 6. 缩进与空格 + +- 缩进统一为 **Tab**，本地开发推荐显示为 4 空格。 +- 操作符两边保留空格： + ```cpp + int sum = a + b; + ``` +- 控制语句中除单语句外均需要添加大括号作用域： + - 条件分支 + ```cpp + if (condition) + do_something(); // Right + if(condition) + do_something(), do_another_thing(); // Wrong! + if (condition) + { + do_something(); + do_another_thing(); + } + else + { + do_another_thing(); + do_something(); + } + ``` + - 循环结构 + ```cpp + for (int i = 0; i < n; ++i) + { + do_something(); + } + while(condition) + { + do_something(); + } + do + { + do_something(); + } + while(condition); + ``` + - 选择结构 + ```cpp + switch(condition) + { + case 1: + do_something(); + break; + //case ...: + default: + do_something(); + break; + } + ``` + +## 7. 注释与文档 + +- 所有 **公共接口** 必须有 Doxygen 风格注释： + ```cpp + /** + * @brief 启动 TCP 服务器 + * @param port 监听端口 + */ + void start_server(int port); + ``` +- 复杂逻辑可以加内联注释，但避免冗余： + ```cpp + // 使用非阻塞模式读取数据 + socket.read_nonblocking(); + ``` + +## 8. 异常与错误处理 +- 尽量使用 **RAII** 管理资源，避免手动 delete。 +- 遇到严重错误，可使用 `throw` 抛异常；非严重错误返回错误码或状态。 + +## 9.头文件包含顺序 + +头文件按照以下顺序引入，不同类型头文件之间用空行隔开： + +1. 对应模块的头文件 +2. 标准库头文件 +3. 第三方库头文件 +4. 其他模块头文件 + +示例： +```cpp +#include "tcp_server.hpp" + +#include +#include +#include + +#include "third_party/some_c_lib.h" +#include "third_party/some_cpp_lib.hpp" + +#include "event_loop.hpp" +``` + +## 10. 测试与调试 + +- 每个模块必须有对应单元测试。 +- 调试代码在提交前必须移除或用宏控制： + ```cpp + #ifdef DEBUG + std::cout << "Debug info" << std::endl; + #endif + ``` + +## 11. 格式化工具（推荐） + +- 可使用 `clang-format` 自动格式化代码，推荐团队统一配置 `.clang-format` 文件。 +- 所有 PR 提交前请运行格式化，保证一致性。 \ No newline at end of file