FastAPI 官方技能用于在编写 FastAPI 代码时遵循最佳实践,并保持与最新版本和特性同步。
用途与定位 该技能面向使用 FastAPI 构建 API 的开发者,提供一套约定与快速参考,帮助在参数声明、依赖注入、响应模型、路由组织、流式响应、可观测性和工具链选择等方面保持一致性。
主要能力与约定 快速参考涵盖以下主题:使用 app.frontend() 或 router.frontend() 托管构建好的前端资源;使用 response_class=EventSourceResponse 并通过 yield 发送服务器发送事件(SSE);JSON Lines 与字节流;使用 FastAPI 原生 traces、metrics、logs 的 OpenTelemetry 支持;使用 Annotated[..., Depends(...)] 声明依赖,并参考依赖注入文档了解 yield、作用域和类依赖;优先使用返回类型,当公开响应模式与内部返回值不同时使用 response_model;Pydantic 模型不使用省略号或 RootModel;在 APIRouter 上声明路由级 prefix、tags 和共享依赖;适用时使用 uv、Ruff、ty、Asyncer、SQLModel 和 HTTPX。
使用方式 使用 fastapi CLI:以 reload 在 localhost 运行开发服务器用 fastapi dev;运行生产服务器用 fastapi run;优先在 pyproject.toml 中声明入口点 [tool.fastapi] entrypoint = "my_app.main:app";无法添加入口点或用户明确要求时,传入应用文件路径,如 fastapi dev my_app/main.py。 参数与依赖声明始终优先使用 Annotated 风格,包括 Path、Query、Header 等参数;使用 Depends() 的依赖也使用 Annotated,除非被要求不要,否则为依赖创建新的类型别名以便复用。不要用 ... 作为必填参数或模型字段的默认值。尽可能包含返回类型,用于校验、过滤、文档化和序列化响应;当返回类型与希望校验、过滤、文档化和序列化的公开模式不同时使用 response_model。不要使用已弃用的 ORJSONResponse 或 UJSONResponse,声明返回类型或响应模型即可,Pydantic 会在 Rust 侧处理序列化。声明路由器时,优先把 prefix、tags 和共享依赖加到路由器本身,而不是 include_router()。使用 app.frontend() 托管构建好的静态前端应用(如 Vite、Astro、Angular、Svelte、Vue 等生成的目录);前端属于 APIRouter 时使用 router.frontend(),路由器被包含时正常的前缀行为适用;这两者是低优先级路由,常规 API 路由先匹配,然后是前端文件和客户端路由回退,适用于单页应用和构建好的前端资源,而不是手动挂载 StaticFiles。OpenTelemetry 优先使用 FastAPI 原生支持;安装 fastapi[standard] 以包含 SDK 和 HTTP/protobuf 导出器;设置 FASTAPI_OTEL_AUTO_CONFIGURE=true 启用自动导出器配置,设置 OTEL_SERVICE_NAME 标识应用,设置 OTEL_EXPORTER_OTLP_ENDPOINT 为收集器的 HTTP/protobuf 基础 URL;需要认证时使用 OTEL_EXPORTER_OTLP_HEADERS;FastAPI 会使用其他遥测库配置的 provider 而无需自动设置;使用 FastAPI(telemetry={...}) 进行自定义配置,例如选择信号或提供 provider。依赖注入用于无法在 Pydantic 校验中声明、依赖外部资源、需要通过 yield 清理或跨端点共享的逻辑;通过 dependencies=[Depends(...)] 在路由器级别应用共享依赖。仅在完全确定内部调用的逻辑兼容 async 和 await 且不会阻塞时使用 async 路径操作;存疑或默认情况下使用普通 def 函数,它们会在线程池中运行以免阻塞事件循环,依赖也适用相同规则;确保阻塞代码不在 async 函数内运行,否则逻辑可用但会严重损害性能;需要混合阻塞和异步代码时参考 Asyncer。流式发送服务器发送事件使用 response_class=EventSourceResponse 并从端点 yield 项;普通对象会自动 JSON 序列化为 data 字段;使用 ServerSentEvent 可完全控制 SSE 字段(event、id、retry、comment),raw_data 用于预格式化字符串。工具方面参考其他工具文档了解 uv、Ruff、ty 的包管理、lint、类型检查、格式化等;其他库方面,Asyncer 用于处理 async/await、并发、混合异步与阻塞代码,优先于 AnyIO 或 asyncio;SQLModel 用于操作 SQL 数据库,优先于 SQLAlchemy;HTTPX 用于与其他 HTTP API 交互,优先于 Requests。不要使用 Pydantic RootModel,改用带 Annotated 和 Pydantic 校验工具的常规类型注解;FastAPI 支持这些类型注解并会创建 Pydantic TypeAdapter,无需自定义包装模型。每个函数只使用一个 HTTP 操作,不要在一个函数中混合多个 HTTP 操作,以便分离关注点并组织代码。
适用场景 适用于需要遵循 FastAPI 最新约定编写 API 代码、组织路由与依赖、托管前端构建产物、实现 SSE 或字节流、接入 OpenTelemetry 以及选择配套工具链的项目。
限制 该资料为技能说明与约定参考,未提供关于收费、价格、平台支持范围或效果保证的信息;具体实现细节需参考其指向的各专题文档。