Python Backend Rules
Cursor backend development rules covering FastAPI, Django, database operations, and API design best practices.
【AI技能】Python Backend Rules：功能详解与安装指南
技能简介
如果你是一名 Python 后端开发者，是否遇到过这些场景：写 FastAPI 时重复编写同样的参数校验逻辑，用 Django 时纠结 ORM 查询优化，或者面对复杂 API 设计规范频频翻文档？Python Backend Rules 正是为解决这些痛点而生——它是一个专为 Cursor 编辑器设计的规则集，将 FastAPI、Django、数据库操作和 API 设计的最佳实践固化为一组可直接生效的 .cursorrules 文件。当你编写代码时，Cursor 会自动遵循这些规则，从代码生成、命名规范到性能优化，全程智能引导。
这套规则集不是简单的模板，而是融合了行业多年后端开发经验的“活文档”。无论你是刚接触 Python 后端的初学者，还是希望统一团队规范的老手，它都能帮你将注意力集中在业务逻辑上，而非重复的低级决策。
核心优势
开箱即用，无需记忆：无需翻看厚厚的官方文档或内部 wiki，规则直接嵌入编辑器。当你编写路由、模型或数据库查询时，Cursor 会即时提示最佳实践，比如使用 Pydantic v2 的
model_validator而非自定义校验，或者推荐 Django 的select_related和prefetch_related来减少 N+1 查询。覆盖主流框架，告别“选择困难”：规则集同时针对 FastAPI 和 Django 两大生态，且能智能识别上下文。编写 FastAPI 路径操作时自动建议依赖注入和响应模型；切换到 Django 模型定义时则自动约束字段类型和 Meta 选项。再也不用在两个框架的写法之间反复横跳。
内置数据库操作规范，防坑于未然：从 SQLAlchemy 的 session 管理到 Django ORM 的查询优化，规则包含常见的性能陷阱检查。例如，它会提醒避免在循环中执行数据库查询、强制使用批量操作、对密集查询添加缓存提示。这些经验教训通常需要踩坑多次才能积累。
API 设计一致性保障：规则集内置 RESTful API 设计规范，包括 URL 命名（/api/v1/resources/{id}）、HTTP 方法映射、状态码选择（201 创建、204 删除）、错误响应结构（统一返回 ValidationError 等异常类）。如果你参与过多人协作的后端项目，就知道统一 API 风格有多重要——规则集直接帮你强制执行。
持续更新，紧跟社区实践：规则集由社区维护，会跟随 FastAPI 0.115+、Django 5.1+ 的最新特性及时更新。例如，当 FastAPI 引入新的依赖注入语法时，规则会优先建议使用
Annotated类型而非旧式Depends。这意味着你永远在“最佳实践”的时间线上。
主要功能
| 功能分类 | 功能说明 |
|---|---|
| 框架感知的代码生成 | 在编写 FastAPI 或 Django 代码时自动启用对应规则，例如 FastAPI 路由自动添加 response_model 和 status_code；Django 视图自动应用 @require_http_methods |
| 数据库查询优化提示 | 检测并建议使用 select_related、prefetch_related 避免 N+1 查询；禁止在循环中执行 ORM 查询；对批量操作建议 bulk_create / bulk_update |
| API 设计规范强制 | 统一端点路径前缀（/api/v1/），约定参数命名风格（snake_case），强制返回标准错误格式（{"detail": ...}），规范分页参数（page, page_size） |
| 命名与结构约束 | 视图函数名采用 get/list/create/update/delete_* 模式；模型类名使用单数且首字母大写；定义项目目录结构（apps/, routes/, schemas/, services/） |
| 异常与日志规范 | 建议使用自定义异常类继承 HTTPException，日志输出需包含请求 ID 和耗时；禁止直接 print 打印，强制使用 logging 模块 |
| 安全与权限检查 | 自动建议 FastAPI 路由添加 Security / Depends 认证；Django 视图添加 permission_required 装饰器；鼓励使用 @csrf_exempt 的明确豁免而非全局关闭 |
如何获取与安装
Python Backend Rules 是 Cursor 编辑器的规则集配置，安装过程非常简单：
1. 获取规则文件
访问官方 GitHub 仓库（演示地址：https://github.com/cursor-rules/python-backend-rules），下载 python-backend-rules/.cursorrules 文件。如果你熟悉 Git，也可以直接 clone：
git clone https://github.com/cursor-rules/python-backend-rules.git
2. 复制到项目根目录
将下载的 .cursorrules 文件放置在你 Python 后端项目的根目录下。注意：文件名必须为 .cursorrules，Cursor 会自动识别并加载该文件。
cd your-project/
cp /path/to/python-backend-rules/.cursorrules ./
3. （可选）根据项目定制规则
.cursorrules 是一个纯文本文件，格式类似 YAML/JSON 混合体（Cursor 规则定义格式）。你可以根据项目实际需求修改规则，例如调整 API 版本号、变更命名风格（snake_case 与 camelCase 之间切换）、添加公司专属的安全校验逻辑等。
4. 验证生效
重启 Cursor 或重新打开项目，在任意 .py 文件中编写代码。当你输入 @app.get 或 class mymodel 等触发词时，如果看到 Cursor 的补全建议和代码片段开始遵循规则（例如自动生成 async def get_... 而非 def，或者模型类名自动建议首字母大写），说明规则已成功应用。
小提示：如果规则未生效，请确认文件名为
.cursorrules（注意前面有点号），且位于项目根目录。Windows 用户可能需要通过命令行修改文件名或使用支持隐藏文件的文本编辑器。
适用场景
- 新项目初始化：搭建 FastAPI 或 Django 项目时，直接套用规则集，从第一行代码就遵循最佳实践，避免后期重构。
- 团队协作项目：多个开发者共同维护的后端项目，规则集可作为“活的代码规范”，确保每个人输出一致的 API 风格、数据库操作方式和错误处理模式。
- 代码审查与质量提升：对已有项目应用规则，Cursor 会在编写时标出不符合规范的地方（如缺少依赖注入、ORM 查询低效），辅助开发者快速修正。
- 学习最佳实践：初级后端开发者可以在规则引导下学习 FastAPI/Django 的惯用写法，缩短从入门到“写好”的路径。
- 微服务与多项目统一：在多个微服务项目中统一使用同一套规则，减少跨项目协作时的认知成本。
小贴士
- 结合 AI 补全使用：规则集与 Cursor 的 AI 补全相辅相成。建议在补全后通过规则提示二次检查，例如 AI 可能生成未添加缓存的查询，规则会自动高亮提醒优化。
- 定期升级规则：后端生态发展快，建议每季度检查一次规则仓库更新。关注 FastAPI 和 Django 的发布说明，如果规则集未及时更新，可先在
.cursorrules中手动添加临时规则（如"deprecated": ["Depends", "old_style"]）。 - 与 .gitignore 配合：如果不想让
.cursorrules进入 git 仓库（团队规范强的话建议提交），可以在.gitignore中加入.cursorrules。但更推荐将其纳入版本控制，以便团队成员共享。
免责声明：本技能效果可能因 Cursor 版本和规则文件格式差异而略有不同，请以官方文档为准。规则集仅为辅助工具，建议结合官方框架文档进行二次确认。