后端开发规则（fastapi）

• 您是一位精通 Python、FastAPI 和可扩展 API 开发的专家。

关键原则

• 编写简洁、技术性的回复，并提供准确的 Python 示例。

• 使用函数式、声明式编程；尽可能避免使用类。

• 优先使用迭代和模块化，避免代码重复。

• 使用带有辅助动词的描述性变量名（例如 is_active、has_permission）。

• 目录和文件使用小写字母和下划线（例如 routers/user_routes.py）。

• 优先使用命名导出路由和工具函数。

• 使用“接收对象，返回对象”（RORO）模式。

• 目录结构采用

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

  backend/ ├── api/ # API路由层 ├── __init__.py # 创建FastAPI应用实例，注册路由 └── v1/ # API版本1 ├── __init__.py # 注册v1版本的所有路由 └── endpoints/ # 具体的端点模块 ├── login/ # 登录相关接口 ├── user/ # 用户管理接口 ├── role/ # 角色管理接口 └── permission/ # 权限管理接口 ├── controllers/ # 业务逻辑控制器层 ├── services/ # 算法等 ├── core/ # 核心功能模块 ├── security.py # JWT认证、用户身份验证、OAuth2配置 ├── crud.py # 通用CRUD操作基类 ├── dependencies.py # FastAPI依赖注入函数 ├── models/ # 数据库模型层 ├── schemas/ # 数据验证和序列化层 ├── settings/ ├── config.py # 配置管理，数据库连接配置，JWT密钥和算法配置，应用程序环境变量，第三方服务配置等 ├── utils/ # 工具函数库，密码加密和验证，JWT令牌生成和解析，数据序列化工具，其他通用工具函数 ├── main.py # 应用入口文件 └── __init__.py # 包初始化文件

Python/FastAPI

• 使用 def 定义纯函数，使用 async def 定义异步操作。
• 为所有函数签名使用类型提示。优先使用 Pydantic 模型而不是原始字典进行输入验证。
• 文件结构：导出的路由器、子路由、工具函数、静态内容、类型（模型、模式）。
• 避免在条件语句中使用不必要的大括号。
• 对于条件语句中的单行语句，省略大括号。
• 对于简单的条件语句，使用简洁的单行语法（例如 if condition: do_something()）。

错误处理和验证

• 优先处理错误和边缘情况：
  • 在函数开头处理错误和边缘情况。
  • 使用提前返回来处理错误条件，避免深度嵌套的 if 语句。
  • 将正常路径放在函数末尾，以提高可读性。
  • 避免不必要的 else 语句；使用 if-return 模式。
  • 使用守卫子句提前处理前提条件和无效状态。
  • 实现适当的错误日志记录和用户友好的错误消息。
  • 使用自定义错误类型或错误工厂进行一致的错误处理。

依赖项

• FastAPI
• Pydantic v2
• 异步数据库库，如 asyncpg 或 aiomysql
• SQLAlchemy 2.0（如果使用 ORM 功能）

FastAPI 特定指南

• 使用函数式组件（普通函数）和 Pydantic 模型进行输入验证和响应模式。
• 使用声明式路由定义，并带有清晰的返回类型注解。
• 使用 def 定义同步操作，使用 async def 定义异步操作。
• 尽量减少 @app.on_event("startup") 和 @app.on_event("shutdown") 的使用；优先使用生命周期上下文管理器来管理启动和关闭事件。
• 使用中间件进行日志记录、错误监控和性能优化。
• 使用异步函数优化 I/O 密集型任务的性能，使用缓存策略和延迟加载。
• 使用 HTTPException 处理预期错误，并将其建模为特定的 HTTP 响应。
• 使用中间件处理意外错误、日志记录和错误监控。
• 使用 Pydantic 的 BaseModel 进行一致的输入/输出验证和响应模式。

性能优化

• 尽量减少阻塞 I/O 操作；对所有数据库调用和外部 API 请求使用异步操作。
• 使用 Redis 或内存存储等工具为静态和频繁访问的数据实现缓存。
• 使用 Pydantic 优化数据序列化和反序列化。
• 对大数据集和大量 API 响应使用延迟加载技术。

关键约定

1. 依赖 FastAPI 的依赖注入系统来管理状态和共享资源。
2. 优先考虑 API 性能指标（响应时间、延迟、吞吐量）。
3. 限制路由中的阻塞操作：
   • 优先使用异步和非阻塞流程。
   • 使用专用的异步函数进行数据库和外部 API 操作。
   • 清晰构建路由和依赖关系，以优化可读性和可维护性。

有关最佳实践，请参考 FastAPI 文档中的“数据模型”、“路径操作”和“中间件”部分。

数据库

• 数据库使用mysql，数据库相关配置在settings目录的config.py文件进行操作。

• 使用tortoseorm进行数据库操作

• 要求必须使用一下的数据库迁移命令，不能够使用py自动执行迁移

1
2
3
4
5
6
7

aerich init-db

aerich migrate

aerich upgrade

aerich init -t backend.settings.config.TORTOISE_ORM --location ./backend/migrations