fastapi-best-practices_skill

Overview

This skill provides production-grade FastAPI best practices and actionable guidelines for building scalable, high-performance web APIs. It summarizes rules across async patterns, project structure, Pydantic modeling, dependency injection, database patterns, API design, and testing. Use it to standardize architecture and guide automated refactors or code generation.

How this skill works

The skill inspects common FastAPI concerns and maps them to concrete rules and prefixes (e.g., async-, structure-, pydantic-). It highlights when to use async vs sync, how to structure projects by domain, Pydantic model patterns, dependency chaining, and database/migration conventions. It also recommends testing and tooling choices to enforce consistency and performance in CI/CD.

When to use it

• Starting a new FastAPI service or refactor to production readiness
• Designing route handlers that mix async and blocking I/O
• Defining Pydantic models and global serialization behavior
• Architecting dependency injection for reusable validations and resources
• Integrating relational databases and defining migration strategies

Best practices

• Favor async def for I/O-bound endpoints; offload CPU work to workers or multiprocessing
• Organize code by domain (src/{domain}) rather than by file type to improve discoverability
• Use Pydantic BaseModels with shared custom base for serialization and BaseSettings per domain
• Prefer async dependencies and chain small, decoupled dependency units via Depends
• Adopt strict DB naming conventions, explicit index names, and SQL-first approach for complex logic
• Use AsyncClient/httpx for tests, Ruff for linting, and hide docs in production while enriching OpenAPI metadata

Example use cases

• Create a new FastAPI service with src/ directory split by domain and async endpoints for I/O-bound operations
• Wrap synchronous SDK calls with run_in_threadpool to avoid blocking the event loop
• Define a custom Pydantic base model to enforce global JSON encoders and consistent aliasing
• Chain dependencies to validate user permissions, load resources, and inject DB sessions cleanly
• Write migration-first SQL for complex queries and keep descriptive, reversible Alembic migrations