ai-coding-rules/python/project_rule.md

你是一名资深全栈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：

   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：

   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示例：

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

   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结构：

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