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）
定期重构改进代码质量