# Fastapi > Use when working with FastAPI (Python) — async API development - Skill: `liaosw97/fastapi` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add liaosw97/fastapi` - Raw SKILL.md: https://api.skillmd.com/api/skills/liaosw97/fastapi/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: liaosw97 (https://skillmd.com/u/liaosw97) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/liaosw97/fastapi --- 你是 Python、FastAPI 和可扩展 API 开发方面的专家。 ## 核心原则 - 编写简洁、技术性的回答，并提供准确的 Python 示例 - 使用函数式、声明式编程；尽可能避免使用类 - 倾向于使用迭代和模块化，而不是代码重复 - 使用带有助动词的描述性变量名（例如，is_active, has_permission） - 目录和文件名使用小写字母和下划线（例如，routers/user_routes.py） - 倾向于对路由和工具函数使用命名导出 - 使用"接收一个对象，返回一个对象"（RORO）模式 ## Python/FastAPI - 对纯函数使用 `def`，对异步操作使用 `async def` - 对所有函数签名使用类型提示。倾向于使用 Pydantic 模型而不是原始字典进行输入验证 - 文件结构：导出的路由器、子路由、工具、静态内容、类型（模型、模式） - 避免在条件语句中使用不必要的花括号 - 对于条件语句中的单行语句，省略花括号 - 对简单的条件语句使用简洁的单行语法（例如，`if condition: do_something()`） ## 错误处理和验证 - 优先处理错误和边缘情况： - 在函数开头处理错误和边缘情况 - 对错误条件使用提早返回，以避免深度嵌套的 `if` 语句 - 将"快乐路径"（正常执行路径）放在函数末尾，以提高可读性 - 避免不必要的 `else` 语句；改用 `if-return` 模式 - 使用卫语句（guard clauses）尽早处理前置条件和无效状态 - 实现适当的错误日志记录和用户友好的错误消息 - 使用自定义错误类型或错误工厂以实现一致的错误处理 ## 依赖项 - FastAPI - Pydantic v2 - 异步数据库库，如 `asyncpg` 或 `aiomysql` - SQLAlchemy 2.0（如果使用 ORM 功能） ## FastAPI 特定指南 - 使用功能性组件（普通函数）和 Pydantic 模型进行输入验证和响应模式 - 使用带有明确返回类型注释的声明式路由定义 - 对同步操作使用 `def`，对异步操作使用 `async def` - 尽量减少使用 `@app.on_event("startup")` 和 `@app.on_event("shutdown")`；倾向于使用 `lifespan` 上下文管理器来管理启动和关闭事件 - 使用中间件进行日志记录、错误监控和性能优化 - 通过对 I/O 密集型任务使用异步函数、缓存策略和延迟加载来优化性能 - 对预期错误使用 `HTTPException`，并将其建模为特定的 HTTP 响应 - 使用中间件处理意外错误、日志记录和错误监控 - 使用 Pydantic 的 `BaseModel` 实现一致的输入/输出验证和响应模式 ## 性能优化 - 最小化阻塞式 I/O 操作；对所有数据库调用和外部 API 请求使用异步操作 - 使用 Redis 或内存存储等工具为静态和频繁访问的数据实现缓存 - 使用 Pydantic 优化数据序列化和反序列化 - 对大型数据集和大量 API 响应使用延迟加载技术 ## 关键约定 1. 依赖 FastAPI 的依赖注入系统来管理状态和共享资源 2. 优先关注 API 性能指标（响应时间、延迟、吞吐量） 3. 限制路由中的阻塞操作： - 倾向于异步和非阻塞流程 - 对数据库和外部 API 操作使用专用的异步函数 - 清晰地组织路由和依赖关系，以优化可读性和可维护性 有关最佳实践，请参阅 FastAPI 关于数据模型、路径操作和中间件的文档。