---
description: Python 后端项目的编码标准和最佳实践
---

**使用中文与用户对话**

# Python 后端开发规范

## 项目结构
- 所有后端代码位于 `backend` 目录
- 主应用入口为 `backend/main.py`
- 数据库模型定义在 `backend/models.py`
- 数据库连接配置在 `backend/database.py`
- 遵循既定的目录结构：
  - `routers/`: API 路由定义
  - `schemas/`: Pydantic 数据模型和验证
  - `services/`: 业务逻辑层
  - `test/`: **所有测试文件必须保存在此文件夹中**
  - `__pycache__/`: Python 缓存文件（自动生成）

## 测试文件管理
- **重要：所有测试文件必须保存在 `./backend/test` 文件夹中**
- 测试文件命名使用 `test_*.py` 格式
- 测试文件结构应与被测试的模块结构对应
- 不要在项目其他位置创建测试文件，防止到处拉屎
- 示例：
  - 测试 `routers/users.py` → `test/test_routers_users.py`
  - 测试 `services/annotation.py` → `test/test_services_annotation.py`

## 代码风格
- 遵循 PEP 8 编码规范
- 使用 4 个空格缩进，不使用制表符
- 行长度限制为 88 字符（Black 格式化器标准）
- 使用有意义的变量和函数名称
- 类名使用 PascalCase
- 函数和变量名使用 snake_case
- 常量使用 UPPER_CASE

## FastAPI 最佳实践
- 使用路由器（APIRouter）组织 API 端点
- 使用 Pydantic 模型进行请求和响应验证
- 使用依赖注入（Depends）管理数据库会话和认证
- 为所有端点添加适当的 HTTP 状态码
- 使用类型提示提高代码可读性
- 添加详细的 API 文档字符串

## 数据库操作
- 使用 SQLAlchemy ORM 进行数据库操作
- 在 `models.py` 中定义数据库模型
- 使用 Alembic 进行数据库迁移
- 始终使用数据库会话上下文管理器
- 避免 N+1 查询问题，使用 joinedload 或 selectinload
- 为查询添加适当的索引

## 错误处理
- 使用 FastAPI 的 HTTPException 处理 HTTP 错误
- 创建自定义异常类处理业务逻辑错误
- 使用 try-except 块捕获和处理异常
- 记录错误信息以便调试
- 返回用户友好的错误消息
- 不要暴露敏感的系统信息

## 安全性
- 使用环境变量存储敏感配置（参考 `.env.example`）
- 实现适当的身份验证和授权机制
- 使用 CORS 中间件控制跨域访问
- 验证和清理所有用户输入
- 使用参数化查询防止 SQL 注入
- 实现速率限制防止滥用

## 依赖管理
- 在 `requirements.txt` 中列出所有依赖
- 使用虚拟环境隔离项目依赖
- 固定依赖版本以确保可重现性
- 定期更新依赖以修复安全漏洞

## 代码组织
- 保持函数简短且专注于单一职责
- 将复杂的业务逻辑提取到 `services` 层
- 使用 `schemas` 定义数据传输对象（DTO）
- 路由处理器应该简洁，主要负责请求/响应处理
- 避免在路由中直接编写业务逻辑

## 异步编程
- 对 I/O 密集型操作使用 async/await
- 使用异步数据库驱动（如 asyncpg）
- 避免在异步函数中使用阻塞操作
- 使用 asyncio 工具管理并发任务

## 日志记录
- 使用 Python 的 logging 模块
- 为不同环境配置不同的日志级别
- 记录重要的业务操作和错误
- 避免记录敏感信息（密码、令牌等）
- 使用结构化日志便于分析

## 性能优化
- 使用数据库连接池
- 实现适当的缓存策略
- 对昂贵的操作使用后台任务
- 使用分页处理大量数据
- 监控和优化慢查询

## 文档
- 为所有公共函数和类添加文档字符串
- 使用 FastAPI 的自动文档功能
- 在 README.md 中提供清晰的设置说明
- 记录 API 端点的用途和参数
- 保持文档与代码同步更新

## 最佳实践
- 编写清晰、可读的代码
- 遵循 DRY（Don't Repeat Yourself）原则
- 使用类型提示提高代码质量
- 编写单元测试和集成测试
- 进行代码审查
- 使用版本控制（Git）
- 定期重构改进代码质量