FastAPI Best Practices

Comprehensive production-grade best practices for FastAPI applications. Contains rules across 7 categories to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Setting up a new FastAPI project structure
• Implementing async routes and handling blocking I/O
• Designing Pydantic models and validation logic
• Structuring dependencies for reusable validation and injection
• Integrating databases with SQLAlchemy and Alembic
• Writing tests and configuring CI/CD tooling

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Async & Concurrency	CRITICAL	async-
2	Project Structure	HIGH	structure-
3	Pydantic Patterns	HIGH	pydantic-
4	Dependency Injection	MEDIUM-HIGH	dependency-
5	Database & Storage	MEDIUM	db-
6	REST & API Design	MEDIUM	api-
7	Testing & Tooling	LOW-MEDIUM	tooling-
8	Code Maintenance	LOW	maintenance-
9	Performance Optimization	MEDIUM	performance-
10	TDD Strategy	HIGH	tdd-

Quick Reference

1. Async & Concurrency (CRITICAL)

• async-io-intensive - Use async def for awaitables, def for blocking I/O
• async-cpu-intensive - Offload CPU work to multiprocessing/Celery
• async-sync-sdk - Use run_in_threadpool for sync SDKs in async routes

2. Project Structure (HIGH)

• structure-domain-driven - Organize by domain (src/{domain}), not file type

3. Pydantic Patterns (HIGH)

• pydantic-validation - Use built-in regex, enums, etc.
• pydantic-custom-base - Use custom base model for global serialization
• pydantic-config - Split BaseSettings by domain
• pydantic-value-error - Raise ValueError for validation errors

4. Dependency Injection (MEDIUM-HIGH)

• dependency-validation - Use Depends for DB-backed validation
• dependency-chaining - Chain dependencies for reuse
• dependency-decoupling - Decouple into small reusable units
• dependency-async - Prefer async dependencies

5. Database & Storage (MEDIUM)

• db-naming-conventions - Strict naming (snake_case, singular, etc.)
• db-index-naming - Explicit index naming conventions
• db-sql-first - Prefer SQL for complex data logic
• db-migrations - Static, descriptive, reversible migrations

6. REST & API Design (MEDIUM)

• api-path-naming - Consistent path vars for dependency reuse
• api-response-serialization - Minimize serialization overhead
• api-docs-hiding - Hide docs in production
• api-docs-customization - Detailed OpenAPI metadata

7. Testing & Tooling (LOW-MEDIUM)

• tooling-test-client - Use AsyncClient/httpx for tests
• tooling-linter - Use Ruff for all linting

8. New Capabilities (Merged)

• Scripts: Helper scripts available in scripts/ (e.g., run_ruff.py).
• References: Additional guides in references/ (e.g., quad_strategy.md).
• TDD: Explicit testing strategies in rules/tdd-strategy.md.

How to Use

Read individual rule files for detailed explanations and code examples:

rules/async-io-intensive.md
rules/structure-domain-driven.md

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md