贡献规范

感谢你对 OLC 项目的关注！本文档说明如何参与 OLC 的开发。

开发环境搭建

前置要求

Python >= 3.11
pip

安装步骤

# 克隆项目
git clone <repository-url>
cd olc

# 安装核心库（开发模式）
pip install -e .

# 安装核心库 + FastAPI 适配器
pip install -e .[fastapi]

# 安装所有适配器
pip install -e .[all]

验证安装

# 运行测试
pytest tests/ -v

# 运行 FastAPI 示例
cd examples/fastapi_demo
python main.py

代码风格规范

基本规则

遵循 PEP 8
使用 Black 格式化代码（项目已配置 pyproject.toml 中的 [tool.black]）
目标 Python 版本：3.11

命名约定

类型	约定	示例
类名	PascalCase	`OlcRateLimiterFactory`
方法名	snake_case	`try_acquire`
变量名	snake_case	`token_number`
常量	UPPER_SNAKE_CASE	`FLOW_PREFIX`
私有属性	前缀 `_`	`_instance`, `_lock`

单例模式约定

OLC 中大量使用单例模式，统一遵循以下约定：

class SomeManager:
    _instance = None
    _lock = threading.Lock()  # 简单场景用 Lock，需要重入用 RLock

    @classmethod
    def get_instance(cls) -> "SomeManager":
        if cls._instance is None:
            with cls._lock:
                if cls._instance is None:
                    cls._instance = cls()
        return cls._instance

要点：

类属性 _instance 和 _lock
类方法 get_instance() 使用双重检查锁
构造函数 __init__ 中完成所有初始化

日志规范

import logging

logger = logging.getLogger(__name__)

使用 __name__ 作为 logger 名称，自动对应模块路径
级别使用：logger.debug() 调试信息、logger.info() 关键流程、logger.warning() 可恢复异常、logger.error() 严重错误
错误日志使用 exc_info=True 记录堆栈

测试规范

框架

使用 pytest 作为测试框架。

目录结构

测试目录 tests/ 镜像 olc/ 源码目录：

tests/
├── alg/               # 算法模块测试
├── bean/              # 数据模型测试
├── cache/             # 缓存测试
├── collector/         # 采集器测试
├── config/            # 配置管理测试
├── control/           # 控制逻辑测试
│   ├── context/
│   ├── handler/
│   ├── handler_chain/
│   └── matcher/
├── e2e/               # 端到端测试
├── event/             # 事件测试
├── limit/             # 限流器测试
├── performance/       # 性能测试
├── remote/            # HTTP 客户端测试
├── rule/              # 规则管理测试
├── statistic/         # 统计测试
├── stub/              # 配置源测试
├── task_schedule/     # 定时任务测试
└── utils/             # 工具函数测试

命名约定

测试文件：test_<module_name>.py
测试类：Test<ClassName>
测试方法：test_<behavior_description>

运行测试

# 运行所有测试
pytest tests/ -v

# 运行特定模块测试
pytest tests/limit/ -v

# 运行特定测试
pytest tests/limit/test_qps_limiter.py::TestQpsLimiter::test_try_acquire -v

# 运行覆盖率测试
pytest tests/ --cov=olc --cov-report=html

# 运行端到端测试
pytest tests/e2e/ -v

测试要求

新增功能必须附带测试
测试应覆盖正常路径和异常路径
单例类测试需注意清理全局状态（_instance = None）
涉及 Redis 的测试需 mock 或使用测试实例

Git 工作流

分支命名

类型	格式	示例
新功能	`feature/<name>`	`feature/flask-adapter`
修复	`fix/<name>`	`fix/qps-limiter-rollback`
文档	`docs/<name>`	`docs/developer-manual`

Commit Message 格式

<type>: <description>

[optional body]

类型：

feat: 新功能
fix: 修复
docs: 文档
refactor: 重构
test: 测试
chore: 构建/工具变更

示例：

feat: add sliding window rate limiter
fix: fix token rollback in quota limiter
docs: add developer manual

PR 流程

Fork 项目（如果是外部贡献者）
从 main 创建特性分支
开发并提交代码（确保测试通过）
创建 Pull Request，描述变更内容
等待代码审查和合并

发布流程

更新 pyproject.toml 中的 version
更新 README.md 中的版本信息（如有必要）
提交版本变更
创建版本标签