fastapi-best-practices

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

FastAPI production-grade best practices and guidelines for building scalable, high-performance web APIs. Covers project structure, async concurrency, Pydantic validation, dependency injection, and database patterns.

1installs

Sourceahmed6ww/ax-agents

Added on2026-02-22

NPX Install

npx skill4agent add ahmed6ww/ax-agents fastapi-best-practices

SKILL.md Content

View Translation Comparison →

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


async-
structure-
pydantic-
dependency-
db-
api-
tooling-
maintenance-
performance-
tdd-

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

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


async-
structure-
pydantic-
dependency-
db-
api-
tooling-
maintenance-
performance-
tdd-

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

fastapi-best-practices

NPX Install

Tags

SKILL.md Content

FastAPI Best Practices

When to Apply

Rule Categories by Priority

Quick Reference

1. Async & Concurrency (CRITICAL)

2. Project Structure (HIGH)

3. Pydantic Patterns (HIGH)

4. Dependency Injection (MEDIUM-HIGH)

5. Database & Storage (MEDIUM)

6. REST & API Design (MEDIUM)

7. Testing & Tooling (LOW-MEDIUM)

8. New Capabilities (Merged)

How to Use

Full Compiled Document

fastapi-best-practices

NPX Install

Tags

SKILL.md Content

FastAPI Best Practices

When to Apply

Rule Categories by Priority

Quick Reference

1. Async & Concurrency (CRITICAL)

2. Project Structure (HIGH)

3. Pydantic Patterns (HIGH)

4. Dependency Injection (MEDIUM-HIGH)

5. Database & Storage (MEDIUM)

6. REST & API Design (MEDIUM)

7. Testing & Tooling (LOW-MEDIUM)

8. New Capabilities (Merged)

How to Use

Full Compiled Document