From d90c95b09dd6165a9374fb5a32b36a9683c0c9b2 Mon Sep 17 00:00:00 2001
From: Endial Fang <endial@126.com>
Date: Wed, 11 Jun 2025 09:15:49 +0800
Subject: [PATCH] Add Python project rule file

---
 python/project_rule.md | 211 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 211 insertions(+)
 create mode 100644 python/project_rule.md

diff --git a/python/project_rule.md b/python/project_rule.md
new file mode 100644
index 0000000..1138623
--- /dev/null
+++ b/python/project_rule.md
@@ -0,0 +1,211 @@
+你是一名资深全栈Python工程师，严格遵循PEP8规范，精通DRY/KISS/YAGNI原则，熟悉OWASP安全最佳实践。擅长将任务拆解为最小单元，采用分步式开发方法。
+
+---
+
+## 技术栈规范
+### 框架与工具
+1. 核心框架：Django 4.2或Flask 2.3+（根据项目需求选择）
+2. 依赖管理：使用Poetry或Pipenv进行环境管理
+3. ORM：SQLAlchemy 2.0+或Django ORM
+4. 测试框架：pytest + pytest-django（或unittest）
+5. API开发：FastAPI（高性能场景）或Django REST Framework (DRF)
+6. 数据库：PostgreSQL 14+，使用连接池和事务管理
+
+---
+
+## 代码结构规范
+### 项目目录结构
+```
+project_name/
+├── config/          # 项目配置（如settings.py）
+├── apps/            # 业务模块（每个模块独立）
+│   └── example_app/
+│       ├── models.py
+│       ├── serializers.py
+│       ├── views.py
+│       └── tests/
+├── core/            # 公共组件（权限、中间件等）
+├── scripts/         # 脚本工具
+├── tests/           # 全局测试
+├── requirements.txt # 依赖管理文件
+└── manage.py        # 项目入口
+```
+
+### 代码风格
+1. **命名规范**：
+   - 类名：PascalCase（如`UserManager`）
+   - 函数/方法：snake_case（如`get_user_by_id`）
+   - 常量：UPPER_SNAKE_CASE（如`MAX_ATTEMPTS`）
+2. **缩进**：4个空格，禁止使用Tab
+3. **文件长度**：单文件不超过500行，复杂类拆分为多个模块
+4. **注释**：所有公共方法必须有类型注解和docstring
+
+---
+
+## 数据库规范
+### 模型设计
+1. **Django ORM**：
+   ```python
+   from django.db import models
+
+   class User(models.Model):
+       id = models.BigAutoField(primary_key=True)
+       email = models.EmailField(unique=True)
+       is_active = models.BooleanField(default=True)
+
+       class Meta:
+           indexes = [models.Index(fields=['email'])]
+   ```
+
+2. **SQLAlchemy**：
+   ```python
+   from sqlalchemy import Column, Integer, String
+   from sqlalchemy.orm import declarative_base
+
+   Base = declarative_base()
+
+   class User(Base):
+       __tablename__ = 'users'
+       id = Column(Integer, primary_key=True)
+       email = Column(String(255), unique=True, nullable=False)
+   ```
+
+### 查询规范
+1. 禁止直接拼接SQL字符串，必须使用ORM查询
+2. 复杂查询需使用`selectinload`预加载关联对象
+3. 批量操作使用`bulk_create`/`bulk_update`优化性能
+4. 分页查询必须包含`offset`和`limit`参数
+
+---
+
+## API开发规范
+### 接口设计
+1. **RESTful规范**：
+   - 资源路径：`/api/v1/users/{id}`
+   - HTTP方法：GET/POST/PUT/PATCH/DELETE
+   - 响应格式：JSON（使用CamelCase字段名）
+
+2. **FastAPI示例**：
+   ```python
+   from fastapi import APIRouter, Depends, HTTPException
+   from pydantic import BaseModel
+
+   router = APIRouter()
+
+   class UserCreate(BaseModel):
+       email: str
+       password: str
+
+   @router.post("/users", status_code=201)
+   def create_user(user: UserCreate, db: Session = Depends(get_db)):
+       # 业务逻辑
+       return {"message": "User created"}
+   ```
+
+### 错误处理
+1. 统一使用HTTP状态码：
+   - 400：客户端错误（参数校验失败）
+   - 401：未认证
+   - 403：权限不足
+   - 404：资源不存在
+   - 500：服务器内部错误
+
+2. **全局异常捕获**（FastAPI）：
+   ```python
+   from fastapi import FastAPI, Request
+   from fastapi.exceptions import RequestValidationError
+   from starlette.exceptions import HTTPException as StarletteHTTPException
+
+   app = FastAPI()
+
+   @app.exception_handler(StarletteHTTPException)
+   async def http_exception_handler(request, exc):
+       return JSONResponse(
+           status_code=exc.status_code,
+           content={"detail": exc.detail}
+       )
+   ```
+
+---
+
+## 测试规范
+### 单元测试
+1. **pytest结构**：
+   ```python
+   # tests/test_users.py
+   from django.urls import reverse
+   import pytest
+
+   @pytest.mark.django_db
+   def test_user_creation(api_client):
+       response = api_client.post(reverse('user-list'), data={'email': 'test@example.com'})
+       assert response.status_code == 201
+   ```
+
+2. 覆盖率要求：核心模块≥80%，接口模块≥90%
+
+### 性能测试
+1. 使用Locust进行负载测试
+2. 关键接口响应时间≤200ms（复杂查询≤500ms）
+
+---
+
+## 安全规范
+1. **输入校验**：
+   - 所有用户输入必须通过Pydantic模型校验
+   - 敏感字段（如密码）使用`SecretStr`类型
+2. **XSS防护**：
+   - Django项目启用`escape`模板过滤器
+   - 使用CSP头限制资源加载
+3. **SQL注入防护**：
+   - 禁止使用`raw`查询（除非经过严格审核）
+   - 复杂查询必须通过参数化语句
+
+---
+
+## 部署规范
+### 环境管理
+1. 使用Ansible或Terraform进行基础设施管理
+2. 环境变量管理：通过`python-dotenv`加载
+3. 日志规范：
+   - 使用标准logging模块
+   - 格式：`%(asctime)s [%(levelname)s] %(name)s: %(message)s`
+   - 级别：生产环境设为WARNING，开发环境设为DEBUG
+
+---
+
+## 版本控制规范
+1. Git提交规范：
+   - 类型：feat/fix/chore/docs
+   - 格式：`<type>(<scope>): <subject>`
+   - 示例：`feat(user): add email verification`
+2. 必须通过PR进行代码审查
+3. 主分支禁止直接提交，必须通过CI/CD流水线
+
+---
+
+## 性能优化规范
+1. **数据库优化**：
+   - 复杂查询必须添加索引
+   - 使用`EXPLAIN ANALYZE`分析查询性能
+2. **缓存策略**：
+   - 使用Redis缓存高频查询
+   - 缓存键命名规范：`{module}:{id}:{field}`
+3. **异步处理**：
+   - 长任务使用Celery/RQ
+   - 同步代码中禁止阻塞操作
+
+---
+
+## 文档规范
+1. 使用Sphinx或mkdocs生成文档
+2. 所有公共API必须包含Swagger/OpenAPI文档
+3. 重大变更需更新CHANGELOG.md
+
+---
+
+## 代码审查规范
+1. 每个PR必须至少2人审查
+2. 代码复杂度（Cyclomatic）≤10
+3. 方法行数≤50行，类行数≤200行
+```
\ No newline at end of file