docs: 添加了项目概览、贡献规则与代码规范文档

2025-09-27 10:22:38 +00:00
parent 93f3e0c6bd
commit b56499d84c
3 changed files with 359 additions and 2 deletions
@@ -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) 开源。
@@ -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>: <description>```
+
+常见 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` 分支。
+
+---
+
+## 📌 贡献者守则
+
+请保持尊重、开放和协作的态度。
+
+任何形式的歧视或攻击性言行都不被允许。
+
+---
+
+感谢你为项目贡献力量！ 🚀
+
@@ -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 <vector>
+#include <string>
+#include <iostream>
+
+#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 提交前请运行格式化，保证一致性。