cursor-fastapi

Cursor IDE 快速 API 开发规则 1. 项目结构规范 - 使用标准 FastAPI 项目布局，推荐目录结构如下： ``` project/ ├── app/ │ ├── __init__.py │ ├── main.py │ ├── api/ │ │ ├── __init__.py │ │ └── v1/ │ │ ├── __init__.py │ │ └── endpoints/ │ │ ├── __init__.py │ │ └── items.py │ ├── core/ │ │ ├── config.py │ │ └── security.py │ ├── models/ │ │ └── __init__.py │ ├── schemas/ │ │ └── __init__.py │ └── db/ │ └── session.py └── requirements.txt ``` 2. 代码风格与格式 - 遵循 PEP 8 编码规范 - 使用类型注解（Type Hints）提升可读性和 IDE 支持 - 路由函数命名采用小写加下划线（如 `get_user_by_id`） - Pydantic 模型命名使用大驼峰（如 `UserCreate`） 3. 路由组织 - 按功能模块拆分路由文件（如 users.py、items.py） - 使用 `APIRouter` 组织版本化 API（如 `/api/v1/users`） - 为每个路由添加清晰的 OpenAPI 文档说明（summary、description） 4. 依赖注入 - 利用 FastAPI 的 `Depends` 实现依赖管理 - 数据库会话、认证逻辑等通过依赖注入解耦 - 避免在路由函数中直接实例化服务或数据库连接 5. 错误处理 - 自定义异常处理器（如 `HTTPException`） - 统一错误响应格式（包含 error_code、message、detail） - 使用中间件捕获未处理异常并记录日志 6. 配置管理 - 使用环境变量加载配置（推荐 `pydantic-settings`） - 区分开发、测试、生产环境配置 - 敏感信息（如密钥、数据库密码）不得硬编码 7. 数据库交互 - 推荐使用 SQLAlchemy ORM + Alembic 迁移 - 所有数据库操作封装在 service 层 - 使用异步数据库驱动（如 asyncpg）提升性能 8. 测试规范 - 编写单元测试和集成测试（pytest） - 使用 TestClient 模拟 HTTP 请求 - 覆盖主要业务逻辑和边界条件 9. 文档与调试 - 启用自动生成的 Swagger UI（/docs）和 ReDoc（/redoc） - 为所有 API 端点添加详细的参数说明和示例 - 使用 Cursor IDE 的调试功能设置断点排查问题 10. 性能优化 - 启用 GZipMiddleware 压缩响应 - 对耗时操作使用后台任务（BackgroundTasks） - 合理使用缓存（如 Redis）减少重复计算 11. 安全实践 - 实施身份验证（OAuth2、JWT） - 输入数据严格校验（Pydantic 模型） - 防止常见漏洞（SQL 注入、XSS、CSRF） 12. 日志记录 - 配置结构化日志输出 - 记录关键操作和异常信息 - 集成日志收集系统（如 ELK、Sentry） 遵循以上规则可确保 FastAPI 项目在 Cursor IDE 中高效开发、易于维护且具备良好的可扩展性。

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本