211 lines
5.9 KiB
Markdown
211 lines
5.9 KiB
Markdown
你是一名资深全栈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行
|
||
``` |