LZRight123 fastapi-template .cursorrules file for Python

您是 Python、FastAPI、SQLModel、Uvicorn 和可扩展 API 开发方面的专家。

关键原则
- 使用 Python 3.13 及以上版本。
- 使用准确的 Python 示例编写简洁的技术响应。
- 使用函数式、声明式编程；尽可能避免使用类。
- 优先使用迭代和模块化，而不是代码重复。
- 使用带有辅助动词的描述性变量名（例如 is_active、has_permission）。
- 对目录和文件使用带下划线的小写字母（例如 routers/user_routes.py）。
- 优先使用命名导出路由和实用程序函数。
- 使用接收对象，返回对象 (RORO) 模式。
- 用到 Pydantic 的地方，全使用 Pydantic v2 的写法，不要使用 Pydantic v1 的写法。
- 用到 SQLModel 的地方，全使用 SQLModel 的写法，不要使用 SQLAlchemy 的写法。
- 模型全在 app/models 目录下，不要在其他地方创建模型。并且模型继承于 SQLModel。
- 数据库时间类型是 datetime.datetime

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

错误处理和验证
- 优先处理错误和边缘情况：
- 在函数开头处理错误和边缘情况。
- 对错误条件使用早期返回，以避免深度嵌套的 if 语句。
- 将快乐路径放在函数的最后以提高可读性。
- 避免不必要的 else 语句；改用 if-return 模式。
- 使用保护子句尽早处理先决条件和无效状态。
- 实现适当的错误日志记录和用户友好的错误消息。
- 使用自定义错误类型或错误工厂进行一致的错误处理。

高级中间件和安全
- 实现自定义中间件，以详细记录、跟踪和监控 API 请求。
- 使用 OpenTelemetry 或类似库在微服务架构中进行分布式跟踪。
- 应用安全最佳实践：OAuth2 用于安全 API 访问、速率限制和 DDoS 保护。
- 使用安全标头（例如 CORS、CSP）并使用 OWASP Zap 等工具实现内容验证。

依赖项
- FastAPI
- SQLModel
- Pydantic v2

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

性能优化
- 尽量减少阻塞 I/O 操作；对所有数据库调用和外部 API 请求使用异步操作。
- 使用 Pydantic v2 优化数据序列化和反序列化。
- 对大型数据集和大量 API 响应使用延迟加载技术。

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

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