Cursor 里用 FastAPI 规则：从 awesome-cursorrules 抄什么、删什么

社区 py-fast-api.mdc 把 Pydantic v2、async 路由、lifespan、依赖注入写进 Cursor 规则。本文按原文提炼可执行约定，并说明 globs 怎么收、和项目结构怎么对齐。

Cursor FastAPI 规则：Pydantic v2、async 与 lifespan 约定

Python 后端用 Cursor 时，Agent 很爱写出「能跑的玩具 API」：同步函数里打数据库、用裸 dict 当入参、还在 @app.on_event("startup") 里挂资源。社区列表 awesome-cursorrules 里多份 FastAPI 规则都在压这些习惯；本文以较精简的 py-fast-api.mdc 为准，讲抄哪些、删哪些。

通用装法见 awesome-cursorrules 怎么用。前端 Next 栈可看 Next.js 15 + Supabase 规则。

五分钟装上

  1. 复制 py-fast-api.mdc 到项目 .cursor/rules/。
  2. 把 frontmatter 的 globs 从 **/* 收到 Python 相关路径，例如 **/*.py 或 app/**/*.py, routers/**/*.py。
  3. alwaysApply 保持 false，除非你真要每条对话都注入整份后端规范。
  4. 给 Agent 一个小任务：「加一个带 Pydantic 入参的 GET，并写类型注解」，看输出是否跟规则一致。

值得留下的硬约定

规则把角色定成「Python / FastAPI / 可扩展 API」专家，并点名依赖：FastAPI、Pydantic v2、asyncpg/aiomysql、可选 SQLAlchemy 2.0。和项目不符的依赖名，装之前先改掉或删掉，避免 Agent 主动 pip install 你没用的栈。

  • 类型与校验：函数签名写 type hints；入参/出参用 Pydantic 模型，少用裸字典。
  • 同步 vs 异步：纯计算可用 def；数据库和外部 HTTP 用 async def，别在路由里阻塞 I/O。
  • 生命周期：少用 @app.on_event("startup") / shutdown，改用 lifespan 上下文管理资源。
  • 错误处理：预期错误用 HTTPException；先处理边界再走 happy path；依赖注入管理共享状态。
  • 目录命名：小写加下划线（如 routers/user_routes.py），和「看见啥目录就生成啥」的 Agent 习惯对齐。

建议删掉或改写的部分

原文有一条「avoid classes where possible / 偏函数式」。若你们仓库已经是 class-based service / repository，整段删掉或改成「沿用现有分层，不要为了规则新建一套函数式结构」。否则 Agent 会在 PR 里「重构式」重写，diff 巨大且难审。

「RORO（Receive an Object, Return an Object）」同样：团队没有这个约定就去掉，留下 Pydantic + 依赖注入通常就够。

性能段里的 Redis 缓存、懒加载——没有基础设施就别留，免得 Agent 每次加接口都顺手提 Redis。

和仓库里其它 FastAPI 规则怎么选

同一 Awesome 仓库里还有 python-fastapi-best-practices-...、fastapi-production-architecture-... 等更长变体，强调 router/service/repository、幂等、领域异常。绿场大服务可以读 production 那份；已有中小 API、只想纠正 async / Pydantic / lifespan，py-fast-api.mdc 更合适。

一次只启用一份主 FastAPI 规则，再按需追加「禁止提交密钥」这类短安全规则。两份长文同时 alwaysApply，上下文会被人格设定占满。

验收时盯什么

让 Agent 新增一个路由后，打开 diff 看四点：有没有 Pydantic 模型；I/O 是否 async；有没有又写出 on_event；有没有乱建你禁掉的目录。过了这四关，规则才算真的在干活。Agent 模式边界见 Agent 入门；Rules 与 Skills 分工见 工作流总览。

社区规则是别人的口味清单。对齐依赖、收紧 globs、删掉和仓库冲突的教条——留下的那几条，才值得让 Cursor 每轮记住。